feat(github-copilot-sdk): bump version to v0.11.0 for performance & stability
- Fixed shared client pool bug to eliminate TTFT latency. - Added pure BYOK-only mode support. - Improved cross-user environment isolation for concurrency. - Resolved RichUI infinite vertical sizing loop. - Integrated client.ping() into stall detection. - Automatically hide TODO List widget after completion. - Synced all documentation and release notes.
This commit is contained in:
fujie
@@ -44,3 +44,6 @@ Edge cases or caveats to watch out for.
|
||||
| [openwebui-tool-injection.md](./openwebui-tool-injection.md) | How OpenWebUI injects parameters into Tool functions, and what the Pipe must provide |
|
||||
| [openwebui-mock-request.md](./openwebui-mock-request.md) | How to build a valid Mock Request for calling OpenWebUI-internal APIs from a Pipe |
|
||||
| [copilot-plan-mode-prompt-parity.md](./copilot-plan-mode-prompt-parity.md) | Why Plan Mode prompt logic must be shared between fresh-session and resume-session injection |
|
||||
| [richui-default-actions-optout.md](./richui-default-actions-optout.md) | How static RichUI widgets opt out of fallback prompt/link action injection |
|
||||
| [richui-declarative-priority.md](./richui-declarative-priority.md) | How RichUI resolves priority between declarative actions and inline click handlers |
|
||||
| [richui-interaction-api.md](./richui-interaction-api.md) | Recommended 4-action RichUI interaction contract for chat continuation, prefill, submit, and links |
|
||||
|
||||
72
.agent/learnings/github-copilot-sdk-hang-analysis.md
Normal file
72
.agent/learnings/github-copilot-sdk-hang-analysis.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# GitHub Copilot SDK 卡顿/悬停问题深度源码分析报告
|
||||
|
||||
## 📌 问题现象
|
||||
|
||||
用户反馈在 agent 处理过程中（工具调用、思考、内容输出），`github_copilot_sdk.py` 管道偶尔会卡住（界面转圈不停）。
|
||||
|
||||
## 🔍 事件流架构（SDK 源码分析）
|
||||
|
||||
通过阅读 `copilot-sdk` 源码 (`jsonrpc.py`, `client.py`, `session.py`)，事件流路径如下：
|
||||
|
||||
```
|
||||
Copilot CLI (subprocess)
|
||||
└─ stdout (JSON-RPC over stdio)
|
||||
└─ JsonRpcClient._read_loop() [daemon thread]
|
||||
└─ _handle_message()
|
||||
└─ notification_handler("session.event", params) [线程安全调度到 event loop]
|
||||
└─ CopilotSession._dispatch_event(event)
|
||||
└─ plugin handler(event) → queue.put_nowait(chunk)
|
||||
└─ main loop: await queue.get() → yield chunk
|
||||
```
|
||||
|
||||
## 🚨 已确认的三个卡顿根因
|
||||
|
||||
### 根因 1: Stall 检测豁免盲区
|
||||
|
||||
原始代码的防卡死检测仅在 `content_sent=False` 且 `thinking_started=False` 且 `running_tool_calls` 为空时才触发。一旦 agent 开始处理（输出内容/调用工具），所有豁免条件为真，防卡死机制永久失效。
|
||||
|
||||
### 根因 2: 工具调用状态泄漏
|
||||
|
||||
`running_tool_calls.add(tool_call_id)` 在 `tool.execution_start` 时添加，但如果 SDK 连接断开导致 `tool.execution_complete` 事件丢失，集合永远不为空，直接阻塞 Stall 检测。
|
||||
|
||||
### 根因 3: `session.abort()` 自身可能卡住（SDK 源码确认）
|
||||
|
||||
**SDK 源码关键证据** (`jsonrpc.py:107-148`):
|
||||
|
||||
```python
|
||||
async def request(self, method, params=None, timeout=None):
|
||||
...
|
||||
if timeout is not None:
|
||||
return await asyncio.wait_for(future, timeout=timeout)
|
||||
return await future # ← 无 timeout，永久等待！
|
||||
```
|
||||
|
||||
`session.abort()` 底层调用 `self._client.request("session.abort", ...)` **没有传 timeout**。
|
||||
当 CLI 进程挂死但 `_read_loop` 尚未检测到断流（例如 TCP 半开连接），`abort()` RPC 自身会无限等待响应，造成**修复代码自身也卡住**。
|
||||
|
||||
## ✅ 修复记录 (2026-03-18)
|
||||
|
||||
### 修复 1: `assistant.turn_end` / `session.error` 兜底清理
|
||||
|
||||
`running_tool_calls.clear()` — 即时清除孤儿工具状态。
|
||||
|
||||
### 修复 2: 绝对不活跃保护 (Absolute Inactivity Guard)
|
||||
|
||||
当距最后一个事件超过 `min(TIMEOUT, 90) × 2 = 180s` 且无任何新事件时，**无条件**推送错误并结束流。不受 `content_sent` / `thinking_started` / `running_tool_calls` 任何豁免条件限制。
|
||||
|
||||
### 修复 3: `session.abort()` 超时保护
|
||||
|
||||
所有 `session.abort()` 调用使用 `asyncio.wait_for(..., timeout=5.0)` 包裹。即使 abort RPC 自身卡住也不会阻塞主循环。
|
||||
|
||||
## 📊 修复后超时时间线
|
||||
|
||||
| 场景 | 保护机制 | 触发时间 |
|
||||
|------|----------|----------|
|
||||
| Turn 开始后完全无事件 | Primary Stall Detection | 90 秒 |
|
||||
| Agent 处理中突然断流 | Absolute Inactivity Guard | 180 秒 |
|
||||
| abort() 调用本身卡住 | asyncio.wait_for timeout | 5 秒 |
|
||||
| Turn 结束/Session 错误 | 兜底 running_tool_calls.clear() | 即时 |
|
||||
|
||||
---
|
||||
|
||||
*Created by Antigravity using Source-Code-Analyzer skill on 2026-03-18.*
|
||||
27
.agent/learnings/richui-declarative-priority.md
Normal file
27
.agent/learnings/richui-declarative-priority.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# RichUI Declarative Priority
|
||||
|
||||
> Discovered: 2026-03-16
|
||||
|
||||
## Context
|
||||
This applies to the RichUI bridge embedded by `plugins/pipes/github-copilot-sdk/github_copilot_sdk.py` when HTML pages mix declarative `data-openwebui-prompt` / `data-prompt` actions with inline `onclick` handlers.
|
||||
|
||||
## Finding
|
||||
Mixing declarative prompt/link attributes with inline click handlers can cause duplicate prompt submission paths, especially when both the page and the bridge react to the same click.
|
||||
|
||||
## Solution / Pattern
|
||||
The bridge now treats inline `onclick` as the default owner of click behavior. Declarative prompt/link dispatch is skipped when an element already has inline click logic.
|
||||
|
||||
If a page intentionally wants declarative bridge handling even with inline handlers present, mark the element explicitly:
|
||||
|
||||
```html
|
||||
<button
|
||||
onclick="trackClick()"
|
||||
data-openwebui-prompt="Explain this chart"
|
||||
data-openwebui-force-declarative="1"
|
||||
>
|
||||
```
|
||||
|
||||
## Gotchas
|
||||
Without the explicit override, keyboard/click dispatch for declarative actions will yield to inline `onclick`.
|
||||
|
||||
The bridge also keeps a short same-prompt dedupe window in `sendPrompt()` as a safety net, but the preferred fix is still to avoid mixed ownership unless you opt in deliberately.
|
||||
23
.agent/learnings/richui-default-actions-optout.md
Normal file
23
.agent/learnings/richui-default-actions-optout.md
Normal file
@@ -0,0 +1,23 @@
|
||||
# RichUI Default Action Opt-Out
|
||||
|
||||
> Discovered: 2026-03-16
|
||||
|
||||
## Context
|
||||
This applies to RichUI embeds generated by `plugins/pipes/github-copilot-sdk/github_copilot_sdk.py`, especially when a specific embed should render state without fallback prompt or link actions.
|
||||
|
||||
## Finding
|
||||
The RichUI bridge can add fallback action buttons based on declarative prompt/link metadata. Static embeds can explicitly opt out when their HTML includes `data-openwebui-no-default-actions="1"` or `data-openwebui-static-widget="1"`.
|
||||
|
||||
## Solution / Pattern
|
||||
Mark the embed root with both attributes and keep the embed wrapped through `_prepare_richui_embed_html(...)` when you explicitly want to suppress fallback actions.
|
||||
|
||||
Example:
|
||||
|
||||
```html
|
||||
<div class="w" data-openwebui-no-default-actions="1" data-openwebui-static-widget="1">
|
||||
```
|
||||
|
||||
## Gotchas
|
||||
If the opt-out markers are missing, RichUI fallback actions can reappear even after interactive row handlers have been removed from the widget itself.
|
||||
|
||||
This opt-out only suppresses fallback prompt/link injection. It does not affect the SQL-driven TODO refresh path, which still re-emits the widget through `type: embeds` after `todos` or `todo_deps` updates.
|
||||
89
.agent/learnings/richui-interaction-api.md
Normal file
89
.agent/learnings/richui-interaction-api.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# RichUI Interaction API
|
||||
|
||||
> Discovered: 2026-03-16
|
||||
|
||||
## Context
|
||||
This applies to RichUI HTML embeds generated by `plugins/pipes/github-copilot-sdk/github_copilot_sdk.py` when the page needs to talk back to the OpenWebUI chat UI.
|
||||
|
||||
## Finding
|
||||
The most reliable design is a small recommended interaction surface with only four primary actions:
|
||||
|
||||
1. continue chat now
|
||||
2. prefill chat input without sending
|
||||
3. submit the current chat input
|
||||
4. open an external link
|
||||
|
||||
Keeping the recommended API this small reduces LLM choice overload and makes multilingual HTML generation more consistent.
|
||||
|
||||
Advanced capabilities still exist, but they are intentionally treated as opt-in patterns rather than the default contract:
|
||||
|
||||
- copy text to clipboard
|
||||
- structured selection state
|
||||
- template-based prompt/copy actions driven by current selections
|
||||
|
||||
## Solution / Pattern
|
||||
Prefer declarative attributes first:
|
||||
|
||||
```html
|
||||
<!-- 1. Continue chat immediately -->
|
||||
<button data-openwebui-prompt="Explain this workflow step by step">Explain</button>
|
||||
|
||||
<!-- 2. Prefill the chat input only -->
|
||||
<button
|
||||
data-openwebui-prompt="Draft a rollout checklist for this design"
|
||||
data-openwebui-action="fill"
|
||||
>
|
||||
Draft in input
|
||||
</button>
|
||||
|
||||
<!-- 3. Submit the current chat input -->
|
||||
<button data-openwebui-action="submit">Send current draft</button>
|
||||
|
||||
<!-- 4. Open a real URL -->
|
||||
<a data-openwebui-link="https://docs.example.com">Docs</a>
|
||||
```
|
||||
|
||||
When JavaScript is genuinely needed, prefer the object methods:
|
||||
|
||||
```javascript
|
||||
window.OpenWebUIBridge.prompt(text);
|
||||
window.OpenWebUIBridge.fill(text);
|
||||
window.OpenWebUIBridge.submit();
|
||||
window.OpenWebUIBridge.openLink(url);
|
||||
window.OpenWebUIBridge.reportHeight();
|
||||
```
|
||||
|
||||
Use advanced patterns only when the page genuinely needs them:
|
||||
|
||||
```html
|
||||
<!-- Copy -->
|
||||
<button data-openwebui-copy="npm run build && npm test">Copy command</button>
|
||||
|
||||
<!-- Pick a structured selection -->
|
||||
<button data-openwebui-select="role" data-openwebui-value="reviewer">
|
||||
Reviewer
|
||||
</button>
|
||||
|
||||
<!-- Use the current selection in a follow-up action -->
|
||||
<button data-openwebui-prompt-template="Explain the responsibilities of {{role}}">
|
||||
Explain selected role
|
||||
</button>
|
||||
```
|
||||
|
||||
### Quick decision guide
|
||||
|
||||
- Need an immediate answer now → `data-openwebui-prompt`
|
||||
- Need the user to review/edit first → `data-openwebui-action="fill"`
|
||||
- Need to send what is already in chat input → `data-openwebui-action="submit"`
|
||||
- Need to open an external resource → `data-openwebui-link`
|
||||
- Need copy UX → `data-openwebui-copy`
|
||||
- Need pick-then-act UX → `data-openwebui-select` + template placeholder
|
||||
|
||||
For most pages, keep to one dominant interaction style and only 2-4 visible actions.
|
||||
|
||||
## Gotchas
|
||||
Inline `onclick` owns click behavior by default. If an element mixes inline click code with declarative prompt/link attributes, declarative handling is skipped unless `data-openwebui-force-declarative="1"` is present.
|
||||
|
||||
Legacy aliases such as `sendPrompt(...)` still work for compatibility, but new generated pages should prefer the smaller object-method API or the declarative contract above.
|
||||
|
||||
The bridge still keeps a short same-prompt dedupe window as a safety net, but the preferred design is to avoid mixed ownership in the first place.
|
||||
Reference in New Issue
Block a user