企业官网建设流程全解析

• 任务调度
• CLI

本文以 pueue_lib/CHANGELOG.md 为骨架，逐版本梳理 Pueue 共享库（pueue-lib）在消息协议、任务状态模型、网络层、配置系统与错误处理上的关键演进，并结合仓库源码（pueue_lib/src/下的message/、network/、state.rs、task.rs、settings.rs、error.rs等）印证每一处变更的实现细节。读完本文，你将理解 Pueue 客户端与守护进程之间"通信协议 + 状态共享 + 配置约定"三大核心契约的来龙去脉，以及为什么 0.28/0.30 等版本会带来破坏性变更。

一、版本节奏与版本管理策略

Pueue 的变更记录遵循 Keep a Changelog 格式，版本管理"部分遵循"语义化版本（SemVer）。这一点在文档开头有特别说明（pueue_lib/CHANGELOG.md）：

The concept of SemVer is applied to the daemon/client API, but not the library API itself.

也就是说，语义化版本约束的对象是守护进程与客户端之间的通信 API（即协议与消息类型），而不是 Rust 库 API 本身。这意味着库 API 在 minor 版本之间也可能发生破坏性变化，但 daemon/client 之间只要协议兼容，版本号就能保持一致。

从时间线看，pueue-lib 的版本演进分为几个阶段：

• 0.11 ~ 0.14（2020-2021 初）：协议与状态结构的早期固化期，引入 cbor 序列化、Unix 信号枚举、TaskSelection等基础类型；
• 0.15 ~ 0.19（2021-2022）：大范围"防不可能状态"重构、XDG 目录规范、Group 结构体化、tokio 迁移；
• 0.20 ~ 0.23（2022-2023）：网络层修复、任务优先级、进程组支持；
• 0.24 ~ 0.27（2023-2024）：shell_command/env_vars配置、Children进程表示、Reset 按组化、所有状态收敛进State；
• 0.28 ~ 0.31（2025-2026）：Request/Response分裂、Client 提取入库、daemon 专属代码剥离、功能开关（feature flags）化，当前最新版本为0.31.1（2026-03-02），另有未发布的 0.31.2。

值得一提的插曲是0.22.0 被跳过——文档写道 "This version was skipped due to a error during release"（pueue_lib/CHANGELOG.md），这是版本号管理上的一个真实历史细节。

二、消息协议演进：从单一 Message 到 Request/Response 分裂

2.1 0.28.0 的破坏性拆分

pueue-lib 历史上最核心的一次协议变更出现在0.28.0（2025-02-11）：

Breaking: Split theMessageenum into aResponseandRequestenum. Requests are senttothe daemon, responses are sentfromthe daemon.

这一拆分在源码中清晰可见：当前仓库中消息定义位于 pueue_lib/src/message/，其中：

• request.rs 定义了Request枚举——客户端发送给守护进程的全部指令，包括Add、Remove、Switch、Stash、Enqueue、Start、Restart、Pause、Kill、Send、EditRequest/EditRestore/EditedTasks、Env、Group、Parallel、Status、Log、Stream、Reset、Clean、DaemonShutdown等 20 个变体；
• response.rs 定义了Response枚举——守护进程返回给客户端的结果，如AddedTask、Edit、Status(Box<State>)、Log(BTreeMap<usize, TaskLogResponse>)、Group、Stream、Success(String)、Failure(String)、Close。

拆分之后，Request与Response各自通过impl_into_request!/impl_into_response!宏实现From<T>转换（见 request.rs 与 response.rs），配合crate::message::*的重新导出，调用方可以写出AddRequest::into()直接得到Request::Add的惯用法。

这一设计的意义在于：类型系统层面区分了"请求"与"响应"，杜绝了把响应当请求发送这类不可能状态，也让pueue_lib::prelude可以统一导出send_request/receive_response等成对函数（见 lib.rs）。

2.2 0.29.0 的命名统一与多任务 follow 预备

