@research-copilot/plugin 1.1.17 → 1.1.19

package/dist/skills/llm-wiki/docs/spark/2026-06-15-omp-tool-status-events-design.md

@@ -0,0 +1,174 @@
+# OMP 风格动态工具状态设计
+
+日期：2026-06-15
+
+## 背景
+
+当前工作台已经能接收 agent 的工具开始和工具结束事件，但前端会把每次工具调用都追加到当前回复里。复杂任务一多，聊天区会变成工具流水账，用户很难看清“agent 此刻到底在做什么”。
+
+目标不是做一个简陋的工具提示，而是对齐 `omp` 的体验：当前动作始终以彩色动态状态呈现，历史动作沉淀为可折叠摘要。
+
+## 已确认方向
+
+- 动态工具条放在当前 assistant 回复内部，跟着当前回复走。
+- 工具条是彩色、动态、持续刷新的“跑马灯”状态，而不是普通灰色文本。
+- 工具结束后不再把所有动作摊开显示，改为丰富但折叠的历史摘要。
+- 不走 MVP 思维，优先做完整体验。
+- 采用“升级项目内 pi-agent 依赖 + 对齐新版 `omp` 事件模型”的路线。
+- 升级对象是本项目的依赖，不是用户本机全局安装的 `omp` 或 `pi-agent`。
+
+## 目标体验
+
+当 agent 开始调用工具时，当前 assistant 回复内部、正文之前出现一条动态工具条。它显示当前正在执行的动作，例如：
+
+- Reading `workbench/PRODUCT.md`
+- Writing `wiki/topics/agent-tools.md`
+- Running `npm run typecheck`
+- Searching current knowledge base
+
+同一轮回复里，如果工具连续切换，工具条只显示当前正在进行的一项，之前完成的动作进入折叠摘要。
+
+当 agent 开始输出正文时，工具条仍留在同一条回复内，固定在正文上方，不抢正文阅读。当前工具全部结束后，工具条消失或变为短暂完成态，历史摘要保留。
+
+## 历史摘要
+
+历史摘要默认折叠，但不是只显示一个数字。它要像 `omp` 一样让用户快速判断 agent 做过什么：
+
+- 按工具类型分组：Read、Write、Bash、Search、Skill 等。
+- 每组显示数量。
+- 每组显示少量关键目标，例如文件名、页面名、命令摘要。
+- 超过展示上限时显示“还有 N 项”。
+- 用户展开后可以看到完整工具清单。
+
+摘要示例：
+
+```text
+工具摘要
+Read (6)
+  ✓ SKILL.md:1-80
+  ✓ README.md:1-80
+  ✓ workbench/PRODUCT.md
+Write (4)
+  ✓ wiki/sources/...
+Bash (2)
+  ✓ npm run typecheck
+```
+
+## 底层升级策略
+
+先开分支验证项目内 `pi-agent` 依赖升级，而不是直接改功能。
+
+验证目标：
+
+1. 项目能安装成功。
+2. 后端能启动。
+3. 前端能连接后端。
+4. 基础对话能跑通。
+5. 当前知识库上下文仍能注入。
+6. Skill 调用仍能工作。
+7. 会话历史仍能读取。
+8. 新版事件里能拿到工具名、工具参数、工具状态、必要时的运行中更新。
+
+如果新版依赖改了包名、导出路径或事件格式，后端要增加一个适配层，把新版事件统一整理成前端使用的稳定事件。
+
+如果升级验证失败，不应退回到简陋前端方案；应记录失败点，并决定是补适配层、锁定可用版本，还是分阶段迁移。
+
+## 事件设计
+
+前端不直接依赖底层 `pi-agent` 原始事件。后端提供工作台自己的稳定事件：
+
+- `assistant_text_delta`：assistant 正文增量。
+- `tool_status_start`：一个工具开始或当前工具切换。
+- `tool_status_update`：工具参数、目标、运行中描述更新。
+- `tool_status_end`：工具完成、失败或取消。
+- `tool_status_summary`：一轮回复的工具摘要更新。
+- `assistant_done`：本轮回复完成。
+- `assistant_error`：本轮回复异常。
+
+每个工具事件至少包含：
+
+- 工具调用 ID。
+- 工具名。
+- 面向用户的动作标签。
+- 目标对象，例如文件名、页面名、命令摘要。
+- 状态：运行中、完成、失败、取消。
+- 分组类型。
+- 是否可放入折叠摘要。
+
+面向用户的动作标签优先来自新版事件里的自然语言意图；如果没有，就由后端根据工具名和参数生成。
+
+## 前端结构
+
+当前 `ChatPanel` 已经同时承担消息流、工具流、输入框、命令菜单、引用菜单等职责。实现时应把工具状态拆成独立小模块，而不是继续把逻辑塞进消息数组。
+
+建议拆分：
+
+- `ToolStatusRunway`：当前动态工具条。
+- `ToolHistorySummary`：折叠工具摘要。
+- `tool-status-model`：把 start/update/end 事件归并成当前状态和历史摘要。
+- `formatToolStatus`：把工具名和参数转成人能看懂的短句。
+
+消息对象里不再存一长串实时工具标记。工具状态应作为当前 assistant 回复的附属状态存在；历史消息只保留完成后的摘要数据。
+
+## 视觉设计
+
+动态工具条应满足：
+
+- 彩色流动背景或流动边框。
+- 有明确的当前动作动词。
+- 目标文字可截断，不撑破布局。
+- 工具切换时有轻微过渡。
+- 深色和浅色主题都可读。
+- 在手机宽度下不遮挡正文，不横向溢出。
+
+折叠摘要应满足：
+
+- 默认占用空间小。
+- 能一眼看出做过哪些类型的事。
+- 展开后清单结构清楚。
+- 不和正文 Markdown 表格、列表样式混在一起。
+
+## 错误和边界状态
+
+- 工具失败：当前工具条变为失败态，摘要中该项标红或标记失败。
+- 工具取消：当前工具条显示取消态，摘要保留已完成部分。
+- 工具事件缺参数：显示工具名和通用动作，不显示空目标。
+- 多个工具并行：工具条显示最近活跃工具，摘要中保留所有工具；如新版事件能提供并行状态，可显示“另有 N 项运行中”。
+- 长文件路径：中间截断，保留文件名或末尾路径。
+- 长命令：保留主命令和关键参数，展开后看完整命令。
+- 会话恢复：历史消息显示折叠摘要，不恢复动态跑马灯。
+
+## 验证方式
+
+升级依赖后先做底层验证：
+
+- 安装依赖。
+- 类型检查。
+- 启动后端和前端。
+- 发送普通对话。
+- 发送会触发知识库检索的问题。
+- 发送会触发 read/write/bash 的任务。
+- 检查 Skill 调用是否仍可用。
+
+界面实现后做体验验证：
+
+- 打开本地页面实际跑一次长任务。
+- 确认屏幕上始终只有一个当前工具条，而不是一长串工具。
+- 确认工具结束后出现折叠摘要。
+- 展开摘要，确认分组和明细正确。
+- 在深色和浅色主题下检查可读性。
+- 在窄屏尺寸下检查不溢出、不遮挡输入框。
+
+## 不做的事
+
+- 不改用户本机全局 `omp`。
+- 不直接修改 `node_modules`。
+- 不为了工具条重做整个聊天系统。
+- 不把完整工具输出全部展示在主聊天区。
+- 不把这次升级扩展成桌面打包或新知识库能力。
+
+## 成功标准
+
+用户给 agent 一个复杂任务时，聊天区不再被工具流水账占满。用户始终能看到 agent 当前正在做什么；任务结束后，也能通过折叠摘要快速确认 agent 读了什么、写了什么、跑了什么。
+
+最终观感应接近 `omp`：活、清楚、有节奏，而不是普通 Web 应用里的静态日志。

