Workbuddy、Trae、Pi等 AI 代理的能力日新月异，不拥抱 AI 迟早会被淘汰，所以研究一下开源的 Pi 代理的使用方法。

安装部署

Pi代理具体安装部署请参考：

• 离线部署AI_Agent的方法

扩展安装

记录在不同领域需要安装的扩展。

安装方法

打开命令提示符，输入如下命令：

1

pi install npm:extension_name

大模型接入扩展

• pi-cn-free-model-providers

让 pi（AI 编码助手 CLI）面向中国大陆用户，通过原生通道接入多个免费/低成本模型供应商，包括 OpenCode Zen、SenseNova、SiliconFlow、ModelScope、NVIDIA NIM、AMD Radeon Cloud、Cloudflare 和 Agnes AI。各平台政策可能变化，模型会自动进行实时目录校验。

1

pi install npm:pi-cn-free-model-providers

办公领域

• pi-subagents

办公多任务拆分核心。把「汇总多份文档 + 写 PPT 大纲 + 整理待办」拆成多个子 Agent 并行处理，适合批量材料、报告撰写。

1

pi install npm:pi-subagents

• rpiv-todo（@juicesharp/rpiv-todo）

持久化待办清单，会话压缩、重启后任务不丢失。周报、项目跟进、多阶段公文任务必备，支持 /todos 查看任务面板Pi

1

pi install npm:@juicesharp/rpiv-todo

• pi-web-access

网页检索、URL 抓取、PDF 解析一体。阅读合同、政策文件、参考资料；自带 OCR，支持扫描版文档提取文字。办公文档处理头号扩展。

1

pi install npm:pi-web-access

• @gotgenes/pi-permission-system（bash-guard）

权限防护扩展。对删除、覆盖文件、批量修改文档等高风险操作弹窗确认，防止误删合同、报表，办公环境安全底线。

1

pi install npm:@gotgenes/pi-permission-system

开发领域

• pi-lens

核心开发扩展，接入 LSP、linters、类型检查、代码静态扫描；每次修改代码自动做语法 / 类型校验，让 Agent 写完代码立刻自检，减少低级 bug，C++/TS/Python 都适用Pi

1

pi install npm:pi-lens

• pi-hashline-edit-pro

增强文件编辑工具，基于行哈希定位修改，避免模糊匹配改错代码；支持跨会话撤销，多文件批量修改稳定性大幅提升Pi

1

pi install npm:pi-hashline-edit-pro

• pi-code

一站式代码增强包，兼容 Claude Code 配置，内置任务清单、检查点、会话记忆、网页检索、子代理能力，开箱即用的完整编码工作流

1

pi install npm:@chankov/agent-skills

技能安装

安装方法

全局用户目录安装（推荐，所有项目生效，Windows）

• 定位 Pi 全局 skill 目录

1

%USERPROFILE%\.agents\skills\

完整示例：C:\Users\你的用户名\.agents\skills\pdf-reader\

• 创建文件夹 pdf-reader，在里面新建 SKILL.md，把下面内容复制进去:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

---
name: pdf-reader
description: PDF专业处理技能，区分纯文本PDF/扫描件/带公式图表PDF，自动选择文本提取或OCR页面渲染，提取表格、批注，适合合同、标书、公文阅读。
---
# PDF阅读处理规范
## 适用场景
当任务包含读取PDF、提取PDF文字、表格、批注、总结PDF、解析扫描版PDF时自动启用本技能。
## 处理流程
1. 判断PDF类型：
    - 纯文本PDF：直接提取全文，保留表格结构；
    - 扫描图片PDF：调用OCR识别；
    - 含公式/图表PDF：提取文本+描述图表内容。
2. 输出规则：
    - 长文档：先输出文档大纲，再按章节提炼要点；
    - 表格：尽量还原markdown表格；
    - 合同/公文：重点提取条款、日期、关键数据；
3. 约束：遇到文字模糊OCR识别不全时，主动告知识别缺陷，不编造原文。

• 重启 Pi，输入 /reload 重载技能列表。
• 验证：/skill:pdf-reader，能正常唤起代表安装成功。

项目本地安装（仅当前项目生效）

在你的项目根目录新建文件夹：.agents/skills/pdf-reader/，放入上面的 SKILL.md。

参考链接

1. 离线部署AI_Agent的方法,by huangwang.

因为研究 Pi Agent 源代码，发现都是 TypeScript 编写的，因此找了阮一峰的TypeScript教程熟悉一下 TypeSCript 语法。

简介

TypeScript（简称 TS）是微软公司开发的一种基于 JavaScript （简称 JS）语言的编程语言。
TypeScript 对 JavaScript 添加的最主要部分，就是一个独立的类型系统。

基本用法

any类型

类型系统

bigint 类型包含所有的大整数。

1
2

const x:bigint = 123n;
const y:bigint = 0xffffn;

所谓“包装对象”，指的是这些值在需要时，会自动产生的对象。
由于包装对象的存在，导致每一个原始类型的值都有包装对象和字面量两种情况。