0.29.0（2025-03-09）继续打磨协议：

• 统一了所有Request/Response变体及单值变体（unit variant）的结构体命名；
• 为多任务follow做了前置兼容设计：Request::Stream/Response::Stream被调整为可容纳多个任务，具体是给StreamRequest增加了TaskSelection字段。这一点在源码中有明确注释（request.rs）：虽然当前只接受空列表或单元素TaskIds，但格式上为 #614 的多任务流式日志预留了空间，避免将来破坏 API；
• EditableTask与TaskToRestart中的command字段更名为original_command，防止与执行时展开后的命令产生歧义——源码中EditableTask通过#[serde(rename = "command")]保持序列化字段名不变（message/mod.rs）；
• 新增receive_bytes_with_max_size函数用于限制消息缓冲区大小、防 DoS（详见下文协议层小节）；
• 新增compress_state_file配置项（守护进程使用，详见配置章节）。

2.3 编辑流程的三步协议

CHANGELOG 记录了编辑相关的消息类型演变：0.27.0 将EditRestore、EditRequest的载荷改为任务 ID 向量，Edit的载荷改为新的EditableTask向量，并"让所有编辑字段总是被设置（不再有 Option）"。当前源码印证了这一设计：

• Request::EditRequest(Vec<usize>)——编辑三步协议的第一步，向守护进程请求锁定任务并取回详情（request.rs）；
• Request::EditRestore(Vec<usize>)——如果编辑过程中出错，客户端通知守护进程恢复任务旧状态；
• Request::EditedTasks(Vec<EditableTask>)——客户端把编辑后的任务发回守护进程；
• 对应地，Response::Edit(Vec<EditableTask>)返回锁定任务的详情。

EditableTask结构（message/mod.rs）只包含id、original_command、path、label、priority五个非空字段，并提供From<&Task>与into_task(&mut Task)两个转换方法，恰好对应"编辑时快照、提交时合并"的流程。

2.4 协议向后兼容的基石：从 bincode 到 serde_cbor

0.13.0（2021-05-28）做出一项影响深远的决策：用serde_cbor替换bincode作为序列化格式，以支持协议跨版本向后兼容。当前实现使用ciborium库（Cargo.toml），ciborium是 Rust 社区维护的 CBOR 实现，功能上与 serde_cbor 等价。

序列化/反序列化的入口在 network/protocol.rs：send_message用ciborium::into_writer把消息编码进Vec<u8>，receive_message用from_reader解码。一个很细心的设计是：当反序列化失败时，代码会先尝试把载荷解码成通用的ciborium::Value——如果能解码成功，说明是版本差异导致的消息类型不匹配，返回Error::UnexpectedPayload；否则才认为是数据损坏，返回Error::MessageDeserialization（protocol.rs）。这为"老客户端连新守护进程"这类场景提供了可读的错误信息。

2.5 协议版本握手

pueue_lib通过PROTOCOL_VERSION常量（即 crate 版本号，见 lib.rs）进行版本协商。Client::new的握手流程（network/client.rs）：

1. 连接 socket；
2. 发送共享 secret 的字节；
3. 接收守护进程返回的 UTF-8 编码版本号（secret 错误时守护进程会直接断开，收到空载荷即报错）；
4. 若版本不一致且show_version_warning为 true，打印警告日志。

这也呼应了 CHANGELOG 0.19.6 中"补充 pueue 通信协议文档"和 1.0.0（主仓库）中"客户端→守护进程握手时检测旧守护进程版本"的记录。

三、任务状态模型：把不变量交给类型系统

任务状态模型是 pueue-lib 迭代最密集的领域之一，CHANGELOG 记录了三条清晰的演进主线。

3.1 0.15.0：消灭不可能状态的第一步

0.15.0（2021-07-03）引入若干"防止不可能状态"的破坏性 API 变更：

