docs: 归档 actpred 与 bot4cj 对比研究报告到 reports/

含主推长文、短平快版本、Slogan 弹药库、配图建议

docs/blackbird_promo_pack.md

@@ -0,0 +1,142 @@
+# Blackbird 推广文案包
+
+> 项目定位：一套 DIY 的轻量级微服务架构（UniServe Framework），用 C++ / Python / Go / 仓颉混合实现，让个人和中小团队用极简方式拥有**自托管、可控、安全**的服务平台，免去 Kubernetes 等重型基础设施的复杂度。
+> 许可证：各模块均为 MIT 开源。
+
+---
+
+## 一、主推长文（适合技术社区 / 博客 / 公众号）
+
+### 标题备选
+1. **不想被云厂商绑架？一台服务器，自己搭出一座"微型城市"**
+2. **告别 Kubernetes 的笨重，Blackbird 让微服务回到纯粹的快乐**
+3. **Blackbird：给独立开发者的"乐高底座"，拼出你自己的服务平台**
+4. **你的数据你做主：这套开源框架，把云的能力装进一台机器**
+
+### 正文
+
+**你有没有过这种纠结？**
+
+想做一个属于自己的小产品——一个笔记应用、一个内部工具、一个带 AI 审核的社区。可一查部署，满屏都是 Kubernetes、Service Mesh、云厂商控制台……光是看懂账单和术语，热情就凉了一半。
+
+要是有一套东西，能像搭积木一样，让你用**一台服务器**就拥有"安全入口 + 统一鉴权 + 数据库 + AI 审核 + 业务功能"的完整能力，而且**完全自己掌控、代码开源、零云厂商绑架**——你会心动吗？
+
+这就是 **Blackbird（UniServe Framework）** 想做的事。
+
+---
+
+### 它是什么？一台服务器里的"微型城市"
+
+想象你拥有一座小城市。城市的每个功能，都由一个个**专注的小部门**负责，彼此之间通过内部街道高效协作，而整座城只有**一个安检门**对外营业：
+
+- 🛡️ **WAF 网关**——城市的安检门。统一终止 HTTPS、挡掉恶意流量（内置 OWASP 防护规则），外面的风雨进不来。
+- 🔑 **应用网关**——门内的派出所。负责统一鉴权和反向代理，确保每个请求都"验明正身"才放行。
+- 🗄️ **数据库服务**——城市的档案局。所有业务的数据读写都从这里过，集中、统一、本机隔离，安全又省心。
+- 🤖 **AI 内容审核**——城市的审查员。基于 RAG + 大模型自动把关内容安全，还能吸收人工反馈越用越聪明。
+- ⚙️ **进程守护核心（core）**——城市的市长。负责把各个"部门"拉起来、盯好它们别"罢工"，挂了自动重启。
+- 🌳 **树状笔记（dnfs）**、🤖 **AI 智能体（aibox）**、🦾 **硬件控制模块（bot4cj）**——城市里真正对外提供服务的"营业厅"和"工厂"，甚至可以控制树莓派的舵机做实体机器人。
+
+它不是某个单一应用，而是一套**可以长出各种应用的底座**。
+
+---
+
+### 为什么是 Blackbird，而不是"上云"？
+
+| 传统云原生 | Blackbird |
+|---|---|
+| 要学 K8s、运维集群、看云账单 | 一台机器 + 一个一键脚本搞定 |
+| 数据散落在厂商手里 | 数据完全自托管，你说了算 |
+| 出事要提工单等回复 | 代码开源（MIT），问题自己就能改 |
+| 技术栈绑定某家云 | C++/Python/Go/仓颉多语言自由组合 |
+
+Blackbird 不追求"承载百万 QPS 的巨型帝国"，它专注把**微服务真正有用的那部分收益**——能力拆分、统一入口、安全分层、可观测——用**最轻的量**交到你手里。
+
+---
+
+### 上手有多简单？
+
+仓库里准备好了安装脚本：
+
+```bash
+# Debian/Ubuntu
+./_setup.deb.sh
+# 或 RHEL 系
+./_setup.rhel.sh
+```
+
+然后 `systemctl start Nidus`，核心会按配置自动拉起所有服务。从外部访问，你只需要记住一个地址——`https://你的域名`，安全、鉴权、转发全在背后默默处理好。
+
+---
+
+### 它适合谁？
+
+- 🧑‍💻 **独立开发者 / 个人站长**：想拥有自己的服务平台，又不想被运维压垮。
+- 🏢 **中小团队**：需要一个可控、低成本的内部中台，不依赖外部 SaaS。
+- 🔐 **注重数据主权的人**：数据必须握在自己手里。
+- 🤖 **AI / 硬件爱好者**：想玩转 AI 智能体、嵌入式舵机，又想要一个稳的底座。
+
+---
+
+### 最后说一句
+
+Blackbird 不是要取代云，而是给你**另一种选择**：当世界都在把你推向更复杂的系统时，它轻声说——"其实，简单一点也挺好。"
+
+代码已开源，MIT 许可，欢迎来仓库看看、提 Issue、一起把这座城市建得更漂亮。
+
+👉 **项目地址：https://git.cancerai.top/qing/blackbird**
+
+---
+
+## 二、短平快版本（适合朋友圈 / V2EX / 掘金 / Reddit 等社区发布）
+
+### 版本 A（社区首发自荐）
+> 做了个东西想分享一下：**Blackbird**——一套自托管的轻量微服务框架。
+>
+> 痛点大家都懂：想自己搞个带登录、带数据库、带安全防线的应用，一上来就是 K8s 劝退三连。Blackbird 的思路是"进程托管式微服务"：一个 WAF 门口挡坏人，一个网关管鉴权，一个 core 当保姆盯着所有服务别挂，底下还能挂 AI 审核、树状笔记、甚至树莓派舵机。
+>
+> C++ / Python / Go / 仓颉混编，MIT 开源，一键脚本装好。适合不想被云厂商绑架、又想要微服务那点好处的个人和中小团队。
+>
+> 仓库在这 👉 https://git.cancerai.top/qing/blackbird ，求 Star、求拍砖。
+
+### 版本 B（更"人话"、带情绪钩子）
+> 被云厂商的复杂度和账单搞烦了？我给自己搭了个"微型操作系统"——Blackbird。
+>
+> 一台服务器，一个 HTTPS 入口，背后自动帮你：拦黑客（WAF）、验身份（网关）、存数据（数据库服务）、审内容（AI）、看门狗（进程守护）。还能顺手长出笔记应用、AI 机器人、甚至控制实体舵机。
+>
+> 不玩虚的，代码全开源（MIT），装起来就一个脚本。数据主权这事儿，自己握着才踏实。🔗 https://git.cancerai.top/qing/blackbird
+
+### 版本 C（极简推文风，限字数场景）
+> 🐦 Blackbird：把"云"塞进一台机器。
+> 自托管微服务底座 · WAF+网关+DB+AI审核一应俱全 · C++/Py/Go/仓颉混编 · 一键安装 · MIT 开源。
+> 不想被 K8s 和云账单绑架的独立开发者，来看看 👉 https://git.cancerai.top/qing/blackbird
+
+---
+
+## 三、标题 & Slogan 弹药库
+
+**一句话卖点（可根据场景选用）**
+- "微服务的好处，Kubernetes 的麻烦，二选一？Blackbird 说：都要，但只留好处。"
+- "你的数据、你的服务、你的规则——一台机器，全部自己说了算。"
+- "给独立开发者的一座城：一个门、一套规则、无限可能。"
+
+**Slogan 候选**
+1. Blackbird —— 轻装微服务，主权握手中。
+2. Blackbird —— 一台服务器，一座可控的城。
+3. Blackbird —— 把云的能力，装进自己的机器。
+4. Blackbird —— 微服务的纯粹主义。
+
+**社区讨论钩子（引发互动用）**
+- "你们个人项目都怎么部署的？我最近把整套微服务收进了 Blackbird，一台机器搞定，聊聊？"
+- "K8s 对个人项目是不是杀鸡用牛刀？分享一个轻量替代思路。"
+
+---
+
+## 四、配图 / 可视化建议（如需进一步增强传播）
+
+- **架构一图流**：画一座"城市"，城门标 WAF，城内分派出所（gateway）、档案局（db）、审查员（ai_review）、市长（core），街道连向各营业厅（dnfs/aibox/bot4cj）。比纯 ASCII 架构图更亲民。
+- **对比图**：左"传统云原生=重型城堡"，右"Blackbird=精致小院"，视觉化"轻量可控"。
+- **一键安装 GIF**：录一段从 clone 到 `systemctl start` 到打开 https 的全过程，15 秒讲清"简单"。
+
+---
+
+*文案由 Content Creator 基于项目 README 与代码结构整理撰写，可自由用于推广。如需针对特定平台（如小红书、B站 视频脚本、官网 Landing Page）做深度定制，告诉我目标受众和调性即可。*