联合类型（union types）指的是多个类型组成的一个新类型，使用符号|表示。
联合类型A|B表示，任何一个类型只要属于A或B，就属于联合类型A|B。

1
2
3
4

let x:string|number;

x = 123; // 正确
x = 'abc'; // 正确

数组

元组

元组（tuple）是 TypeScript 特有的数据类型，JavaScript 没有单独区分这种类型。它表示成员类型可以自由设置的数组，即数组的各个成员的类型可以不同。
元组成员的类型可以添加问号后缀（?），表示该成员是可选的。

1

let a:[number, number?] = [1];

扩展运算符（…）将数组（注意，不是元组）转换成一个逗号分隔的序列，这时 TypeScript 会认为这个序列的成员数量是不确定的，因为数组的成员数量是不确定的。

1
2
3
4
5
6
7

const arr:[number, number] = [1, 2];

function add(x:number, y:number){
  // ...
}

add(...arr) // 正确

symbol类型

Symbol 是 ES2015 新引入的一种原始类型的值。它类似于字符串，但是每一个 Symbol 值都是独一无二的，与其他任何值都不相等。

1
2
3
4

let x:symbol = Symbol();
let y:symbol = Symbol();

x === y // false

函数

可选参数:

如果函数的某个参数可以省略，则在参数名后面加问号表示。

1
2
3
4
5
6

function f(x?:number) {
  // ...
}

f(); // OK
f(10); // OK

函数的可选参数只能在参数列表的尾部，跟在必选参数的后面。

rest 参数表示函数剩余的所有参数，它可以是数组（剩余参数类型相同），也可能是元组（剩余参数类型不同）。

1
2
3
4
5
6
7
8
9

// rest 参数为数组
function joinNumbers(...nums:number[]) {
  // ...
}

// rest 参数为元组
function f(...args:[boolean, number]) {
  // ...
}

对象

除了原始类型，对象是 JavaScript 最基本的数据结构。

interface

参考链接

1. TypeScript 教程,by 阮一峰.

最近需要在 X86_64 的 Windows 10 的机器上安装 arm64 指令集的银河麒麟 v10 操作系统，因此研究一下 QEMU 的使用方法。

简介

QEMU 是一款开源、跨平台的机器模拟器与虚拟机工具，核心两大能力：硬件模拟（全系统仿真） 和 用户态程序翻译，不需要依赖硬件虚拟化也能运行。

安装

Windows 安装

1. 下载二进制安装包：https://qemu.weilnetz.de/w64/ ，下载qemu‑w64‑setup‑xxxx.exe安装程序
2. 安装，记住安装路径，默认：C:\Program Files\qemu
3. 把这个目录加到系统 PATH 环境变量（必须，否则 cmd 找不到 qemu‑xxx.exe）
4. 关闭旧 cmd/PowerShell，新开终端验证

1

qemu-system-aarch64.exe --version

Windows 模拟 arm64：需要额外下载QEMU_EFI.fd UEFI 固件文件。

使用

准备文件

1. 下载** ARM64 UEFI 固件 QEMU_EFI.fd（edk2‑aarch64‑code.fd）**，ARM 虚拟机没有 BIOS，靠 EFI 固件引导。
2. 下载 ARM64 系统 ISO 镜像（Ubuntu‑ARM64 / 银河麒麟 ARM64 等）
3. 创建虚拟磁盘（cmd 执行）

1

qemu-img create -f qcow2 kylin_arm64_disk.qcow2 60G

安装系统

安装 银河麒麟V10桌面版

把下面保存为 install.bat，修改路径为你本机真实路径：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

@echo off
qemu-system-aarch64 ^
-machine virt,gic-version=3 ^
-cpu cortex-a72 ^
-m 8192 ^
-smp 4 ^
-bios edk2-aarch64-code.fd ^
-device qemu-xhci,id=usbbus ^
-drive file=kylin_arm64_disk.qcow2,if=virtio,format=qcow2 ^
-cdrom Kylin-Desktop-V10-SP1-2503-Release-20250430-ARM64.iso ^
-device virtio-net-pci,netdev=net0 ^
-netdev user,id=net0 ^
-device usb-kbd,bus=usbbus.0 ^
-device usb-tablet,bus=usbbus.0 ^
-device virtio-gpu-pci,max_outputs=1 ^
-display sdl ^
-accel tcg,thread=multi,tb-size=512 ^
-serial stdio

参数说明：

• -M virt：QEMU 标准 ARM 虚拟机板卡
• -cpu cortex‑a72：模拟 ARMv8‑A CPU；也可以写max
• -accel tcg,thread=multi：软件多线程翻译，x86 Windows 唯一可用加速选项virtio-win
• -nic user：NAT 网络，虚拟机可访问外网
• -bios：指定 aarch64 EFI 固件，**缺少直接黑屏无法启动

安装完成后，把命令里的 cdrom 那一行删掉，就是正常启动虚拟机脚本。

安装 银河麒麟V10服务器版

把下面保存为 install.bat，修改路径为你本机真实路径：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