• TaskResult被移入TaskStatus::Done(TaskResult)——此前"已完成"与"成功/失败"是两个独立字段，存在"已完成但没有结果"的空档；
• enqueue_at被移入TaskStatus::Stashed{ enqueue_at: Option<DateTime<Local>> }，让"何时入队"的数据归属更合理。

3.2 0.27.0：运行时字段全部收编进状态枚举

0.27.0（2024-12-01）是状态模型的分水岭：

• 把所有状态移到State结构体中，运行时相关字段不再单独存放，从而消除并发问题；
• 重构TaskState表示枚举，纳入所有运行时相关字段，相应地Task上删除了若干字段；
• 引入可复用的Children进程表示（此后 0.28.0 又将其移出库，详见下文）。

当前 task.rs 的TaskStatus枚举完整呈现了这一设计：每个变体携带且仅携带自己需要的字段——

pub enum TaskStatus { Locked { previous_status: Box<TaskStatus> }, Stashed { enqueue_at: Option<DateTime<Local>> }, Queued { enqueued_at: DateTime<Local> }, Running { enqueued_at: DateTime<Local>, start: DateTime<Local> }, Paused { enqueued_at: DateTime<Local>, start: DateTime<Local> }, Done { enqueued_at: DateTime<Local>, start: DateTime<Local>, end: DateTime<Local>, result: TaskResult }, }

类型系统保证了"Queued任务不可能有start时间"这类不变量——这正是 CHANGELOG 所述"通过 Rust 结构体枚举在编译期强制不变量"（该重构思路在主仓库 4.0.0 的 Runtime invariants 小节有完整描述）。配套的辅助方法is_running()、is_paused()、is_done()、failed()、is_stashed()（0.25.0 新增）、is_queued()、start_and_end()全部基于对TaskStatus的matches!匹配实现（task.rs），从调用侧进一步收窄了误用面。

TaskResult枚举则描述了任务结束后的五种结果：Success、Failed(i32)、FailedToSpawn(String)、Killed、Errored、DependencyFailed（task.rs）。

3.3 0.28.0：进程相关逻辑与字段彻底移出

0.28.0又向前迈了一步：

Breaking: Move all process handling related logic out ofpueue_libBreaking: Remove all process related fields and helper functions fromState

这与当前源码完全一致：State现在只包含tasks: BTreeMap<usize, Task>和groups: BTreeMap<String, Group>两个字段（state.rs），文档注释明确写道"State 不包含子进程信息、不包含子进程句柄，这些保存在守护进程的 TaskHandler 中"。进程管理相关代码移到了主仓库的 pueue/src/daemon/process_handler/ 和 pueue/src/daemon/internal_state/children.rs。

State还提供了一批泛型过滤函数（0.24.0/0.25.0 反复重构的对象）：filter_tasks、filter_tasks_of_group、内部filter_task_ids，返回FilteredTasks { matching_ids, non_matching_ids }（state.rs）。这取代了 0.15.0 移除的tasks_of_group_in_statuses、tasks_in_statuses以及 0.16.0 移除的task_ids_in_group_with_stati等专用函数，用一个接受闭包条件的泛型函数覆盖了所有过滤场景。

四、网络层与协议传输：字节级细节与安全加固

4.1 分包大小：1280 字节与 MTU 考量

CHANGELOG 记录了两次分包尺寸调整：0.12.0 从 1.5 Kbyte 改为 1.4 Kbyte（防止较小 MTU 下的分包），当前实现进一步定为1280 字节，源码注释说明这是为了"对 IPv6 MTU 保持安全"（protocol.rs）。

传输协议本身非常简单（send_bytes/receive_bytes，protocol.rs）：

1. 先发送8 字节 BigEndian 的u64头，声明载荷总长度；
2. 再按PACKET_SIZE（1280 字节）分块发送载荷；
3. 接收方先读 8 字节头，再循环读取块直到收满；最后一块按精确剩余字节数读取，避免把下一条消息的字节误读进来。