docs/reports/actpred_bot4cj_research_20260809.md

@@ -0,0 +1,124 @@
+# 研究报告：actpred 与 bot4cj 项目
+
+> 研究时间：2026-08-09
+> 仓库：`git.cancerai.top/qing/blackbird`（micro_servers 单体仓库）
+> 结论先行：**两个项目是同一套「具身智能 / 机器人」技术栈的两个互补半环**——
+> `actpred` 是「大脑」（学出来的动作预测器），`bot4cj` 是「身体」（把动作落到真实硬件的执行引擎）。
+
+---
+
+## 1. 一句话定位
+
+| 项目 | 语言/框架 | 角色 | 输入 → 输出 |
+|------|-----------|------|-------------|
+| **actpred** | Python / PyTorch | 动作预测「大脑」 | 摄像头图像 + 历史动作序列 → 下一步连续动作（回归） |
+| **bot4cj** | 仓颉 Cangjie + C/C++/Lua | 硬件执行「身体」 | 矩阵式脚本(.mt) → 驱动舵机/IMU/扬声器 |
+
+---
+
+## 2. actpred 详解
+
+### 2.1 它是什么
+纯神经网络实现的**动作预测模块**：给定一帧摄像头图像（3×64×64）和前 `history_len` 步动作，回归预测当前步的连续动作向量。默认参数量约 140K，最大可到 ~2.3M（mobilenet + gru）。
+
+### 2.2 架构
+```
+图像(3×64×64) ──► CNN编码器(simple/mobilenet) ──► img_feat(128)
+                                                      │ concat
+动作历史(H×D)  ──► MLP/GRU编码器            ──► act_feat(64) ──► 融合头 ──► 动作(action_dim)
+```
+- **图像编码器**：`SimpleCNN`（4 层卷积+自适应池化）或 `MobileNetEncoder`（ImageNet 预训练，带离线权重容错）。
+- **历史编码器**：`MLPHistoryEncoder`（默认）或 `GRUHistoryEncoder`。
+- **损失**：纯 MSE 回归；优化器 AdamW + CosineAnnealingLR；早停 + 梯度裁剪。
+
+### 2.3 工程质量（亮点）
+- 全部超参通过 `config.py` 的 dataclass + CLI 覆盖，序列化进 checkpoint，推理时自动还原。
+- 数据层 `dataset.py` 设计扎实：自然排序键、按 episode 切分训练/验证、动作归一化统计量**只用训练集计算**（避免 val loss 失真）、`DataRecorder` 采集器。
+- `export_onnx.py` 导出 ONNX 并**自动用 onnxruntime 验证一致性**（最大差异打印）。
+- `test_actpred.py` 单元测试覆盖：排序、解析、前向、动态 batch、录制器、数据集、配置——质量明显高于一般研究脚本。
+
+### 2.4 默认配置
+`image_size=64, action_dim=8, history_len=5, backbone=simple, history_encoder=mlp, epochs=100, lr=1e-3`。
+
+---
+
+## 3. bot4cj 详解
+
+### 3.1 它是什么
+基于**仓颉（Cangjie）**编程语言 + Linux I2C 接口的**机器人硬件脚本解析器**。用一种「行列式表格」脚本（`.mt`）描述机器人的硬件构成与动作序列，解析后驱动真实硬件执行。目标平台是树莓派（aarch64），适配 Dashun 蜘蛛机器人（10 舵机 + 2 云台 + 扬声器）。
+
+### 3.2 架构分层
+```
+.mt 矩阵脚本
+   ↓  MatrixParser (P.cj) —— FSM 逐字符解析 → MatrixObject 链表
+   ↓  RobotStruct (r.cj) —— createHardVars() 构建硬件变量（工厂模式）
+   ↓  硬件实现 hd/*.cj：PCA9685 / Servo / MPU6050 / Speaker / Lua扩展
+   ↓  系统库 cpp/ + cuda/：I2C / 矩阵 / FFT / CNN / 音频
+   ↓  数学/NN 库 math/*.cj：Matrix1 / Tensor / Af / Nn1 / Adam / Kalman
+```
+
+### 3.3 关键设计
+- **MatrixVars_Hardware 基类**：用三个闭包回调统一硬件接口——`build()`（rise，拿资源）、`play()`（things，执行，输入输出均为 JsonValue）、`free()`（destroy，放资源）。硬件与脚本通过 `JsonValue` 解耦。
+- **硬件变量工厂**：`MtVars_I2C / Servo / Speaker / MPU6050_BIND / Alias / Lua`，从 `@I2C/@PCA9685/@Servo/@Speaker/@MPU6050` 块按名构建。
+- **Lua 扩展口**：任意未知 `@Block` 会路由到 `modules/<Name>.lua`（已接 ADS1115/ADS1256/PCA9685/SPI），C 层注册了 i2c_*/spi_*/milli_sleep 给 Lua 调用——这是「通用机器人硬件描述语言」野心的落点。
+- **I2C 总线保护**：20 槽锁数组，多硬件共享总线时互斥。
+- **资源释放**：`main.cj` 用 `try/finally` 显式 `deactive()`，规避仓颉 GC 析构时机不确定的风险。
+
+### 3.4 自带 NN 库（有意思的工程副产物）
+不依赖 PyTorch，纯仓颉实现了 `Nn1`（全连接，含前向/反向/权重更新）、`Matrix1`/`Tensor`、`Af`（6 种激活）、`Ini`（Xavier/Kaiming）、`Adam`、`cnn`、`fft`、`kalman`。配套 C/C++ 加速库（可切 CUDA）。这说明作者**试图把训练与推理都搬进仓颉生态**，为后续 DRL 端到端闭环做准备。
+
+### 3.5 已支持的硬件
+- **PCA9685**（0x40，50Hz PWM，角度→脉宽 0.5~2.5ms→12 位 PWM）。
+- **Servo**（max/min/offset 校准，max<0 自动翻转反向安装舵机）。
+- **MPU6050**（±500°/s，±8g，后台 10ms 采样线程 + 卡尔曼融合）。
+- **Speaker**（正弦波发声，5ms 淡入淡出）。
+
+---
+
+## 4. 两个项目的关系（核心结论）
+
+1. **闭环互补**：`actpred` 感知+记忆→预测动作（连续向量）；`bot4cj` 把动作变成舵机角度执行。
+   这在代码里已有明确意图：
+   - `bot4cj/src/main.cj` 预留了 DRL 分支（`--test`、注释掉的 `run_action_drl`、`-i/-o` 模型加载/保存）。
+   - `bot4cj/src/r.cj:838` 注释：`TODO(20260518-qing): 使用神经网络RNN直接根据动作+传感器脚本生成下一步动作`。
+2. **尚未真正打通**：目前两者**没有共享数据格式**。`actpred` 默认 `action_dim=8`，`bot4cj` 是 10 舵机 + 云台；`actpred` 输出 numpy 向量，`bot4cj` 消费 `.mt` 矩阵。集成是明确的「未来工作」。
+3. **同作者、同仓库**：均署名 `qing`，同属 `blackbird` 单体仓库，是同一具身智能蓝图的「预测端」与「执行端」。
+
+---
+
+## 5. 发现的问题与不一致（值得跟进）
+
+### 5.1 在代码中已修复、但 README 仍列为「已知问题」的旧项（README 滞后）
+- **D6（Softmax 雅可比错误）**：当前 `math/Af.cj:softmax_jacobian` 已实现正确——对角线 `y_i(1-y_i)`、非对角 `-y_i*y_j`，逻辑无误。
+- **D8（Tanh 导数错误）**：当前 `math/Af.cj:tanh_dot` 用 `1 - y_val*y_val`（`y` 即 tanh 输出），**这是正确的**。代码里 `NOTE(20260525-qing): 修复命名（x => y）` 表明作者已意识到此前是按输出 y 计算的。README 描述的旧 bug 已修。
+- → 建议：更新 `README.robot.md` 的「已知问题」表，删除/标注 D6、D8 已修复，避免误导。
+
+### 5.2 真实存在的代码瑕疵（未在 README 列出）
+- **`src/P.cj:147` 调试残留**：`parse()` 主循环里有 `print(s)`，**逐字符把脚本内容打到 stdout**。运行脚本时会污染标准输出（若将来用 stdout 与上层通信会很致命）。应删除或改为 debug 开关。
+- **`src/P.cj:93` 运算符优先级 bug**：`if (!values.size == 0 && !grp.size == values[...].size)`。`!values.size` 实际是对 size 整数取反（非零→false，零→true），**并非** `!= 0`。正确写法应为 `values.size != 0 && grp.size != values[...].size`。当前该行恒为假分支，导致「行未对齐」检测 `DoesNotSync` 实际**从不触发**，矩阵列数不一致时不会报错而可能静默错位。
+- **`src/P.cj:202` 转义不一致**：同文件里换行判断混用 `r'\n'` 与 `r"\n"`（后者是字面两字符，非换行符），属复制粘贴隐患。
+- **PCA9685 双实现**：`hd/PCA9685.cj` 仍保留主路径，但已标注「由 Lua 取代」（`modules/PCA9685.lua`），存在代码冗余（D4）。
+
+### 5.3 设计层面的待办（来自代码 TODO）
+- DRL 闭环未实现（`main.cj` 中 `run_action_drl`、`run_action` 均注释）。
+- `RobotStruct` 的 `@Action` 位置指示器（增量行动）未做，脚本路径写死 `./modules/`，未从环境变量/相对路径查找（r.cj:996, :998）。
+- `Tensor` 乘法仅支持 2D（D7），限制模型复杂度。
+
+---
+
+## 6. 总体评价
+
+| 维度 | actpred | bot4cj |
+|------|---------|--------|
+| 代码成熟度 | 高（测试完备、可导出 ONNX） | 中（功能可用，有调试残留与 TODO） |
+| 实用性 | 可直接训练/推理/集成 | 强硬件依赖（树莓派+I2C），需真机验证 |
+| 创新性 | 常规回归网络 | 「矩阵式机器人硬件 DSL」+ 纯仓颉 NN 库，有想法 |
+| 集成度 | 独立 | 与 actpred 的物理闭环尚未打通 |
+
+**建议下一步**：
+1. 修掉 `P.cj` 的 `print(s)` 与 `!size == 0` 两个硬 bug（影响解析正确性）。
+2. 更新 `README.robot.md`，把 D6/D8 标记为已修复。
+3. 定义 `actpred` 动作向量 ↔ `bot4cj` `.mt` 舵机角度的映射协议，打通预测—执行闭环（可先用 `action_dim=10` 对齐 10 舵机，或保留舵机+云台=12 维）。
+
+---
+*本报告基于源码静态阅读（actpred 全部 .py、bot4cj 的 README/main/P/r/nn/Af + 构建脚本 + 示例脚本），未做真机/真模型运行验证。*