@echo off
qemu-system-aarch64 ^
-machine virt,gic-version=3 ^
-cpu cortex-a72 ^
-m 8192 ^
-smp 4 ^
-bios edk2-aarch64-code.fd ^
-device qemu-xhci,id=usbbus ^
-drive file=kylin_arm64_disk.qcow2,if=virtio,format=qcow2 ^
-cdrom Kylin-Server-V10-SP3-2403-Release-20240426-ARM64.iso ^
-device virtio-net-pci,netdev=net0 ^
-netdev user,id=net0 ^
-device usb-kbd,bus=usbbus.0 ^
-device usb-tablet,bus=usbbus.0 ^
-device virtio-gpu ^
-accel tcg,thread=multi ^
-serial stdio

参数说明：

• -M virt：QEMU 标准 ARM 虚拟机板卡
• -cpu cortex‑a72：模拟 ARMv8‑A CPU；也可以写max
• -accel tcg,thread=multi：软件多线程翻译，x86 Windows 唯一可用加速选项virtio-win
• -nic user：NAT 网络，虚拟机可访问外网
• -bios：指定 aarch64 EFI 固件，**缺少直接黑屏无法启动

安装完成后，把命令里的 cdrom 那一行删掉，就是正常启动虚拟机脚本。

启动系统

启动银河麒麟V10桌面版

把下面保存为 start_gui.bat，修改路径为你本机真实路径：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

@echo off
chcp 65001 >nul
qemu-system-aarch64 ^
-machine virt,gic-version=3 ^
-cpu cortex-a72 ^
-m 8192 ^
-smp 4 ^
-bios edk2-aarch64-code.fd ^
-device qemu-xhci,id=usbbus ^
-drive file=kylin_arm64_disk.qcow2,if=virtio,format=qcow2 ^
-device virtio-net-pci,netdev=net0 ^
-netdev user,id=net0,hostfwd=tcp::2222-:22 ^
-device usb-kbd,bus=usbbus.0 ^
-device usb-tablet,bus=usbbus.0 ^
-device virtio-gpu-pci,max_outputs=1 ^
-display sdl ^
-accel tcg,thread=multi,tb-size=512 ^
-serial stdio

参数说明：

• 与安装脚本相比，主要删除了 cdrom 那一行
• -device virtio-gpu-pci，安装时使用的是 virtio-gpu，两者区别是： 底层 GPU 逻辑完全一样，只是总线类型不同。由于场景为-machine virt（aarch64 virt 板子），推荐用 virtio-gpu-pci，麒麟 V10 ARM64 对 PCI 设备驱动识别更稳。
• -netdev user,id=net0,hostfwd=tcp::2222-:22，宿主机的 2222 端口映射虚拟机ssh 22 端口。
• -device e1000,netdev=net0, e1000 是模拟传统网卡，稳定性更好，避开部分 QEMU 版本 virtio-net + user netdev 的端口转发异常。

进入桌面后，设置默认启动目标：多用户字符模式，然后把下面保存为 start_nogui.bat，以便下次直接进入：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

@echo off
chcp 65001 >nul
qemu-system-aarch64 ^
-machine virt,gic-version=3 ^
-cpu cortex-a72 ^
-m 6144 ^
-smp 2,cores=2,threads=1 ^
-bios edk2-aarch64-code.fd ^
-drive file=kylin_arm64_disk.qcow2,if=virtio,format=qcow2 ^
-device virtio-net-pci,netdev=net0 ^
-netdev user,id=net0,hostfwd=tcp::2222-:22 ^
-accel tcg,thread=multi,tb-size=1024,one-insn-per-tb=off ^
-serial stdio ^
-no-reboot

启动银河麒麟V10服务器版

把下面保存为 start.bat，修改路径为你本机真实路径：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

@echo off
qemu-system-aarch64 ^
-machine virt,gic-version=3 ^
-cpu cortex-a72 ^
-m 8192 ^
-smp 4 ^
-bios edk2-aarch64-code.fd ^
-device qemu-xhci,id=usbbus ^
-drive file=kylin_arm64_disk.qcow2,if=virtio,format=qcow2 ^
-netdev user,id=net0,hostfwd=tcp::2222-:22 ^
-device e1000,netdev=net0 ^
-device usb-kbd,bus=usbbus.0 ^
-device usb-tablet,bus=usbbus.0 ^
-device virtio-gpu-pci ^
-accel tcg,thread=multi ^
-serial stdio

参数说明：

• 与安装脚本相比，主要删除了 cdrom 那一行
• -device virtio-gpu-pci，安装时使用的是 virtio-gpu，两者区别是： 底层 GPU 逻辑完全一样，只是总线类型不同。由于场景为-machine virt（aarch64 virt 板子），推荐用 virtio-gpu-pci，麒麟 V10 ARM64 对 PCI 设备驱动识别更稳。
• -netdev user,id=net0,hostfwd=tcp::2222-:22，宿主机的 2222 端口映射虚拟机ssh 22 端口。
• -device e1000,netdev=net0, e1000 是模拟传统网卡，稳定性更好，避开部分 QEMU 版本 virtio-net + user netdev 的端口转发异常。

SSH访问

银河麒麟V10桌面版设置

• 确认 ssh 服务是否就绪

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 1. 查看sshd状态
systemctl status sshd