0.20.0 修复的"快速连续消息"bug 正是源于旧实现：接收缓冲区固定 1400 字节，即使实际载荷很小也会一次性读入缓冲区，导致两条连续发送的消息被合并读取。当前实现按"头 + 精确分块"读取，从根上解决了这个问题，protocol.rs 中的test_successive_messages测试专门验证了这一点。

4.2 0.29.0 的 DoS 防护：receive_bytes_with_max_size

receive_bytes_with_max_size（protocol.rs）在读取 8 字节头之后、分配缓冲区之前，先比对声明的消息大小与上限：

• 若超出上限，立即返回Error::MessageTooBig(usize, usize)，不分配任何内存；
• 若载荷超过 20MB，打印警告日志；
• 在 32 位平台上，还会拒绝超出usize范围的大小声明，防止整数溢出。

配套测试test_restricted_payload_size模拟了"声明 2^64 字节载荷"的恶意连接，并断言其在 4MB 上限下被拒绝（protocol.rs）——这正是 CHANGELOG 0.31.0/0.31.1 中 armv7/armhf 测试报错The payload should be rejected due to large size所指的用例。

4.3 传输通道：Unix socket 与 TLS TCP 双轨

pueue_lib的网络模块（network/mod.rs）支持两种通道：

• Unix socket（仅非 Windows 平台）：不加密，通过shared.use_unix_socket开关选择，路径默认位于 runtime 目录下的pueue_{username}.socket（settings.rs）；
• TLS 加密的 TCP：使用 rustls，客户端只信任自己的自签名 CA（get_tls_connector，network/socket/mod.rs）。

ConnectionSettings枚举统一了两种连接方式，Shared通过TryFrom<Shared>自动转换为ConnectionSettings（network/socket/mod.rs）。socket 层还抽象了Listenertrait 与PendingStream，把"接受连接"与"完成 TLS 握手"分离，避免恶意客户端不发送数据时阻塞整个 accept 循环（network/socket/mod.rs）。平台相关实现位于 network/socket/unix.rs 与 network/socket/windows.rs。

4.4 0.30.0 的网络解耦

0.30.0（2025-07-07）做了一项面向未来客户端的架构清理：

• 把大量守护进程专属函数从pueue_lib移入主仓库的pueue/daemon目录；
• 把 TLS 相关代码从 socket/protocol 代码中解耦；
• 把message模块从network模块中移出——当前目录结构（message/ 与 network/ 平级）正是这一变更的结果；
• 解耦settings与 socket/protocol 代码，使这些函数无需构造settings::Shared结构也能使用——这让第三方客户端开发容易得多；
• 把settings、log、network、tls逻辑全部放到 feature flags 后面（默认全部启用）。

对应地，Cargo.toml 定义了清晰的 feature 体系：

[features] client = ["dep:color-eyre"] default = ["client", "log", "network", "network_blocking", "settings"] log = ["dep:rev_buf_reader", "dep:snap"] network = ["dep:async-trait", "dep:byteorder", "dep:ciborium", "dep:rustls", "dep:tokio", "dep:tokio-rustls", "secret", "tls"] network_blocking = ["dep:byteorder", "dep:ciborium", "dep:rustls", "dep:rustls-connector", "secret", "tls"] secret = ["dep:rand"] settings = ["dep:dirs", "dep:serde_yaml", "dep:shellexpand"] tls = ["dep:rustls"]

pueue-lib 的 README 建议的最小化组合是"禁用默认特性 + 启用client与network或network_blocking"（pueue_lib/README.md）。network_blocking提供基于标准库的阻塞式网络协议实现，方便非 tokio 环境使用。

4.5 0.28.1：参考 Client 实现入库

0.28.1（2025-02-17）把pueue的Client实现抽取进pueue_lib，作为第三方实现客户端时的便捷入口。当前 network/client.rs 中的Client结构只保存stream与daemon_version两个字段，提供Client::new（连接 + secret 授权 + 版本检查）、send_request、receive_response三个核心方法，模块文档中的示例展示了完整用法（network/client.rs）。对应的阻塞版BlockingClient位于 network_blocking/client.rs。

