Skip to content

👾 Open Computer Use – Open-Source Alternative to Codex Computer Use

Preserve link role for markdown links

Leoa20e53c104a1
diff --git a/docs/histories/2026-05/20260507-2026-preserve-link-role-for-markdown.md b/docs/histories/2026-05/20260507-2026-preserve-link-role-for-markdown.md
new file mode 100644
index 0000000..345946c
--- /dev/null
+++ b/docs/histories/2026-05/20260507-2026-preserve-link-role-for-markdown.md
@@ -0,0 +1,29 @@
+# Markdown 链接保留 link role
+
+## 用户诉求
+
+继续对齐官方 `computer-use` 的 state renderer,让 Lark / Electron app 的返回既可读又保留可操作元素语义。
+
+## 主要改动
+
+- 修正 `AXLink` 在 suppress children 后被泛化成 `container` 的问题。
+- Markdown 链接行现在保留 `link [label](url)` 形态,而不是 `container [label](url)`。
+- 补充单测覆盖 `AXLink` 压平后仍保留 `link` role 的边界。
+
+## 设计动机
+
+上一轮将带 URL 的链接压平成 Markdown 文本后,Lark 回归显示行头变成了 `container`。这提升了可读性,但弱化了元素语义。官方 renderer 逆向中同时存在 `flattenLinksIntoMarkdownText` 和 `role` / `roleDescription` 字段,因此更合理的形态是保留 link role 并压平文本。
+
+## 验证
+
+- Lark 本地回归确认链接行输出为 `link [label](url)`。
+- `swift test`
+- `./scripts/build-open-computer-use-app.sh debug`
+- `./scripts/run-tool-smoke-tests.sh`
+- `./scripts/check-docs.sh`
+- `git diff --check`
+
+## 受影响文件
+
+- `packages/OpenComputerUseKit/Sources/OpenComputerUseKit/AccessibilitySnapshot.swift`
+- `packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift`
diff --git a/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/AccessibilitySnapshot.swift b/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/AccessibilitySnapshot.swift
index 581d6c1..b06f7a2 100644
--- a/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/AccessibilitySnapshot.swift
+++ b/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/AccessibilitySnapshot.swift
@@ -1351,7 +1351,7 @@ private func isPlainGenericTextContainer(_ element: AXUIElement, children: [AXUI
return true
}
-private func displayRoleText(
+func displayRoleText(
baseRoleText: String,
role: String,
title: String?,
@@ -1362,6 +1362,10 @@ private func displayRoleText(
return ""
}
+ if role == "AXLink" {
+ return baseRoleText
+ }
+
if suppressChildren {
return "container"
}
diff --git a/packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift b/packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift
index 95b8547..c4fb4be 100644
--- a/packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift
+++ b/packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift
@@ -683,6 +683,19 @@ final class OpenComputerUseKitTests: XCTestCase {
XCTAssertEqual(meaningfulActions(["AXZoomWindow"], role: kAXButtonRole as String), ["zoom the window"])
}
+ func testAccessibilityRendererKeepsLinkRoleWhenSuppressingChildren() {
+ XCTAssertEqual(
+ displayRoleText(
+ baseRoleText: "link",
+ role: "AXLink",
+ title: "[Docs](https://example.com)",
+ label: "Docs",
+ suppressChildren: true
+ ),
+ "link"
+ )
+ }
+
func testAccessibilityRendererFormatsPlaceholderSegment() {
XCTAssertEqual(
formattedPlaceholderSegment(