# 如果没装，安装并启动
sudo apt-get install openssh-server -y
sudo systemctl start sshd
sudo systemctl enable --now ssh.service

# 2. 查看监听端口，确认sshd监听 22
ss -tlnp | grep sshd

# 3. 防火墙放行22端口（麒麟默认防火墙会拦截！这个是高频坑）
sudo firewall-cmd --add-service=ssh --permanent
sudo firewall-cmd --reload

• ssh 访问无法执行可执行程序的问题

原因是内核启动参数：security=kysec。

KYSEC 是银河麒麟 V10 内置安全模块，执行控制（exec control）开启强制模式时，只允许系统自带、带有 kysec 安全标记的 ELF 程序运行。

自编译的hello、上传的pi属于外来二进制，没有 kysec 安全标记，execve 直接返回 EACCES，bash 提示权限不够，和你现象完全吻合

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# 查看**当前正在生效**的内核启动参数

cat /proc/cmdline

# 修改/etc/default/grub，注释下行

GRUB_CMDLINE_LINUX_SECURITY="security=kysec"

# 更新grub，并重启
sudo update-grub
reboot

# 持久软模式（重启虚拟机仍然保持 softmode）
sudo setstatus softmode -p

# 编辑.bashrc文件
vim .bashrc

# 末尾增加
# 代理开关别名
alias proxy-on='export ALL_PROXY=socks5://127.0.0.1:7890;export HTTP_PROXY=http://127.0.0.1:7890;export HTTPS_PROXY=http://127.0.0.1:7890;export NO_PROXY=localhost,127.0.0.1,10.0.2.0/24;echo "✅ 代理已开启"'
alias proxy-off='unset ALL_PROXY HTTP_PROXY HTTPS_PROXY;echo "❌ 代理已关闭"'

source .bashrc

# 查看公网 IP 的地理位置
curl ipinfo.io
curl -s myip.ipip.net

银河麒麟V10服务器版设置

• 确认 ssh 服务是否就绪

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 1. 查看sshd状态
systemctl status sshd

# 如果没装，安装并启动
sudo dnf install openssh-server -y
sudo systemctl start sshd
sudo systemctl enable sshd

# 2. 查看监听端口，确认sshd监听 22
ss -tlnp | grep sshd

# 3. 防火墙放行22端口（麒麟默认防火墙会拦截！这个是高频坑）
sudo firewall-cmd --add-service=ssh --permanent
sudo firewall-cmd --reload

• 解禁 root 直接 ssh 登录

1
2
3
4
5
6

# 虚拟机内修改ssh配置允许root登录（测试用）
sudo vi /etc/ssh/sshd_config
# 修改：
PermitRootLogin yes
# 重启sshd
sudo systemctl restart sshd

生产环境不建议 root 直接 ssh；你可以新建普通用户登录。

Nodejs安装

• 下载最新的Linux Arm64 Nodejs LTS版
• 解压 node-v24.21.0-linux-arm64.tar.xz 到 /opt/node

1
2

sudo mkdir -p /opt/node
sudo tar -Jxf node-v24.21.0-linux-arm64.tar.xz -C /opt/node --strip-components=1

• 将 node 路径永久加入系统 PATH

1
2
3

sudo vim /etc/profile
# 文件末尾加入下列行，并保存
export PATH="/opt/node/bin:$PATH"

• 验证

1
2

node -v
npm -v

问题记录

虚拟机分辨率调整

启动麒麟v10桌面版系统，分辨率太低，只有640*480的解决方法：

• 打开终端，输入命令

1
2
3
4
5
6

# 打开终端，查看显示器名称
xrandr

# 直接设置 1080P

xrandr --output Virtual-1 --mode 1920x1080

虚拟机启动太慢

1
2
3
4
5
6
7
8
9
10
11
12

# 设置默认启动目标：多用户字符模式
sudo systemctl set-default multi-user.target

# 验证
systemctl get-default
# 输出 multi-user.target 就是成功

reboot

# 恢复开机图形（以后需要桌面时）
sudo systemctl set-default graphical.target
reboot

参考链接

1. qemu,by qemu.
2. Running QEMU VMs on ARM64: UEFI Requirements,by Nikita Vakula.
3. windows qemu 安装 arm 虚拟机,by 三希.
4. 安装与配置麒麟V10操作系统,by huawei.

最近在测试 trae、workbuddy、pi 三款 ai 代理，调用的是本地 ollama 部署的大模型，三款 ai 代理都会以兼容 OpenAI Api 的方式向 ollama 提供的 http://127.0.0.1:11434 端口发出 http 请求，于是想通过一款 http 代理工具，抓取三款 ai 代理发出的兼容 OpenAI Api风格的 http 请求，从底层了解 ai 代理的原理。使用的 http 代理工具经豆包推荐为 MitmProxy，当然类似的工具还有 Fiddler 等。

简介

mitmproxy 是一款免费开源的交互式的 https 代理。可以从 mitmproxy 官网地址下载安装。

使用方法

下载后的 mitmproxy 安装包解压后主要有三个可执行文件：