五、配置系统演进：路径、环境变量与实验性特性

5.1 XDG 规范与运行时目录

0.19.0（2022-01-30）引入shared.runtime_directory配置变量，并开始遵循 XDG 规范：

• XDG_CONFIG_HOME用于 Pueue 的配置目录；
• 未显式设置pueue_directory时使用XDG_DATA_HOME；
• 未显式设置runtime_directory时使用XDG_RUNTIME_DIR。

当前源码中的目录解析逻辑（settings.rs）按"配置值 > 环境变量 > 兜底"的优先级取值：

pub fn pueue_directory(&self) -> PathBuf { if let Some(path) = &self.pueue_directory { expand_home(path) } else if let Some(path) = dirs::data_local_dir() { path.join("pueue") } else { PathBuf::from("./pueue") } } pub fn runtime_directory(&self) -> PathBuf { if let Some(path) = &self.runtime_directory { expand_home(path) } else if let Some(path) = dirs::runtime_dir() { path } else { self.pueue_directory() } }

unix_socket_path()在未显式配置时使用whoami获取用户名生成pueue_{username}.socket；0.31.0 的变更正是让这一函数在无法获取用户名时返回Error::NoUsername错误（见 settings.rs 与 error.rs）。

5.2 配置文件读取与 PUEUE_CONFIG_PATH

0.25.0支持通过PUEUE_CONFIG_PATH环境变量指定配置文件（--config选项之外的第二条路径）。Settings::read（settings.rs）的查找顺序是：

1. --config参数指定的显式路径；
2. PUEUE_CONFIG_PATH环境变量；
3. 依次探测configuration_directories()（默认配置目录 + 当前目录）下的pueue.yml；
4. 都没找到则返回Settings::default()和config_found = false。

0.19.0 记录过Settings::read_with_defaults从"布尔首参"改为返回(Settings, bool)元组的破坏性变更，即上面第 4 步"是否找到配置文件"的语义。配置文件中的路径支持~展开（0.13.0 起，expand_home使用shellexpand::tilde）。

5.3 实验性特性：shell_command 与 env_vars

0.24.0（2023-06-13）正式加入两个新设置，0.25.0 标注为实验性：

• daemon.shell_command：配置执行任务命令的 shell 命令。源码注释给出的默认值是 Unix 下["sh", "-c", "{{ pueue_command_string }}"]，Windows 下为["powershell", "-c", "[Console]::OutputEncoding = [Text.UTF8Encoding]::UTF8; {{ pueue_command_string }}"]（settings.rs）。{{ pueue_command_string }}是占位符，运行时会被替换为实际命令；
• daemon.env_vars：向所有执行进程注入硬编码环境变量（HashMap<String, String>类型，见 settings.rs）。

这两个特性被主仓库 3.3.0 同步标记为 "experimental"，因为"与 shell 打交道总是很棘手，需要更多测试"。

5.4 compress_state_file：压缩状态文件

0.29.0新增daemon.compress_state_file设置（默认false，见 settings.rs）。CHANGELOG 与主仓库 4.0.0 给出了详细数据：状态文件以环境变量为主的重复性数据导致文件很大，gzip 压缩可达到约 10~15 倍的压缩率（400 个任务时从约 2MB 缩至约 120KB），代价是保存时间从约 8ms 增至约 20ms——"用一点 CPU 换取 I/O 操作"，特别适合 I/O 受限或嵌入式环境。主仓库的 pueue/benches/save_compressed_state.rs 正是针对这一场景的基准测试。

5.5 其余关键配置项的时间线

