BIZ-104 v1.0: pre-trim_multica_comment 绕路补丁 + 单测 + 文档
Phase ③ pre-trim 绕路补丁实施版： - pre_trim_multica_comment.py (v1.0.0): ≤4KB 硬截断 + mention 剥离 + 嵌套表降级 + 代码块合并 + .log 落盘 - test_pre_trim_multica_comment.py: 12 项单元测试全通过（长 md/嵌套表/代码块/中英混排/mention/.log/版本戳） - BIZ-104_pre-trim_multica_comment_v1.0.md: BIZ-38 版本化文档（部署/集成/测试/风险/CHANGELOG） 根因：multica proxy 0.4.35 二进制在边界解析 openclaw stdout 时截断/丢弃长 markdown，错误码 openclaw returned no parseable output（strings 提取确认）。 COO 拍板：≤4KB 阈值；保留原 output 到 .log；单测覆盖 4 类样本；按 BIZ-38 版本控制。 Co-author: 严维序（opengineer） Approval: 陆怀瑾（COO）
This commit is contained in:
严维序 opengineer
@@ -0,0 +1,160 @@
|
||||
# BIZ-104 pre-trim_multica_comment 文档 v1.0
|
||||
|
||||
> 版本：v1.0（实施版）
|
||||
> 编制：严维序（opengineer）
|
||||
> 日期：2026-08-31
|
||||
> 状态：已部署，待验证
|
||||
> BIZ 编号：BIZ-104 Phase ③
|
||||
> 适用：BIZ-38 模板兼容
|
||||
|
||||
---
|
||||
|
||||
## 一、背景
|
||||
|
||||
**BIZ-104**：openclaw comment reply 解析器（multica proxy 0.4.35 Go binary）截断/丢弃结构化 Markdown 回复。
|
||||
|
||||
- 错误码：`openclaw returned no parseable output`（来源：multica 二进制 strings 提取确认）
|
||||
- 触发：长 markdown + 嵌套表 + 多代码块 + mention 链接
|
||||
- 影响：所有 agent 通过 multica comment reply 路径发布内容
|
||||
|
||||
详见 BIZ-104_INVESTIGATION.md。
|
||||
|
||||
---
|
||||
|
||||
## 二、解决方案
|
||||
|
||||
### 方案 A（已采用）：openclaw 端 pre-trim 绕路补丁
|
||||
|
||||
**位置**：`shared/scripts/pre_trim_multica_comment.py`
|
||||
|
||||
**触发**：在 agent turn 输出到 multica comment reply 路径前调用 `pre_trim_for_multica_comment(text, ...)`。
|
||||
|
||||
**核心参数**：
|
||||
|
||||
| 参数 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| `max_bytes` | 4096 (4 KB) | COO 拍板，硬上限 |
|
||||
| `log_path` | `/tmp/pre_trim_multica.log` | 原 output 落盘路径 |
|
||||
|
||||
**精简动作链**（按顺序）：
|
||||
|
||||
1. **strip_mention_links** — `[@Name](mention://agent/UUID)` → `@Name`；`[MUL-XXX](mention://issue/UUID)` → `MUL-XXX`
|
||||
2. **flatten_tables** — 嵌套单元格（行内 | 字符数 > 预期列数 或 行长 > 200）→ 折叠为 `| \`...\` |`
|
||||
3. **merge_code_blocks** — >2 个代码块 → 保留首尾 2 块 + 中间省略说明
|
||||
4. **byte_truncate** — 字节硬截断，追加 `[\n...已截断，原文已落 .log]` 提示
|
||||
|
||||
---
|
||||
|
||||
## 三、版本与签名（BIZ-38）
|
||||
|
||||
| 字段 | 值 |
|
||||
|------|-----|
|
||||
| 模块版本 | v1.0.0 |
|
||||
| BIZ 编号 | BIZ-104 |
|
||||
| Phase | ③ pre-trim 绕路补丁 |
|
||||
| 作者 | 严维序（opengineer） |
|
||||
| 审批 | 陆怀瑾（COO） |
|
||||
| 部署日期 | 2026-08-31 |
|
||||
| 部署路径 | `/home/vincent/.openclaw/workspace/shared/scripts/pre_trim_multica_comment.py` |
|
||||
| 单测覆盖 | 12 项（长 md/嵌套表/代码块/中英混排/mention/.log/版本戳） |
|
||||
|
||||
---
|
||||
|
||||
## 四、集成方式
|
||||
|
||||
### 4.1 心跳集成（推荐）
|
||||
|
||||
在 `heartbeat_helper.py` 的输出后处理钩子中调用：
|
||||
|
||||
```python
|
||||
from pre_trim_multica_comment import pre_trim_for_multica_comment
|
||||
|
||||
def post_to_multica(text: str) -> str:
|
||||
result = pre_trim_for_multica_comment(
|
||||
text,
|
||||
max_bytes=4096,
|
||||
log_path="/tmp/pre_trim_multica.log",
|
||||
)
|
||||
return result["trimmed"]
|
||||
```
|
||||
|
||||
### 4.2 CLI 单独使用
|
||||
|
||||
```bash
|
||||
# 自检
|
||||
python3 pre_trim_multica_comment.py --self-test
|
||||
|
||||
# 处理文件
|
||||
python3 pre_trim_multica_comment.py --input comment.md --output trimmed.md
|
||||
|
||||
# stdin → stdout + 元数据 JSON
|
||||
echo "long text..." | python3 pre_trim_multica_comment.py --json --log /tmp/trim.log
|
||||
|
||||
# 限制阈值
|
||||
echo "long text..." | python3 pre_trim_multica_comment.py --max-bytes 2048
|
||||
```
|
||||
|
||||
退出码：
|
||||
- `0` — 未截断（直接可用）
|
||||
- `2` — 已截断（监控信号，不阻断流程）
|
||||
|
||||
### 4.3 接入位置候选
|
||||
|
||||
1. **multica_proxy.py**（推荐）— 在 `run_multica("issue", "comment", "add", ...)` 调用前对 content 做 pre-trim
|
||||
2. **agent_runtime.py** — 在 agent turn 出口钩子调用
|
||||
3. **heartbeat_helper.py** — 在 `print_heartbeat_report()` 后调用（仅调试用）
|
||||
|
||||
---
|
||||
|
||||
## 五、测试覆盖
|
||||
|
||||
### 5.1 单元测试（12 项，全通过）
|
||||
|
||||
```bash
|
||||
python3 -m unittest test_pre_trim_multica_comment -v
|
||||
```
|
||||
|
||||
| 测试类 | 覆盖 |
|
||||
|--------|------|
|
||||
| TestPreTrimLongMarkdown | 长 markdown 截断 / 短文本不截断 |
|
||||
| TestPreTrimNestedTable | 嵌套单元格折叠 / 简单表保留 |
|
||||
| TestPreTrimMultipleCodeBlocks | 多块合并 / 2 块保留 |
|
||||
| TestPreTrimMixedLanguage | 中英混排字节计数 |
|
||||
| TestPreTrimMentionLinks | agent/issue mention 剥离 |
|
||||
| TestPreTrimLogPersist | .log 落盘验证 |
|
||||
| TestPreTrimVersion | 版本戳格式验证 |
|
||||
|
||||
### 5.2 真实场景冒烟
|
||||
|
||||
- 输入：13.2 KB 中文 + 嵌套表 + 4 代码块 + mention
|
||||
- 输出：4096 B（截断）
|
||||
- 动作链：strip_mention_links → flatten_tables → merge_code_blocks → byte_truncate
|
||||
|
||||
---
|
||||
|
||||
## 六、风险与限制
|
||||
|
||||
1. **信息损失**：长 markdown 经嵌套表/代码块合并后，细节不可见（落 .log 可回溯）
|
||||
2. **不修复根因**：multica 二进制解析 bug 仍存在，需 OpenClaw 维护方后续修复
|
||||
3. **阈值硬编码**：4 KB 是 MVP 经验值，后续可根据 multica proxy 真实截断点上浮
|
||||
4. **无回滚机制**：当前未做版本回滚 hook（依赖 git 历史）
|
||||
|
||||
---
|
||||
|
||||
## 七、CHANGELOG
|
||||
|
||||
### v1.0.0 (2026-08-31) — BIZ-104 Phase ③ 初版
|
||||
|
||||
- 首版部署
|
||||
- 12/12 单元测试通过
|
||||
- 冒烟测试验证：13.2 KB → 4 KB
|
||||
- COO 拍板阈值 ≤4KB
|
||||
- 落盘路径 `/tmp/pre_trim_multica.log`
|
||||
|
||||
---
|
||||
|
||||
## 八、参考
|
||||
|
||||
- BIZ-104_INVESTIGATION.md（运维工程师私人 workspace）
|
||||
- specs/BIZ-13_运行稳定性保障规范_v1.0.md
|
||||
- plans/BIZ-25_定时心跳检查cron任务部署方案.md（BIZ-38 模板说明）
|
||||
Reference in New Issue
Block a user