• mitmproxy，提供命令行界面
• mitmdump，提供一个简单的终端输出（还可以配合Python抓包改包）
• mitmweb，提供在线浏览器抓包界面

反向代理

mitmproxy 做 reverse proxy 反向代理，客户端访问 mitmproxy，mitmproxy转发给 ollama 11434，全部流量被捕获。

方法如下，打开命令提示符窗口，输入如下命令：

1

mitmweb --mode reverse:http://127.0.0.1:11434 -p 8888

mitmweb 会打开网页控制台 http://127.0.0.1:8081 , 可以在该网页查看所有转发 http 请求。

修改 ai 代理自定义模型的 base_url，指向 mitmproxy，即：

1

base_url = " http://127.0.0.1:8888/v1"

参考链接

1. mitmproxy,by mitmproxy.
2. 实战|手把手教你如何使用抓包神器MitmProxy,by 李运辰.

最近想离线部署一套AI编程工具，以提高生产力。首先研究离线部署LLM的方法，再研究离线部署AI Agent的方法。

Pi 离线安装

开源的AI Agent有很多，这里使用 Pi agent，因为该AI代理具备持久记忆和自我审查能力，支持完全离线运行，可在Ollama等本地模型上使用，具备长期记忆和自主迭代能力。

安装过程1

• 安装 NVM nodejs多版本管理工具，从官网下载 NVM 安装 NVM。

• 使用 nvm 安装最新的 nodejs LTS 版本

1
2
3

nvm install 24.19.0 x64
nvm list
nvm use 24.19.0

• 安装 npm-bundle 用于打包 pi agent

1

npm install -g npm-bundle

• 安装 Pi agent

1

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

• 打包 npm 包

1

npm-bundle  @earendil-works/pi-coding-agent

因为打包失败，无法离线安装，暂时放弃此安装方式。

安装过程2

• 从github下载 pi，即 pi-windows-x64.zip
• 解压 pi-windows-x64.zip ，并将解压目录添加到 PATH 环境变量

配置过程

pi 代理主要有两个配置文件，通常在目录 .pi/agent/ 下，一个配置文件名叫 settings.json，另一个配置文件名叫 models.json ，需要手动创建。两个配置文件内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# settings.json
# 设置 pi 版本、默认 LLM 提供者和默认 LLM

{
  "lastChangelogVersion": "0.84.2",
  "defaultProvider": "ollama",
  "defaultModel": "deepseek-r1:1.5b"
}

# models.json

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "deepseek-r1:1.5b" }
      ]
    }
  }
}

内网部署

拷贝 pi-windows-x64.zip 和 目录 .pi/agent/ 到内网机器，按照同样的配置过程设置即可。

使用方法

• 运行模式：默认进入交互模式，也支持 -p（打印后退出）或 –mode json/rpc。
• 内建工具：包含 read（读文件）、write（写文件）、edit（改文件）、bash（跑命令）。
• 常用交互命令：
  • /model：切换 AI 模型。
  • /settings：调整思考级别（Thinking）和主题。
  • /tree / /fork：浏览会话树、分支管理。
  • /compact：手动压缩上下文。

问题记录

Pi 代理无法读写文件

• 原因：Qwen‑Coder‑2.5‑7B 本身对 Agent 工具调用能力弱于通用大模型

参考链接

1. 别只拿 AI 写代码了——用 Pi Agent + Skill 搭建你的全能工作流,by 玩客笔记.
2. Pi Agent 深度剖析：一个”什么都不要”的编码智能体，凭什么一年 8.9 万星？—— 与 Codex、OpenCode 的实现对比,by Arthur.
3. Pi — 终端 AI 编程助手使用指南,by graysonchen.
4. 万字详解：普通开发者如何用Ollama、llama.cpp把大模型无缝跑在本地消费级显卡上？,by HogwartscsrQY.
5. 下一代Agent架构——Pi Agent Core 设计逻辑深度解析,by 王鹏LLM.

最近想离线部署一套AI编程工具，以提高生产力。首先研究离线部署LLM的方法，再研究离线部署AI Agent的方法。

Ollama 离线安装

目前LLM主流部署框架与工具主要有：Ollama、llama.cpp、vLLM、LM Studio、Xinference、Hugging Face Transformers。综合考虑，先从最简单的开始，离线部署Ollama。

根据机器的CPU指令集，从github官网下载 Ollama的安装包，这里选择绿色版的ollama-windows-amd64.zip。

安装过程

解压ollama-windows-amd64.zip到安装目录，并将 ollama 的安装目录添加到系统环境变量 PATH 中。

配置过程

• 修改 Ollama 下载模型保存位置

新建环境变量 OLLAMA_MODELS ，设置其值为 Ollama 下载模型保存位置。

启动过程

打开 cmd 窗口，启动 ollama 服务器实例，如下所示：

1
2

## 启动Ollama服务
ollama serve

再打开一个cmd窗口，执行 ollama 客户端命令，如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