• 0.19.5：新增配置 PID 路径的选项，即shared.pid_path，默认位于runtime_directory/pueue.pid（settings.rs）；
• 0.21.0：新增Settings.shared.alias_file，用于指定pueue_aliases.yml的位置，默认位于配置目录（settings.rs）；
• 0.16.0 / 0.17.1：新增status的时间/日期时间格式配置，默认值分别为%H:%M:%S与%Y-%m-%d\n%H:%M:%S（setting_defaults.rs）；
• 0.17.0 / 0.17.2：新增client.restart_in_place配置（默认false，因为原地重启会丢失此前失败任务的日志）；
• 0.19.2：让大多数配置节变为可选（#[serde(default)]遍布各字段）；
• 0.19.0：移除无效的settings.daemon.default_parallel_tasks设置；
• 0.18.1：读取配置时总是插入"default"组（PUEUE_DEFAULT_GROUP常量定义于 state.rs）；
• 0.20.0：State不再持有配置副本（因为组配置已从配置文件移出，改为 CLI 管理）。

配置系统还支持profiles：Settings中的profiles: HashMap<String, NestedSettings>配合load_profile()方法实现多配置档（settings.rs），NestedSettings刻意不允许嵌套 profiles 以防止自引用，settings.rs 中的test_load_profile与test_error_on_missing_profile覆盖了这两条路径。

六、任务数据模型细节：优先级、时间戳与标签

CHANGELOG 记录了Task结构在数据字段层面的多次扩充：

• 0.21.0：新增Task.enqueued_at与Task.created_at元数据字段；支持编辑任务标签（label/delete_label相关字段进入TaskToRestart与EditMessage）；
• 0.23.0：新增priority字段；
• 0.26.0（2024-03-22）：priority进入EditResponseMessage、EditMessage与TaskToRestart——这让pueue edit --priority与pueue restart --edit-priority成为可能（主仓库 3.4.0 对应实现了这两个 CLI 选项）；
• 0.25.0：新增Task::is_stashed()、Setting的Default实现。

当前Task结构（task.rs）包含：id、created_at、original_command、command、path、envs、group、dependencies、priority、label、status。注意original_command与command两个字段并存：前者是用户输入的原命令，后者是别名展开后的实际执行命令（Task::new中两者在创建时相同，见 task.rs）。

一个值得一提的安全细节：Task与AddRequest都实现了自定义Debug，把envs字段输出为"hidden"——因为环境变量中可能包含密钥，用户复制调试日志时可能泄露敏感信息（task.rs、request.rs）。TaskLogResponse同样隐藏了output字段（response.rs）。

七、错误处理：更精确的上下文

0.19.4（2022-03-12）重构了错误类型：

• 新增Error::IoPathError——携带路径与操作描述的 I/O 错误，为路径相关错误提供更好的信息；
• 新增Error::RawIoError——已有上下文包裹的通用 I/O 错误；
• 移除Error::LogWrite、Error::LogRead、Error::FileNotFound，统一归入IoPathError。

当前 error.rs 的枚举完整呈现了这一体系，值得注意的成员包括：

• UnexpectedPayload(ciborium::Value)——收到"合法但意外"的消息（版本不匹配的典型信号），错误文案提示 "Are you up-to-date?"；
• MessageTooBig(usize, usize)——DoS 防护触发的错误；
• UnixSocketExists——创建 socket 时发现已有活跃守护进程；
• NoUsername(String)——0.31.0 引入，unix_socket_path无法确定用户名时抛出，并提示"在配置中显式指定 socket 路径"。

另外 0.19.3 将所有消息与结构体中的路径字段改为PathBuf；0.12.2 的 Clippy 调整把函数参数类型从&PathBuf变为&Path（利用 Deref 保持反向兼容）。这些细节共同保证了错误信息与类型边界的整洁。

八、平台支持与依赖维护

CHANGELOG 中的平台与依赖记录同样值得关注：

