Files

T

严维序 opengineer 8c931dde1c 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）

2026-08-31 08:32:59 +08:00

4.9 KiB

Raw Permalink Blame History

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 落盘路径

精简动作链（按顺序）：

strip_mention_links — [@Name](mention://agent/UUID) → @Name；[MUL-XXX](mention://issue/UUID) → MUL-XXX
flatten_tables — 嵌套单元格（行内 | 字符数 > 预期列数或行长 > 200）→ 折叠为 | \...` |`
merge_code_blocks — >2 个代码块 → 保留首尾 2 块 + 中间省略说明
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 的输出后处理钩子中调用：

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 单独使用

# 自检
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 接入位置候选

multica_proxy.py（推荐）— 在 run_multica("issue", "comment", "add", ...) 调用前对 content 做 pre-trim
agent_runtime.py — 在 agent turn 出口钩子调用
heartbeat_helper.py — 在 print_heartbeat_report() 后调用（仅调试用）

五、测试覆盖

5.1 单元测试（12 项，全通过）

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

六、风险与限制

信息损失：长 markdown 经嵌套表/代码块合并后，细节不可见（落 .log 可回溯）
不修复根因：multica 二进制解析 bug 仍存在，需 OpenClaw 维护方后续修复
阈值硬编码：4 KB 是 MVP 经验值，后续可根据 multica proxy 真实截断点上浮
无回滚机制：当前未做版本回滚 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 模板说明）

4.9 KiB Raw Permalink Blame History Unescape Escape