## 从模型文件创建模型
ollama create
## 显示模型信息
ollama show
## 运行模型
ollama run 模型名称
ollama run deepseek-r1:1.5b
## 从注册表中拉去模型
ollama pull 模型名称
## 将模型推送到注册表
ollama push
## 列出模型
ollama list
## 复制模型
ollama cp
## 删除模型
ollama rm 模型名称
## 获取有关Ollama任何命令的帮助信息
ollama help

离线部署

• 拷贝ollama-windows-amd64.zip到离线电脑
• 拷贝 Ollama 下载模型文件夹
• 设置环境变量 PATH 和 OLLAMA_MODELS

问题记录

内存访问违规问题

• 问题描述

运行如下命令时报错：

1
2
3
4

ollama create
ollama run deepseek-r1:1.5b

Error: 500 Internal Server Error: llama-server process has terminated: exit status 0xc0000005: The instruction at 0xp referenced memory at 0xp. The memory could not be s

• 原因分析
  原因： NVIDIA 显卡驱动过旧：这是非常常见的原因。Ollama 的新版本（如 v0.30.11 及以上）通常需要 NVIDIA 驱动版本在 550.x 或更高。旧版驱动可能与新版的 CUDA 后端不兼容，从而引发内存错误。

• 解决方案

直接去 NVIDIA 官网，下载并安装最新稳定版驱动。安装后重启电脑。

大语言模型没有在GPU上运行的问题

• 问题描述

ollama run qwen3.6:9b 时，大模型没有运行在GPU上，这一点可以通过执行 ollama ps 查看。

• 原因分析

没有安装最新的显卡驱动

• 解决方案

安装好最新的显卡驱动之后，将 ollama.exe 添加到使用显卡执行的列表中去。

参考链接

1. 手把手教你离线安装Ollama,by 张云飞.
2. Ollama GPU 加速配置：CUDA、ROCm 与 Metal 全平台实战指南,by easton.
3. 当使用 ollama 本地部署 Error: could not connect to ollama app, is it running?,by 系着秋天的落叶.
4. 一文读懂大模型推理中的HTTP协议,by 游凯超.
5. OpenAI API 协议完全指南 - 大模型应用开发的通用标准,by 不想起名字1111111.
6. OpenAI API格式详解-Chat Completions,by 啤酒泡泡.
7. 工具调用:OpenAI 工具调用从一到多函数调用,by JPPeng.
8. 大模型 LLM 缓存机制：从原理到工程实践,by guangzhengli.

开发一个C/S架构的软件，准备使用gRPC技术。

gRPC 简介

gRPC (gRPC Remote Procedure Calls) 是一个跨平台的开源高性能远程过程调用（RPC）框架。

gRPC最初由Google创建，它使用一个通用的RPC基础设施Stubby来连接其数据中心内外运行的大量微服务，始于2001年。2015年3月，Google决定构建下一个版本的Stubby并将其开源，于是就有了gRPC。现在除了Google之外，许多组织都在使用它来支持从微服务到计算的“最后一英里”（移动、Web和物联网）的用例。

gRPC基于HTTP/2协议传输数据，使用Protocol Buffers作为接口描述语言，并提供认证（authentication）、双向流（bidirectional streaming）和流量控制、阻塞或非阻塞绑定以及取消和超时（Deadlines）等功能。它为许多语言生成跨平台的客户端和服务器绑定。最常见的使用场景包括在微服务风格的架构中连接服务，或将移动设备客户端连接到后端服务。

使用方法

默认情况下，gRPC 使用 Protocol Buffers，这是 Google 成熟的开源机制，用于序列化结构化 数据（尽管它也可以与其他数据格式如 JSON 一起使用）。

使用 Protocol Buffers 的第一步是在 proto 文件中定义您要序列化的数据结构：这是一个带有 .proto 扩展名的普通文本文件。Protocol buffer 数据被结构化为 消息 (messages)，其中每条消息都是一条逻辑信息记录，包含一系列称为 字段 (fields) 的名称-值对。以下是一个简单的示例：

1
2
3
4
5

message Person {
  string name = 1;
  int32 id = 2;
  bool has_ponycopter = 3;
}

然后，一旦指定了数据结构，您就可以使用 Protocol Buffer 编译器 protoc 从您的 proto 定义中生成您所选语言的数据访问类。这些类为每个字段提供了简单的访问器，例如 name() 和 set_name()，以及将整个结构序列化/解析为原始字节的方法。

您可以在普通 proto 文件中定义 gRPC 服务，并将 RPC 方法参数和返回类型指定为 Protocol Buffer 消息:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// The greeter service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

参考链接

1. gRPC 简介,by gprc.
2. GRPC,by wiki.

读书使人进步。

数据结构

位掩码 (Bitmask)

将多个布尔标志打包到一个整数中，通过位运算实现常数时间的集合操作。

最小堆 / 优先队列 (Min Heap)

存储在数组中的二叉树，最小元素始终在根节点，支持 O(1) 查看和 O(log n) 插入/删除。

环形缓冲区 (Ring Buffer)

固定大小的缓冲区通过模运算实现循环，提供常数时间的入队出队且无需内存分配。

Trie 前缀树 (Trie / Prefix Tree)

在树中存储字符串，每条边代表一个字符——共享前缀共享节点，实现按键长度 O(k) 查找。

