From 7aec8fcabf71aaaf728bd35ec9d681b82e6ddafc Mon Sep 17 00:00:00 2001
From: brad1104 <brad1104@users.noreply.github.com>
Date: Mon, 10 Aug 2026 09:22:22 +0800
Subject: [PATCH] fix(docker): patch harness-agent MRO order to fix ACP null
 responses
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

orcakit-harness-agent 0.9.19 的 acp/server.py 中 _Agent 类继承顺序为
(Agent, HarnessACPAgent)，由于 Agent 是 Protocol 基类且其方法默认返回
None，Python MRO 优先解析 Agent 的空实现而非 HarnessACPAgent 的实际实现，
导致 ACP initialize / session/new 等方法返回 null，Octop 无法通过 ACP
协议对接外部编排器。

修复方案（三层覆盖）:
1. Dockerfile: 构建时 sed 修复 site-packages 中的源文件
2. docker-entrypoint.sh: 运行时检测并修复（覆盖旧镜像场景）
3. patch-harness-agent-mro.sh: 独立脚本，供已运行容器手动修复

根本修复应在上游 harness-agent 仓库中将继承顺序改为
(HarnessACPAgent, Agent)，本 PR 为临时 workaround。
---
 docker/Dockerfile                 | 19 +++++++++++++++++
 docker/docker-entrypoint.sh       | 12 +++++++++++
 docker/patch-harness-agent-mro.sh | 34 +++++++++++++++++++++++++++++++
 3 files changed, 65 insertions(+)
 create mode 100644 docker/patch-harness-agent-mro.sh

diff --git a/docker/Dockerfile b/docker/Dockerfile
index 1bcfb65e..4c9fade2 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -127,6 +127,25 @@ RUN --mount=type=cache,target=/root/.cache/uv \
     && apt-get purge -y --auto-remove build-essential \
     && rm -rf /var/lib/apt/lists/* /tmp/*
 
+# 临时修复: orcakit-harness-agent 0.9.19 中 _Agent 类的 MRO 顺序问题
+#
+# 问题: harness_agent/acp/server.py 中 `class _Agent(Agent, HarnessACPAgent)`
+# 导致 Agent（Protocol 基类）的空实现优先于 HarnessACPAgent 的实际实现被调用，
+# 使 ACP initialize / session/new 等方法返回 null，Octop 无法通过 ACP 对接
+# 外部编排器（如 Multica）。
+#
+# 修复: 交换继承顺序为 `class _Agent(HarnessACPAgent, Agent)`，确保
+# HarnessACPAgent 的方法在 MRO 中优先解析。
+#
+# 上游修复发布后可移除此段。参考: https://github.com/TencentCloud/harness-agent
+RUN SERVER_PY="$(find /app/.venv/lib -path '*/harness_agent/acp/server.py' -print -quit)" \
+    && if [ -n "$SERVER_PY" ] && [ -f "$SERVER_PY" ]; then \
+        sed -i 's/class _Agent(Agent, HarnessACPAgent):/class _Agent(HarnessACPAgent, Agent):/' "$SERVER_PY"; \
+        echo "[Dockerfile] Patched harness_agent MRO order in: $SERVER_PY"; \
+    else \
+        echo "[Dockerfile] WARNING: harness_agent/acp/server.py not found, skipping MRO patch"; \
+    fi
+
 RUN mkdir -p /data/.octop
 
 EXPOSE 8088
diff --git a/docker/docker-entrypoint.sh b/docker/docker-entrypoint.sh
index ab76a2b9..edea5141 100644
--- a/docker/docker-entrypoint.sh
+++ b/docker/docker-entrypoint.sh
@@ -22,6 +22,18 @@ PORT="${OCTOP_PORT:-8088}"
 
 mkdir -p "$OCTOP_HOME"
 
+# 运行时修复: harness-agent MRO 顺序问题（与 Dockerfile 补丁配合，覆盖已运行旧镜像的场景）
+# 上游修复发布后可移除此段
+_patch_mro() {
+    local server_py
+    server_py="$(find /app/.venv/lib -path '*/harness_agent/acp/server.py' -print -quit 2>/dev/null || true)"
+    if [ -n "$server_py" ] && [ -f "$server_py" ] && grep -q 'class _Agent(Agent, HarnessACPAgent):' "$server_py"; then
+        sed -i 's/class _Agent(Agent, HarnessACPAgent):/class _Agent(HarnessACPAgent, Agent):/' "$server_py"
+        echo "[entrypoint] Patched harness_agent MRO order in: $server_py"
+    fi
+}
+_patch_mro
+
 if [ ! -f "$DB_FILE" ]; then
     echo "[entrypoint] 首次启动，正在初始化 Octop..."
 
diff --git a/docker/patch-harness-agent-mro.sh b/docker/patch-harness-agent-mro.sh
new file mode 100644
index 00000000..1f972168
--- /dev/null
+++ b/docker/patch-harness-agent-mro.sh
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# =============================================================================
+# 修复 orcakit-harness-agent 中 _Agent 类的 MRO 顺序问题
+#
+# 问题: harness_agent/acp/server.py 中 `class _Agent(Agent, HarnessACPAgent)`
+# 导致 Agent（Protocol 基类）的空实现优先于 HarnessACPAgent 的实际实现，
+# 使 ACP initialize / session/new 返回 null。
+#
+# 用法:
+#   # 在宿主机上修复运行中的容器
+#   docker exec <container_name> bash /docker/patch-harness-agent-mro.sh
+#
+#   # 或在容器内直接执行
+#   bash /docker/patch-harness-agent-mro.sh
+#
+# 上游修复发布后可删除此脚本。
+# =============================================================================
+set -euo pipefail
+
+SERVER_PY="$(find /app/.venv/lib -path '*/harness_agent/acp/server.py' -print -quit 2>/dev/null || true)"
+
+if [ -z "$SERVER_PY" ] || [ ! -f "$SERVER_PY" ]; then
+    echo "[patch] ERROR: harness_agent/acp/server.py not found"
+    exit 1
+fi
+
+if ! grep -q 'class _Agent(Agent, HarnessACPAgent):' "$SERVER_PY"; then
+    echo "[patch] SKIP: $SERVER_PY 已修复或模式不匹配"
+    exit 0
+fi
+
+sed -i 's/class _Agent(Agent, HarnessACPAgent):/class _Agent(HarnessACPAgent, Agent):/' "$SERVER_PY"
+echo "[patch] OK: 已修复 MRO 顺序 in $SERVER_PY"
+echo "[patch] 请重启 Octop 服务使修复生效"