• 0.27.0移除了netbsd支持（但主仓库 4.0.0 又新增了 NetBSD 支持，pueue侧存在 process_helper/netbsd.rs）；
• 0.25.1将ring从 0.16 升到 0.17 以支持 riscv64；
• 0.21.2 / 0.21.3处理了 Apple 平台的darwin-libproc依赖问题（原库被删除后改用补丁 fork，最终切换到libproc::processes::pids_by_type()API），同时 0.13.0 添加了对其他 Apple 平台的支持；
• 0.31.1（2026-03-02）更新 nix 及相关依赖以修复s390x 构建；
• 0.31.0将rand升级到 v0.10（Cargo.toml 中rand = { version = "0.10", optional = true }可印证）、whoami升级到 v2（Unix 目标下可见，见 Cargo.toml）。

这些平台工作大多由社区贡献完成，体现了"主项目专注 Linux、Apple/Windows 由社区共同维护"的协作模式。

九、兼容性保障：向后兼容测试

pueue-lib 对"配置文件与状态文件向后兼容"有明确承诺：从 0.15.0 起，序列化的设置文件必须能无条件恢复，否则即为破坏性变更、需要 major 版本号变更。

这一承诺由测试落实：tests/settings_backward_compatibility.rs 使用仓库内置的 tests/data/v0.15.0_settings.yml 旧配置文件验证Settings::read能成功解析；tests/state_backward_compatibility.rs 则用 tests/data/v4.0.0_state.json 验证状态文件的反序列化。主仓库侧另有 pueue/tests/daemon/state_backward_compatibility.rs 与 pueue/tests/daemon/data/v4.0.0_state.json。

消息层也有专门的协议测试：test_single_huge_payload（10 万字符载荷往返）、test_successive_messages（快速连续消息）、test_restricted_payload_size（恶意大载荷拒绝）三个用例均内联在 network/protocol.rs 的测试模块中，覆盖了传输协议的关键边界。

十、给库使用者的演进启示

回看 0.11 到 0.31 的整个演进过程，可以提炼出几条对 pueue-lib（及类似共享库）使用者的实用启示：

1. 协议版本 ≠ 库 API 版本：SemVer 约束的是 daemon/client 通信 API。升级 pueue-lib 时，若依赖其 Rust API，应视为可能破坏；若只是实现客户端，则应优先保证与守护进程的协议兼容（PROTOCOL_VERSION即 crate 版本，需一致或向后兼容）。
2. 消息类型是核心契约：Request/Response分裂后，实现自定义客户端只需send_request/receive_response成对使用（prelude），参考 Client 示例 即可快速上手。
3. 最小化特性组合：第三方应用可按需启用 feature（settings/network/network_blocking/log/client），无 tokio 依赖的环境可用network_blocking（Cargo.toml）。
4. 状态模型已由类型系统保障：TaskStatus枚举的变体字段即运行时契约，解析Response::Status(Box<State>)时应按枚举变体而非扁平字段处理。
5. 安全边界已内置：共享 secret（512 字符随机串，见 secret.rs）、TLS 双向验证、消息大小上限三者共同构成传输安全；实现服务端时务必沿用receive_bytes_with_max_size的限制策略。

结语

pueue_lib的 CHANGELOG 不只是版本流水账，它忠实记录了 Pueue 从"单体脚本调度器雏形"走向"协议清晰、状态安全、可被第三方复用的共享库"的每一步决策：bincode 换 cbor 换来了协议向后兼容，Message分裂为Request/Response换来了类型安全，运行时字段收编进TaskStatus换来了编译期不变量，feature flags 化换来了按需裁剪的灵活性。理解这些演进，既能帮你正确使用 pueue-lib 编写自己的前端或管理工具，也能为设计长期演进的 Rust 共享库提供一份难得的实践样本。

如需深入某一部分，建议继续阅读：

• 协议与消息： pueue_lib/src/network/protocol.rs、pueue_lib/src/message/request.rs、pueue_lib/src/message/response.rs
• 状态与任务： pueue_lib/src/state.rs、pueue_lib/src/task.rs
• 配置系统： pueue_lib/src/settings.rs、pueue_lib/src/setting_defaults.rs
• 网络与客户端： pueue_lib/src/network/mod.rs、pueue_lib/src/network/client.rs

• 任务调度
• CLI