跳表 (Skip List)

概率有序数据结构，O(log n) 搜索、插入和删除——比平衡树更简单，性能相当。

布隆过滤器 (Bloom Filter)

以 O(k) 时间测试集合成员资格，零漏判——代价是可调的误判率。

LRU 缓存 (LRU Cache)

缓存满时淘汰最近最少使用的条目——用哈希表加双向链表实现 O(1) 的 get 和 put。

B+ 树 (B+ Tree)

自平衡多路树，高扇出——内部节点负责路由，叶节点存储数据，所有叶节点通过链表相连以支持高效范围扫描。

标签联合体 (Tagged Union / Variant)

将类型标签与值联合体配对存储，使一个变量安全地持有不同类型，通过标签分发行为。

Merkle 树 (Merkle Tree)

对叶子节点做哈希，然后逐层向上哈希配对——以 O(log n) 的代价验证任意叶子的完整性，无需重新哈希整个数据集。

合并迭代器 (Merge Iterator / K-Way Merge)

使用最小堆将 K 个有序流合并为一个有序输出——跨多个数据源创建”统一视图”的通用方法。

并发

信号量 / 有界并发 (Semaphore)

通过维护计数器限制并发操作数量——工作前获取，完成后释放，达到上限时阻塞。

Actor 模型

每个 Actor 拥有一个信箱并按顺序处理消息——没有共享状态，没有锁，仅通过消息传递实现安全并发。

工作窃取 (Work Stealing)

空闲线程从繁忙线程的队列中窃取任务——无需中央协调即可动态均衡负载。

MVCC 多版本并发控制

为每个值保留多个带时间戳的版本，读者永远不阻塞写者——每个事务看到一致的快照，无需加锁。

协作调度 (Cooperative Scheduling)

将长时间运行的任务拆分为小块，在每块之间让出控制权，以保持系统响应。

双缓冲 (Double Buffering)

维护两份状态副本，在它们之间原子切换，让读取方始终看到一致的快照。

背压 / 流控 (Backpressure)

当消费者跟不上时减慢生产者——用有界缓冲区和需求信号防止资源耗尽。

事件循环 / 反应器 (Event Loop / Reactor)

单线程循环通过 epoll/kqueue 多路复用 I/O，将就绪事件分发给回调——无需线程即可处理数千连接。

逻辑时钟 / Epoch (Logical Clock)

单调递增的计数器，无需物理时钟即可排序事件——实现一致性快照和过期检测。

系统

熔断器 (Circuit Breaker)

通过跟踪错误次数自动跳闸——快速失败，而不是堆积超时等待。

限流器 / 令牌桶 (Rate Limiter)

通过维护一个按固定速率补充的令牌桶来控制吞吐量——每次操作消耗一个令牌，桶空时拒绝请求。

指数退避重试 (Retry with Backoff)

操作失败时以指数增长的延迟重试，加随机抖动避免惊群效应。

预写日志 (Write-Ahead Log)

在应用变更前先将每个变更记录到持久存储——重放日志即可从崩溃中恢复，零数据丢失。

批处理 (Batch Processing)

累积单个操作并作为一组执行，将每次操作的开销分摊到整个批次。

一致性哈希 (Consistent Hashing)

将键分布到虚拟环上的节点，添加或移除节点时只重映射约 1/n 的键。

依赖图 (Dependency Graph)

将依赖关系建模为有向无环图，拓扑排序确定合法执行顺序——在死锁前检测循环。

中间件 / 管道链 (Middleware / Pipeline Chain)

组合处理器，每个包裹下一个——前处理、调用 next、后处理——形成双向管道。

注册表 / 自注册 (Registry)

组件按名称将自身注册到全局查找表——消费者在运行时发现实现，无需硬编码依赖。

脏标记 (Dirty Flag)

在变更时将对象标记为”脏”，延迟昂贵的重计算直到值真正被需要时再执行，然后清除标记。

LSM 树 (Log-Structured Merge Tree)

将写入缓冲在内存中，刷写到磁盘的有序文件，后台合并文件——用读放大换取快速写入。

检查点 (Checkpointing)

定期快照一致性状态，使恢复只需从检查点开始重放——而不是从时间的起点。

内存

对象池 (Object Pool)

预分配一组可复用对象，避免热路径上重复分配和垃圾回收的开销。

对象池 (Object Pool)

共享相同的不可变对象而非创建重复实例，用查找开销换取大量内存节省。

Arena 分配器 (Arena Allocator)

在预分配区域中通过移动指针分配对象——不再需要时一次性释放所有内存。

空闲链表 (Free List)

维护一个已释放槽位的链表，使分配和释放都是 O(1)——复用内存而无需调用系统分配器。

写时复制 (Copy-on-Write)

通过引用共享数据，直到有人修改时才创建私有副本——为读多写少的场景节省内存和分配开销。

引用计数 (Reference Counting)

通过原子计数器追踪所有者，归零时自动清理——无需垃圾回收的确定性资源生命周期管理。

墓碑 / 延迟删除 (Tombstone)