package/dist/skills/llm-wiki/install.ps1

@@ -0,0 +1,87 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+  llm-wiki Windows PowerShell install wrapper
+
+.DESCRIPTION
+  Fixes the combined encoding problem on Windows PowerShell 5.1:
+    - console default is GB2312 (CP936) on Chinese Windows
+    - $OutputEncoding defaults to ASCII (CP1252)
+    - Python subprocess sys.stdout.encoding defaults to gbk (cp936)
+  This wrapper forces UTF-8 across all three layers so install.sh Chinese
+  output and hook-generated JSON are not garbled (issue #16).
+
+  Steps:
+    1. chcp 65001 (console code page)
+    2. [Console]::InputEncoding / OutputEncoding = UTF-8
+    3. $OutputEncoding = UTF-8 (how PS decodes subprocess stdout)
+    4. PYTHONIOENCODING=utf-8 (Python subprocess output)
+    5. Invoke bash install.sh, forwarding all args
+
+  All Write-Host output is kept ASCII-only so this script works even when
+  PowerShell 5.1 parses the .ps1 file under Chinese ANSI (GBK) codepage
+  with no BOM. The actual Chinese UI comes from install.sh after handoff.
+
+.EXAMPLE
+  PS> powershell -ExecutionPolicy Bypass -File install.ps1 --platform claude
+
+.EXAMPLE
+  PS> powershell -ExecutionPolicy Bypass -File install.ps1 --platform codex --dry-run
+
+.NOTES
+  - Requires Git for Windows (Git Bash) or WSL to provide bash on PATH
+  - PowerShell 7+ users default to UTF-8 and can run bash install.sh directly
+  - This wrapper adjusts environment only; it does not alter install.sh logic
+#>
+
+[CmdletBinding()]
+param(
+  [Parameter(ValueFromRemainingArguments = $true)]
+  [string[]]$RemainingArgs
+)
+
+$ErrorActionPreference = 'Stop'
+
+# 1. Switch console code page to UTF-8
+$null = & chcp.com 65001
+
+# 2. Console input/output encoding
+[Console]::InputEncoding = [System.Text.Encoding]::UTF8
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+
+# 3. How PS decodes subprocess stdout bytes
+$OutputEncoding = [System.Text.Encoding]::UTF8
+
+# 4. Force Python subprocess stdout/stderr to UTF-8
+$env:PYTHONIOENCODING = 'utf-8'
+
+# 5. Detect bash
+$bashCmd = Get-Command bash -ErrorAction SilentlyContinue
+if (-not $bashCmd) {
+  Write-Host "[llm-wiki] Error: bash not found on PATH." -ForegroundColor Red
+  Write-Host "          Install Git for Windows first: https://git-scm.com/download/win" -ForegroundColor Red
+  exit 1
+}
+
+# Script root (use $PSScriptRoot to avoid null $MyInvocation.MyCommand.Path under -File)
+$scriptDir = $PSScriptRoot
+if ([string]::IsNullOrEmpty($scriptDir)) {
+  $scriptDir = Split-Path -Parent $PSCommandPath
+}
+$installSh = Join-Path -Path $scriptDir -ChildPath 'install.sh'
+
+if (-not (Test-Path $installSh)) {
+  Write-Host "[llm-wiki] Error: install.sh not found at $installSh" -ForegroundColor Red
+  exit 1
+}
+
+Write-Host "[llm-wiki] UTF-8 environment ready, launching install.sh..." -ForegroundColor Cyan
+
+# Forward args
+if ($null -eq $RemainingArgs -or $RemainingArgs.Count -eq 0) {
+  & bash $installSh
+} else {
+  & bash $installSh @RemainingArgs
+}
+
+exit $LASTEXITCODE