# 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 模板说明）