用墓碑标记代替直接删除条目——后台进程稍后回收空间。

驻留 / 符号表 (Interning / Symbol Table)

通过规范化查找表去重不可变值——用 O(1) 的指针比较替代 O(n) 的内容比较。

行为型

状态机 (State Machine)

将实体的生命周期建模为一组状态和显式转换，让不可能的状态不可表达，每次状态变更可审计。

观察者 / 发布-订阅 (Observer / Pub-Sub)

让对象订阅事件并在事件发生时收到通知，实现生产者与消费者的解耦——发送方不需要知道谁在监听。

迭代器 / 惰性求值 (Iterator)

逐个处理序列中的元素而不实例化整个集合，通过可组合的转换实现零中间分配。

差异/补丁 (Diff / Patch)

比较两个序列，计算将一个转换为另一个所需的最小操作集（插入、删除、移动）。

虚函数表 / 操作分发 (Vtable / Ops Dispatch)

将函数指针组合到结构体中实现运行时多态——接口、trait 和虚方法背后的手动基础。

访问者 / 树遍历器 (Visitor / Tree Walker)

将树遍历与操作解耦，通过分发到类型特定的回调——使新操作无需修改树结构。

参考链接

1. Battle-Tested Patterns,by totoro-jam.

Pytest 是一个功能强大且易于使用的 Python 测试框架，广泛用于单元测试和调试代码。它支持简单的断言语法、丰富的插件生态系统以及灵活的测试用例管理，非常适合调试和提高代码质量。

安装与环境配置

1
2
3
4
5

# 使用 pip 安装
pip install pytest

# 验证安装
pytest --version

编写测试用例

Pytest 遵循约定优于配置的原则，测试文件和函数需遵循以下命名规则：

• 测试文件以 test_ 开头或 _test 结尾，例如 test_example.py。

• 测试函数以 test_ 开头，例如 def test_add():。

• 测试类以 Test 开头，且不包含 init 方法。

示例代码：

1
2
3
4
5
6
7
8

# 被测试函数
def add(a, b):
   return a + b
# 测试用例
def test_add_positive_numbers():
   assert add(2, 3) == 5
def test_add_negative_numbers():
   assert add(-1, -1) == -2

执行测试与调试

运行测试时，可以通过命令行指定文件、目录或关键字：

1
2
3
4
5
6

# 运行当前目录下的所有测试
pytest
# 运行指定文件的测试
pytest test_example.py
# 运行包含特定关键字的测试
pytest -k "add"

断言与错误报告

Pytest 支持直接使用 Python 的 assert 语句，并在断言失败时提供详细的上下文信息。例如：

1
2

def test_example():
    assert 2 + 2 == 5 # 输出详细的断言失败信息

参考链接

1. 十分钟带你看懂——Python测试框架之pytest最全讲,by 程序员月下.

使用字节跳动的Trae Solo CN编写了一个两个参与者的博弈类小游戏，该游戏使用 nodejs 加 expressjs 加 socket.io 实现。开发完毕后，将该应用部署到互联网，记录一下部署过程。

申请云主机

选择阿里云免费申请一个云主机，使用ubuntu 22.04操作系统，默认安装docker服务。

上传应用

远程登录阿里云主机，上传nodejs应用。

部署应用

因为需要在Docker中运行 npm install 构建 nodejs 应用部署环境，因此无法直接使用默认的 nodejs 镜像，需要自定义 nodejs 镜像。

创建一个高效的 Dockerfile

在项目的根目录下，创建一个名为Dockerfile的文件，并写入以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 选择一个基础镜像，比如 Node.js 20
FROM node:20-alpine

# 在容器中创建并设置工作目录
WORKDIR /usr/src/app

# 先复制依赖管理文件（这是为了利用 Docker 的缓存，避免每次代码变动都重新安装依赖）
COPY package*.json ./

# 安装项目依赖
RUN npm install
# 如果是生产环境，推荐使用 npm ci 以获得更快、更可靠的安装
# RUN npm ci --only=production

# 复制所有应用源代码到工作目录
COPY . .

# 应用运行的端口
EXPOSE 8080

# 指定容器启动时运行的命令
CMD ["node", "server.js"]

构建与运行

• 构建镜像

在包含上述Dockerfile的目录下，运行以下命令来构建镜像：

1
2
3
4
5

# 构建镜像
docker build -t my-node-app .

# 查看镜像
docker image ls

• 运行容器

构建成功后，使用docker run命令启动容器，并将宿主机的端口映射到容器内的端口：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 后台运行docker镜像
docker run -d -p 80:8080 -d my-node-app

# 交互式运行docker镜像
docker run -it -p 80:8080 -d my-node-app

# 查看容器
docker container ls

# 查看docker进程
docker ps

# 访问nodejs应用
curl http://localhost:80

# 删除容器
docker container rm container_id

# 删除镜像
docker image rm image_id

远程访问

在阿里云主机的管理界面上，设置防火墙，允许外部主机访问云主机的web服务端口。

打开浏览器，输入网址访问 http://ip ，其中ip为云主机的公网ip 。

参考链接

1. Docker使用帮助,by huangwang.