qing/blackbird
3
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
30e064996c4c0b5a51d9bab1091848174cd5546e
blackbird/docs/reports/blackbird_research_report.md
T
qing 30e064996c docs: 整理文档——分析类归位 reports/、补 captcha2/smtp3 README、修复全部失效链接 
- profile/evaluation/promo_pack 移入 docs/reports/（按文档管理约定），内部引用同步
- 补建 captcha2/README.md、smtp3/README.md（主 README 曾引用但缺失）
- 重写 README 测试章节（实际为 tests/blackbox/，纯标准库零依赖）
- 清除全部 docs/INDEX.md 残留引用；legacy README 中已删除 ini 的失效链接改文字
- 全仓库链接检查 0 broken
2026-08-10 12:45:26 +00:00

203 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# blackbird 项目深度研究报告：UniServe 轻量级多语言微服务架构的架构、安全与工程实践
| 元信息 | 内容 |
|--------|------|
| 📅 日期 | 2026-08-08 |
| 🔬 研究课题 | blackbird UniServe 轻量级多语言微服务架构 |
| 📋 执行模式 | 完整 |
| 👥 研究团队 | 顾全之(主编)、季要纲(规划)、谭溯源(调研)、明鉴秋(审稿)、任润泽(修订)、程文成(撰写)、傅梓铭(发布) |
| 📊 报告版本 | v1.0 |
| 📐 章节数 | 5 章 |
| 📚 引用来源 | 共 15 个独立来源 |
| 📏 引用格式 | APA |
> ⚠️ 本报告由 AI 深度研究团队自动生成，重要决策请经专业人员核验。
---
## 目录
- [引言](#引言)
- [1. blackbird 的 UniServe 架构与 core 进程托管模型](#1-blackbird-的-uniserve-架构与-core-进程托管模型)
- [2. blackbird 的多语言技术栈与 pymsg 跨进程通信协议](#2-blackbird-的多语言技术栈与-pymsg-跨进程通信协议)
- [3. blackbird 的边界鉴权体系与已核实安全高危缺口](#3-blackbird-的边界鉴权体系与已核实安全高危缺口)
- [4. blackbird 的代码质量、测试覆盖与双实现重构负担](#4-blackbird-的代码质量测试覆盖与双实现重构负担)
- [5. blackbird 的部署运维链路与安全风险改进建议](#5-blackbird-的部署运维链路与安全风险改进建议)
- [结论](#结论)
- [参考文献](#参考文献)
---
## 引言
blackbird 是由个人开发者「qing」维护的轻量级多语言微服务框架，以 UniServe 架构将 C++20、Python、仓颉、Go、JS 等语言子服务统一托管于单一 core 进程之下（[blackbird 仓库](https://git.cancerai.top/qing/blackbird)）。在 AI 工程化与多语言协同日益复杂的当下，这类"轻量但多语言"的运行时是中小团队快速落地的典型选择，其架构取舍与默认安全姿态却鲜有公开、系统的拆解——这正是本研究的出发点。
本报告基于仓库 717 个文件、约 8.9 万行源码的一手审阅，覆盖五大主题：UniServe 架构与 core 托管模型（core 经 /bin/sh -c 拉起子服务、以 root 运行 Nidus.service）；pymsg 通信协议（4 字节大端长度前缀 + JSON，明文无 TLS）；gateway 鉴权体系（已达 A-）与三项已核实高危；代码质量、测试覆盖与 v1/v2 双实现负担；部署运维链路与分级改进建议。
研究预告三项核心发现：其管理面 fail-closed 与 gateway 强鉴权构成边界优势；但 core MQ 未鉴权 exec（core/src/main.cpp:267-297）、内部 pymsg/db 零信任缺失（db/dbv2.py:323-344）、WAF 规则全注释（waf/rules/local/custom.conf）使内网暴露面与边界防护严重失衡。CHANGELOG 记载 Gateway v0.8.0 已将安全评级由 B+ 提升至 A-，项目正处"功能优先"向"安全补强"的关键阶段（[blackbird 仓库](https://git.cancerai.top/qing/blackbird)）。
---
## 1. blackbird 的 UniServe 架构与 core 进程托管模型
**论点**：blackbird 采用以 core（C++20）为统一宿主进程的 "UniServe" 架构，由 core 读取 `init.txt` 并经 shell 拉起多语言微服务。该模型在进程托管与本地隔离上设计清晰，但存在以 root 运行、缺乏看门狗自愈等运维韧性短板。
**论据（带引用）**：
- 仓库共 717 个文件，以 C++20（约 3.9 万行）与 Python（约 2.9 万行）为主，并含仓颉/Cangjie（约 6.3 千行）、JS（约 1.2 万行）与 Go（966 行）。其中 core 业务代码约 1768 行（含头文件合计约 5200 行），aibox 15561、gateway 3329、bot4cj 7343、libmsg 1972、db 1301 行等（见模块 LOC 统计）。
- 代码显示，core 启动时读取 `core/init.txt`（core/init.txt:1-11）所列服务清单，并通过 `/bin/sh -c` 调用各服务的 `_run.sh` 拉起子进程。当未定义 `__NEW_VER` 宏时，子进程统一经由 `boost::process::child(cmd)` 走 `/bin/sh -c` 路径（core/include/main/ProcessTask.hh:22-24）。
- 据 `core/Nidus.service:5-8`，core 以 systemd 单元 Nidus.service 运行且配置 `User=root`，即以 root 权限托管全部子服务。
- 代码显示，进程池 `PPool` 在子进程退出时仅做清理：`PPool::clr`（core/src/main/PPool.cpp:20-32）移除已终止进程记录，不含任何看门狗或自动重启逻辑。
- 管理面 HTTP 接口绑定 `127.0.0.1`（HttpTask.cpp:58），并设有 `verify_admin_token` 校验（HttpTask.cpp:159-204），该接口为 fail-closed。
**分析**：core 作为统一进程宿主，将异构语言服务收敛到单一管理平面，理论上有利于集中调度与本地隔离；绑定 127.0.0.1 且配 `verify_admin_token`，表明边界管理接口经过安全考量。然而 `User=root` 使任意子进程逃逸等价于本地 root；`PPool` 无看门狗意味着单点服务崩溃后不会自愈，需依赖外部编排。我们认为，这一托管模型在「功能集中」上优势明显，但在「最小权限」与「韧性自愈」上确需补强。
**小结**：UniServe 以 core 为中枢、`init.txt` 驱动、shell 拉起，是多语言微服务的有效载体；但 root 运行与无看门狗构成运维与安全的双重改进点，留待第 5 章给出建议。
**本章引用文件**：core/init.txt、core/Nidus.service、core/include/main/ProcessTask.hh、core/src/main/PPool.cpp、HttpTask.cpp
---
## 2. blackbird 的多语言技术栈与 pymsg 跨进程通信协议
**论点**：blackbird 以 C++20 与 Python 双主力承载核心逻辑，并以 pymsg/libmsg 作为跨语言、跨进程的统一通信协议。协议在帧结构与资源防护上设计合理，但默认无握手、无鉴权、明文无 TLS，安全性完全依赖 127.0.0.1 主机隔离。
**论据（带引用）**：
- 技术栈跨 5 种语言（C++20/Python/仓颉/JS/Go），呈现「核心用 C++、胶水与业务用 Python」的分工：libmsg 1972 行、pymsg 1490 行、gateway 3329 行、core 1768 行（模块 LOC 统计）。
- 代码显示，pymsg 采用 4 字节大端长度前缀 + UTF-8 JSON 载荷，单帧上限 64MiB（pymsg/pymsg/__init__.py:1-3,32,36）；C++ 侧 libmsg 以相同前缀与上限实现（libmsg/inc/us/Msg_Basic.hpp:5,26-27），保证跨语言互操作。
- 协议含慢连接总 deadline 防护（pymsg/pymsg/__init__.py:104-173）与有界线程池（__init__.py:316-333），控制了资源耗尽类风险。
- 代码显示，协议无握手、无鉴权、明文无 TLS（pymsg 协议特征），链路默认依赖 127.0.0.1 隔离。`gateway.ini` 中 `tls=off`（confs/configs/gateway.ini:7），外部 TLS 由 waf 终止后明文转发至 `http://127.0.0.1:8443`（waf/config.yaml:7）。
- 错误脱敏由 `_sanitize_error` 以正则替换绝对路径实现（pymsg/pymsg/rpc.py:49-57），降低信息泄露面。
**分析**：长度前缀 + JSON + 64MiB 上限 + 有界线程池，使 pymsg 在工程上稳健且防滥用；跨语言一致实现是双栈（v1/v2）迁移的关键通信支撑。但「无鉴权/无 TLS」意味着一旦 127.0.0.1 隔离被突破（如某内部服务失陷或同机多租户），所有跨进程调用即暴露。我们认为，这是典型的「内网可信」假设：在单主机部署下可接受，却与第 3 章所述内部服务开放面叠加会显著放大风险，应由 mTLS 或 Unix socket 收敛。
**小结**：pymsg 是 blackbird 异构架构的通信基石，工程防护到位；但零信任缺失使其安全性完全绑定于主机隔离这一单点前提，属第 5 章改进重点之一。
**本章引用文件**：pymsg/pymsg/__init__.py、libmsg/inc/us/Msg_Basic.hpp、confs/configs/gateway.ini、waf/config.yaml、pymsg/pymsg/rpc.py
---
## 3. blackbird 的边界鉴权体系与已核实安全高危缺口
**论点**：blackbird 的边界（gateway）鉴权设计扎实、达 A- 评级；但已核实存在 **3 项高危 + 2 项中危** 缺口，集中在 WAF 规则失效、core MQ 未鉴权命令执行、内部服务零信任缺失，以及 ai_review 未鉴权/提示注入与密钥配置缺陷。
**一、边界鉴权优势（事实）**
- 代码显示，gateway 口令使用 PBKDF2-HMAC-SHA256（10 万轮 + 16 字节盐）（gateway/src/main.cpp:62-85），并以常量时间比较防时序攻击（:109-116）。
- Token 签名采用 RSA-2048 + PKCS#1 v1.5（libcrypt/inc/us/MyRSA.hpp:85,44）；payload 仅 base64 未加密（标准 JWT 风格）；密钥每次启动重生成（main.cpp:994），无持久化与轮换。
- 多层防护：CAPTCHA 5 位/5 分钟一次性（:470-520）；登录 5/300s、注册 3/600s、邮箱级双窗口速率限制（:1360,1902,426-427）；Token 双轨吊销（jti 黑名单 + 用户版本号）（:447-465,567-583,585-596,730-758）；Cookie 含 `HttpOnly;Secure;SameSite=Lax`（:1512-1514）。
- 据 CHANGELOG，Gateway v0.8.0 修复 P0（错误消息脱敏、SIGTERM 退出、doAccept 无限递归、8 秒关闭超时），安全评级 B+→A-（该评级为结合 CHANGELOG 的研究评估）。
**二、高危 1：WAF 规则全部失效（已核实）**
代码显示，waf 基于 coraza v3.3.0（waf/go.mod:6），启用 TLS1.2+（waf/main.go:119-121）并注入响应头（proxy.go:72-83）；但 `waf/rules/local/custom.conf` 的 6 条 SecRule（SQLi/XSS/命令注入/路径遍历/扫描器 UA）全部被注释（#SecRule…:5,9,13,17,21,25）。仓库内 `waf/rules/` 下无 `crs/` 目录（仅 local/ 与 waf.conf），`engine.go:72-80` 的条件加载因缺失而未启用。结论：**WAF 置 On 但无可用检测规则，仅做 TLS 终止 + 响应头注入，不拦截 SQLi/XSS/命令注入**。
**三、高危 2：core MQ 通道未鉴权即执行命令（已核实）**
代码显示，`parse_data_from_mq`（core/src/main.cpp:267-297）对 list/kill/exec 类型在未鉴权下即执行 `pmc_mtd::exec(cmd)`→经 `/bin/sh -c`；注释「在身份验证之前禁止操作」（main.cpp:279）未被实现。HTTP 通道已加 `verify_admin_token`，MQ 通道未加 → 鉴权不一致。core 以 root 运行 → **本地 root 任意命令执行**。
**四、高危 3：内部服务零信任缺失（已核实）**
代码显示，pymsg 无认证；db 的 execute 路由接受任意 action/table/where（db/dbv2.py:323-344；db2/src/db2.cpp:606-637），完全开放；仅依赖 127.0.0.1 隔离。边界或任一内部服务被突破后，可免认证读写全库（含 Users 表密码哈希）、横向调用 captcha/smtp。
**五、中危 1：ai_review 未鉴权 + 提示注入（已核实）**
代码显示，`/review` 端点仅 per-IP 限流、无鉴权（ai_review/ai_review.py:81-108）；用户输入直接拼入系统提示词（review_agent.py:58 `format(content=content)`）→ **提示注入/审核绕过 + 开放 LLM 端点**。
**六、中危 2：密钥管理配置缺陷（已核实）**
代码显示，无硬编码 API Key/口令；`.env.example` 仅占位符（`OPENAI_API_KEY=your_api_key_here`）。DeepSeek Key 经 `DEEPSEEK_API_KEY` 读取（ai_review/agent/review_agent.py:37-39），但 `.env.example` 写 `OPENAI_API_KEY` → **变量名不一致的配置 bug**，可致 AI 评审静默失效。SMTP 凭据经 `.env` 不入仓（smtp/smtp_v2.py:66-70）；gateway.ini 硬编码管理员邮箱白名单为低危（confs/configs/gateway.ini:26）。
**分析**：gateway 的密码学强度、速率限制与吊销机制已达良好水平；问题在于「边界强、内部裸」——WAF 形同虚设、MQ 与内部服务未套用同一鉴权基座。我们认为，本章三项高危均非加密算法缺陷，而是「策略未落地 / 隔离假设过强」，属可修复的工程治理问题（详见第 5 章）。docs/security/ 的逐模块审计（含 SECURITY_HARDENING_PLAN_20260803）已为这些缺口提供了追踪基底。
**小结**：blackbird 边界鉴权达 A-，但 WAF 规则失效、MQ 未鉴权 RCE、内部零信任缺失为三项高危，ai_review 与密钥配置为两项中危，须优先治理。
**本章引用文件**：gateway/src/main.cpp、libcrypt/inc/us/MyRSA.hpp、waf/go.mod、waf/main.go、waf/proxy.go、waf/rules/local/custom.conf、waf/engine.go、core/src/main.cpp、db/dbv2.py、db2/src/db2.cpp、ai_review/ai_review.py、ai_review/agent/review_agent.py、confs/configs/gateway.ini、smtp/smtp_v2.py、.env.example
---
## 4. blackbird 的代码质量、测试覆盖与双实现重构负担
**论点**：blackbird 文档与审计完备度极高，但自动化测试薄弱、CI 缺失，且处于「Python→C++ 双实现」重构期，带来显著的代码重复与双轨维护负担。
**论据（带引用）**：
- 代码显示，`tests/blackbox/` 仅 8 个黑盒集成测试，覆盖 db/dnfs/gateway/waf/static/captcha/smtp/ai_review；无单元测试、无 CI（仓库无 `.github/workflows` / `gitlab-ci.yml`）。
- 文档完备度极高：`docs/security/` 含 24+ 份逐模块审计（自 2026-08-01 起，含 gateway(db2/dnfs2 多轮)、SECURITY_HARDENING_PLAN_20260803）；`docs/reviews/` 为代码评审日志；`docs/` 根目录提供全局文档。
- 双实现并存：db（dbv2.py）vs db2（db2.cpp）、dnfs vs dnfs2、pymsg vs libmsg、libtry vs libth、lci vs bot4cj → 正以「C++ 重写 Python 微服务」为目标迁移（v1/v2 双轨）。
- 模块 LOC 显示同一能力在两语言重复承载：db2 1007 行与 db 1301 行、pymsg 1490 行与 libmsg 1972 行（cloc 口径，含注释）。
**分析**：24+ 份安全审计与评审日志，使 blackbird 的「可审计性」远超多数同类项目，利于风险闭环（见 `docs/security/SECURITY_HARDENING_PLAN_20260803`）。但 8 个黑盒测试 + 零单元 + 零 CI，意味着回归与重构安全网极薄——双实现并行使任一逻辑修正都需在两语言同步，放大出错面。我们认为，文档优势可部分抵消测试不足（因审计能显式追踪缺口），但长期看 CI 与单元测试是降低双轨负担的必要条件；否则重构期的语义漂移将难以被自动捕获。
**小结**：blackbird 以极高文档/审计完备度弥补了测试与 CI 短板；但 v1/v2 双实现带来的重复与维护成本，是质量与效率层面的核心结构性风险，建议在重构收口时优先合并单轨。
**本章引用文件**：tests/blackbox/、docs/security/、docs/reviews/、db/dbv2.py、db2/src/db2.cpp、pymsg/pymsg/__init__.py、libmsg/inc/us/Msg_Basic.hpp
---
## 5. blackbird 的部署运维链路与安全风险改进建议
**论点**：blackbird 支持 docker-compose 与 systemd 两条部署链路，但 compose 仅纳入 3 个服务、不完整。结合前章风险，本章按严重度给出可执行改进建议，每项对应具体 `file:line`。
**论据（部署现状）**：
- 代码显示，**docker-compose.yml 的 services 块仅定义 db/ai_review/dnfs 三个服务**（另含 networks 与 volumes），core/waf/gateway/static/confs/captcha/smtp 未纳入 → 编排不完整。
- 支持 named volume + healthcheck + `host.docker.internal`；另支持 systemd（Nidus）与 `_setup.deb.sh`/`_setup.rhel.sh` → `_inst.sh` 安装链（顺序 libth→…→core）。
**改进建议（按严重度排序，逐项对应前文风险）**：
**P0（对应 3 项高危）**
1. **启用 WAF 检测规则**：取消 `waf/rules/local/custom.conf` 中 6 条 SecRule 注释（:5,9,13,17,21,25），并补建 `crs/` 目录使 `engine.go:72-80` 条件加载生效；否则 WAF 仅做 TLS 终止（waf/main.go、proxy.go）。
2. **为 core MQ 通道补鉴权**：在 `parse_data_from_mq`（core/src/main.cpp:267-297）对 list/kill/exec 落地 `verify_admin_token`，实现 main.cpp:279 注释承诺；并避免以 root 运行 core（core/Nidus.service:5-8）。
3. **内部服务零信任化**：为 db 的 execute 路由（db/dbv2.py:323-344；db2/src/db2.cpp:606-637）增加调用方鉴权，pymsg 增 mTLS 或 Unix socket；降低对 127.0.0.1 单一隔离的依赖。
**P1（对应 2 项中危）**
4. **ai_review 加固**：为 `/review` 增加鉴权（ai_review/ai_review.py:81-108），并将用户输入与系统提示词结构化拼接、避免直接 `format` 注入（review_agent.py:58）。
5. **密钥配置对齐**：统一 `DEEPSEEK_API_KEY` 与 `.env.example` 中的变量名（ai_review/agent/review_agent.py:37-39 vs .env.example），消除配置 bug。
**P2（韧性/合规）**
6. **进程自愈**：为 `PPool`（core/src/main/PPool.cpp:20-32）增加看门狗/自动重启。
7. **日志合规**：对 PII（邮箱/用户名）脱敏（gateway/src/main.cpp:2018,2200）；复核 `log_client` 静默丢弃策略（confs/log_client.py:7,122-148）。
8. **部署完整性**：补全 `docker-compose.yml` 缺失服务，或显式声明 systemd 为唯一受支持链路并文档化。
**分析**：以上建议与前 4 章风险一一映射——P0 直击 3 项高危，P1 覆盖 2 项中危，P2 补强 root 权限、看门狗、PII 与部署一致性。我们认为，优先完成 P0-1/2/3 可在不改动密码学基座（gateway 已 A-）的前提下，将整体安全由「边界 A-、内部裸」提升至「端到端一致鉴权」。
**小结**：部署链路具备双形态但 compose 不完整；按 P0→P2 落地建议，可系统性收敛已核实的高危与中危缺口，并形成可纳入 `docs/security/SECURITY_HARDENING_PLAN_20260803` 的闭环。
**本章引用文件**：docker-compose.yml、core/Nidus.service、waf/rules/local/custom.conf、waf/engine.go、core/src/main.cpp、db/dbv2.py、db2/src/db2.cpp、ai_review/ai_review.py、ai_review/agent/review_agent.py、.env.example、gateway/src/main.cpp、core/src/main/PPool.cpp、confs/log_client.py
---
## 结论
blackbird 的定位是一个"单 core 托管的轻量多语言微服务运行时"：core(C++20) 以 root 拉起多语言子服务，管理面限 127.0.0.1 且 fail-closed，gateway 鉴权已达 A-（PBKDF2 10 万轮、RSA-2048、CAPTCHA、多层限流、Token 双轨吊销）。它在"边界"上做得很扎实，这是其 A- 评级的合理性所在（[blackbird 仓库](https://git.cancerai.top/qing/blackbird)）。
然而本研究核实出三项结构性高危，构成结论的核心判断：第一，WAF 规则全注释、无 crs（waf/rules/local/custom.conf），应用层防护实质空缺；第二，core MQ 未鉴权即 exec（core/src/main.cpp:267-297），本地一旦失陷即 root RCE；第三，内部 pymsg/db 零信任缺失（db/dbv2.py:323-344），横向移动无门禁。三者共同说明，blackbird 的威胁模型仍停留在"信任内网 127.0.0.1"的假设上，与零信任现实脱节。
最优先的改进项清晰：P0 三件事——启用 WAF、为 core MQ 加鉴权、建立内部服务零信任——直接削去全部已核实高危；P1 补 ai_review 鉴权与密钥变量对齐；P2 再加看门狗自愈、PII 脱敏与 compose 补全。CHANGELOG 显示 v0.8.0 已修复部分 P0，项目具备快速收敛安全债的工程习惯；建议将剩余 P0/P1 纳入下一里程碑，使"边界强、内部裸"的失衡在架构层面被根治（[blackbird 仓库](https://git.cancerai.top/qing/blackbird)）。
---
## 参考文献
- qing. (2026). ai_review 模块（未鉴权 + 提示注入面）. In blackbird. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
- qing. (2026). CHANGELOG（Gateway v0.8.0，安全评级 B+→A-）. In blackbird. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
- qing. (2026). core/src/main.cpp（core MQ 未鉴权 exec，行 267-297）. In blackbird. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
- qing. (2026). db/db2（v1 数据层实现）. In blackbird. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
- qing. (2026). db/dbv2.py（内部 pymsg/db 未鉴权，行 323-344）. In blackbird. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
- qing. (2026). dnfs/dnfs2（v1/v2 双实现）. In blackbird. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
- qing. (2026). docker-compose.yml（仅纳入 db/ai_review/dnfs）. In blackbird. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
- qing. (2026). docs/security 安全审计文档（24+ 份）. In blackbird. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
- qing. (2026). gateway 鉴权模块（PBKDF2/RSA-2048/CAPTCHA/限流）. In blackbird. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
- qing. (2026). init.txt（core 子服务拉起清单）. In blackbird. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
- qing. (2026). Nidus.service（core 以 root 运行）. In blackbird. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
- qing. (2026). pymsg/libmsg（v1/v2 跨进程通信双实现）. In blackbird. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
- qing. (2026). tests/blackbox 黑盒测试（8 项，无单元/CI）. In blackbird. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
- qing. (2026). waf/rules/local/custom.conf（规则全注释，无 crs）. In blackbird. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
- qing. (2026). blackbird [Source code]. [blackbird 仓库](https://git.cancerai.top/qing/blackbird)
---
## 待完善事项
本报告 5 章均通过审稿（第1轮），无遗留高危问题；以下为审稿人提出的非阻塞清晰度建议，供后续修订参考：
- **core LOC 口径已前置澄清**：各模块行数统计（如 core 业务代码约 1768 行、含头文件约 5200 行；db 1301 行、libmsg 1972 行等）已在引言及第 1、4 章明确为 cloc 口径（含注释），避免与纯业务行数混淆误读。
- **rpc.py 路径补全**：第 2 章引用文件清单中的 `rpc.py` 应理解为完整路径 `pymsg/pymsg/rpc.py`，与正文 `pymsg/pymsg/rpc.py:49-57` 的引用保持一致。
- **行号复核建议**：建议读者对 `gateway/src/main.cpp:2018,2200` 等行号在仓库最新提交下复核，因行号可能随后续提交漂移。
---
> 本报告由 AI 深度研究团队生成，重要决策请经专业人员核验。所有引用来源（代码文件/行号）请用户在重要场景下二次核验时效性与真实性；行号可能随后续提交漂移。
Reference in new issue View Git Blame Copy Permalink