magic-agent 2.4.3 → 2.6.3

package/internal/client/knowledge.go

@@ -0,0 +1,854 @@
+package client
+
+/* knowledge.go — 「发现 → 知识库」：OpenViking 的本机安装状态 + 一键安装 / 升级。
+ *
+ * OpenViking 是面向 AI Agent 的**上下文数据库**（viking:// 文件系统范式：记忆、资源、
+ * 技能统一组织，按需分层加载）。它**不是引擎** —— core 的 `--engines` 里没有它、也不该有：
+ * core 是「跑一轮 agent 就退出」的进程，没有「本机常驻一个知识库服务」这个概念。
+ * 所以这一层能力放在插件（magic-client）侧，与 plugins.go / scripts.go 同源。
+ *
+ * ── 纪律 ──
+ *  1) 命令**只来自下面这张表**（argv 数组，不过 shell）—— 接口不接受客户端传来的命令，
+ *     唯一的外部输入是 id 与 action，找不到就 404。否则这个接口等于一个任意命令执行器。
+ *  2) 不假装成功：探测不到就报 installed=false + 说明；安装失败把 stderr 原样流回去。
+ *  3) 版本号读不到就留空 —— 绝不编一个看起来对的版本号。
+ *  4) 不自动初始化服务：openviking-server init 需要 api_key，那一步留给人（note 里说清去哪配）。
+ *
+ * ── 三处「不确定」怎么处理（不猜）──
+ *   · CLI 名字：0.5.2 的 PyPI 文档只确认 `ov`，而火山引擎 0.4.15 的文档用 `openviking`。
+ *     → 两个名字**都**探测（ovCLINames），认错名字的后果是「明明装了却说没装」。
+ *   · `ov --version` 是否被支持：未确认 → 版本读取分四层兜底（见 readOpenVikingVersion）。
+ *   · 最新版本：走 PyPI JSON **运行期查**，代码里不写死版本号（今天 0.5.2，明天就旧了）。
+ */
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"runtime"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const (
+	// ovPyPackage OpenViking 的 PyPI 包名（pip install 用它）。
+	ovPyPackage = "openviking"
+	// ovVenvName 自建 venv 的目录名（家目录下）。隔离安装，不污染系统 Python
+	// （PEP 668 externally-managed 与系统 pip 权限那两坑都绕开）。
+	ovVenvName = ".openviking-venv"
+	// ovEnvBin 环境变量：显式指定 ov 命令位置（与 MAGIC_CLIENT_SHORTS_DIR 同一思路）。
+	ovEnvBin = "MAGIC_CLIENT_OPENVIKING_BIN"
+	// ovEnvPython 环境变量：显式指定用来建 venv 的 python。
+	ovEnvPython = "MAGIC_CLIENT_PYTHON"
+)
+
+// ovCLINames 命令名候选。0.5.2 的 PyPI 文档给的是 `ov`；火山引擎 0.4.15 的文档用 `openviking`。
+// 两个都认 —— 认错的后果是「明明装了却说没装」。
+var ovCLINames = []string{"ov", "openviking"}
+
+/* ── 注入点（测试打桩用；生产走下面的默认实现）── */
+
+// ovHomeDir 家目录。
+var ovHomeDir = func() (string, error) { return os.UserHomeDir() }
+
+// ovPythonProbe 找一个可用的 python（≥3.10）。返回 (命令前缀, 版本)；找不到返回 (nil, "")。
+// 前缀可能是多个词（Windows 的 `py -3`），所以是 []string 而不是字符串。
+var ovPythonProbe = func() ([]string, string) { return findPython310() }
+
+// pypiLatest 查 PyPI 上的最新版本。测试把它换成桩（不打外网）。
+var pypiLatest = func(pkg string) (string, error) { return fetchPyPILatest(pkg) }
+
+// knowledgeSpec 知识库目录里的一项（服务端固定表，不接受客户端输入）。
+type knowledgeSpec struct {
+	ID           string
+	Name         string
+	CLI          string
+	PyPIPackage  string
+	Tagline      string
+	Description  string
+	Requirements string
+	Homepage     string
+	Examples     []string
+	// UsePrompt 是「让它干活」时预填到输入框里的话（用户补参数即可发送）。
+	UsePrompt string
+}
+
+func knowledgeSpecs() []knowledgeSpec {
+	return []knowledgeSpec{
+		{
+			ID:          "openviking",
+			Name:        "OpenViking",
+			CLI:         "ov",
+			PyPIPackage: ovPyPackage,
+			Tagline:     "Agent 的上下文数据库：记忆 · 知识 RAG · 技能，统一收进 viking://",
+			Description: "一个专门给 AI Agent 用的上下文数据库：把文档、网页、笔记这些非结构化资料丢进去，" +
+				"它自动解析、切分、向量化、分层索引，Agent 需要时**按需取用**而不是整包塞进上下文窗口。" +
+				"资料用 viking:// 文件系统组织（目录式检索，检索范围能一层层收窄），" +
+				"会话结束后还能把要点沉淀成长期记忆。" +
+				"对 Agent 框架有两种接法：命令行（`ov`）或 MCP（`openviking-mcp`）。" +
+				"本机装好后还需在 ~/.openviking/ov.conf 里配 workspace 与 embedding / vlm 的 api_key 才会真的开始检索。",
+			Requirements: "Python ≥ 3.10（官方 wheel 为 cp310-abi3，Windows / Linux x64 / Linux arm64 / macOS 都有预编译版）；需要能访问 PyPI",
+			Homepage:     "https://github.com/volcengine/OpenViking",
+			Examples: []string{
+				"ov status                                    # 看服务状态",
+				"ov add-resource https://github.com/volcengine/OpenViking   # 收一份资料进去",
+				"ov find \"这个仓库的架构是怎样的\"             # 语义检索",
+				"openviking-server init                       # 初始化本地服务（会问你要 api_key）",
+			},
+			UsePrompt: "用 OpenViking 查知识库。\n问题：",
+		},
+	}
+}
+
+func findKnowledge(id string) (knowledgeSpec, bool) {
+	id = strings.TrimSpace(strings.ToLower(id))
+	for _, k := range knowledgeSpecs() {
+		if k.ID == id {
+			return k, true
+		}
+	}
+	return knowledgeSpec{}, false
+}
+
+// knowledgeInfo GET /desk/knowledge 的一项（客户端只读，不做第二次推断）。
+type knowledgeInfo struct {
+	ID           string `json:"id"`
+	Name         string `json:"name"`
+	CLI          string `json:"cli"`
+	Tagline      string `json:"tagline"`
+	Description  string `json:"description"`
+	Requirements string `json:"requirements,omitempty"`
+	Homepage     string `json:"homepage,omitempty"`
+	Installed    bool   `json:"installed"`
+	Version      string `json:"version,omitempty"`
+	Bin          string `json:"bin,omitempty"`
+	// BinSource 命令从哪来：env（环境变量指定）| venv（本项目自建 venv）| path（PATH 上）。
+	BinSource string `json:"binSource,omitempty"`
+	// LatestVersion PyPI 上的最新版本（查不到就空串 + note 说明，不报错卡住页面）。
+	LatestVersion string `json:"latestVersion,omitempty"`
+	// UpgradeAvailable 本机版本确实比最新版本旧。
+	UpgradeAvailable bool `json:"upgradeAvailable"`
+	// PythonPath / PythonVersion 探测到的、可以用来建 venv 的 python。
+	PythonPath    string   `json:"pythonPath,omitempty"`
+	PythonVersion string   `json:"pythonVersion,omitempty"`
+	Install       string   `json:"install"`
+	Upgrade       string   `json:"upgrade"`
+	Examples      []string `json:"examples"`
+	UsePrompt     string   `json:"usePrompt"`
+	// Note 讲清「为什么是现在这个状态」，客户端原样显示，不自己编。
+	Note string `json:"note,omitempty"`
+}
+
+/* ── 探测 ── */
+
+// ovDetect 探测结果。
+type ovDetect struct {
+	Bin        string // 命令绝对路径（空 = 没找到）
+	Source     string // env | venv | path
+	VenvRoot   string // 自建 venv 的根目录
+	VenvPython string // venv 里的 python
+}
+
+// ovVenvRoot 自建 venv 的位置（家目录下）。
+func ovVenvRoot() string {
+	home, err := ovHomeDir()
+	if err != nil || strings.TrimSpace(home) == "" {
+		return ""
+	}
+	return filepath.Join(home, ovVenvName)
+}
+
+// ovVenvBinDir venv 里放可执行文件的目录：Windows 是 Scripts，POSIX 是 bin。
+func ovVenvBinDir(root string) string {
+	if root == "" {
+		return ""
+	}
+	if runtime.GOOS == "windows" {
+		return filepath.Join(root, "Scripts")
+	}
+	return filepath.Join(root, "bin")
+}
+
+// ovVenvPython venv 里的 python。
+func ovVenvPython(root string) string {
+	if root == "" {
+		return ""
+	}
+	if runtime.GOOS == "windows" {
+		return filepath.Join(root, "Scripts", "python.exe")
+	}
+	return filepath.Join(root, "bin", "python")
+}
+
+// detectOpenViking 找本机的 OpenViking 命令。
+//
+// 候选顺序（每一步都有理由）：
+//  1. 环境变量 —— 用户显式指定的优先级最高（他可能装到了别处）。
+//  2. 自建 venv —— **必须排在 PATH 之前**：一键安装装进 venv 后 `ov` 并不在 PATH 上，
+//     只查 PATH 会把「刚装好」误报成「未安装」，那是本功能最容易出的错。
+//  3. PATH —— 最后才是系统里已有的。
+func detectOpenViking() ovDetect {
+	d := ovDetect{VenvRoot: ovVenvRoot()}
+
+	if p := strings.TrimSpace(os.Getenv(ovEnvBin)); p != "" {
+		if st, err := os.Stat(p); err == nil && !st.IsDir() {
+			d.Bin, d.Source = p, "env"
+			return d
+		}
+	}
+
+	if dir := ovVenvBinDir(d.VenvRoot); dir != "" {
+		for _, name := range ovCLINames {
+			p := filepath.Join(dir, name)
+			if runtime.GOOS == "windows" {
+				p += ".exe"
+			}
+			if st, err := os.Stat(p); err == nil && !st.IsDir() {
+				d.Bin, d.Source = p, "venv"
+				d.VenvPython = ovVenvPython(d.VenvRoot)
+				return d
+			}
+		}
+	}
+
+	for _, name := range ovCLINames {
+		if p, err := exec.LookPath(name); err == nil {
+			d.Bin, d.Source = p, "path"
+			return d
+		}
+	}
+	return d
+}
+
+/* ── 版本号（分层兜底，绝不编）── */
+
+// ovVersionCoreRe 匹配 x.y.z 形态的数字段（版本号的「核心」）。
+var ovVersionCoreRe = regexp.MustCompile(`\d+\.\d+\.\d+`)
+
+// ovSuffixRe 版本号后面的修饰部分（`.dev0` / `-rc1` / `+local` …）。
+var ovSuffixRe = regexp.MustCompile(`^[0-9A-Za-z.\-+]*`)
+
+// ovSplitVersion 把一行输出里的版本号拆成 (核心, 后缀)。
+//
+// ⚠️ **只看第一行**：版本输出都在第一行，后面的行常是路径或别的程序的版本
+// （实测 llm 引擎的 venv 坏掉时，输出里满是 `3.12.13` 这类路径里的数字）。
+//
+// ⚠️ 后缀必须留着：PEP 440 的预发布形态**不一定用 '-' 分隔** ——
+// 实测本机 `ov --version` 吐的是 `openviking 0.4.16.dev0`，
+// 而 PyPI 上也有 `0.6.0rc1` 这种形态。只看 '-' 会把 dev 版当成正式版。
+func ovSplitVersion(line string) (core, suffix string, ok bool) {
+	m := ovVersionCoreRe.FindString(line)
+	if m == "" {
+		return "", "", false
+	}
+	rest := line[strings.Index(line, m)+len(m):]
+	return m, ovSuffixRe.FindString(rest), true
+}
+
+// ovFirstLine 取文本第一行。
+func ovFirstLine(s string) string {
+	if i := strings.IndexByte(s, '\n'); i >= 0 {
+		return s[:i]
+	}
+	return s
+}
+
+// ovVersionToken 从一行输出里取出版本号（含后缀，如 "0.4.16.dev0"）；没有则空串。
+func ovVersionToken(line string) string {
+	core, suffix, ok := ovSplitVersion(line)
+	if !ok {
+		return ""
+	}
+	return core + suffix
+}
+
+// readOpenVikingVersion 尽力读出本机 OpenViking 的版本号；读不到就空串。
+//
+// 四层，逐层更"不依赖解释器"：
+//
+//	L1  <bin> --version        CLI 自述，最权威；但 `ov --version` 是否被支持**未确认**
+//	                          （实测本机 0.4.16 是支持的，但不能拿别人的版本赌）→ 不能只靠这层。
+//	L2  dist-info 目录名        纯文件系统，不依赖解释器 —— 比 L3 可靠：解释器可能被搬走
+//	                          或损坏（本仓 llm 引擎的 venv 就踩过这个坑）。
+//	L3  importlib.metadata     对任意安装器都准，但要求解释器能跑。
+//	L4  pip show               兜底，要求 pip 在。
+func readOpenVikingVersion(bin, venvRoot string) string {
+	if v := versionFromCLI(bin); v != "" {
+		return v
+	}
+	if v := versionFromDistInfo(bin, venvRoot); v != "" {
+		return v
+	}
+	return versionFromInterpreter(venvRoot)
+}
+
+// versionFromCLI 跑一次 `--version`，取输出里的版本号。
+func versionFromCLI(bin string) string {
+	if bin == "" {
+		return ""
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	out, errOut, err := ovCapture(ctx, []string{bin, "--version"})
+	if err != nil && out == "" && errOut == "" {
+		return ""
+	}
+	if v := ovVersionToken(ovFirstLine(out)); v != "" {
+		return v
+	}
+	// 少数 CLI 把版本打到 stderr（stdout 只剩日志）→ 兜一次。
+	return ovVersionToken(ovFirstLine(errOut))
+}
+
+// versionFromDistInfo 从安装元数据目录名读版本（openviking-0.5.2.dist-info）。
+func versionFromDistInfo(bin, venvRoot string) string {
+	for _, dir := range ovSitePackagesDirs(bin, venvRoot) {
+		ents, err := os.ReadDir(dir)
+		if err != nil {
+			continue
+		}
+		for _, e := range ents {
+			name := e.Name()
+			if !strings.HasPrefix(name, ovPyPackage+"-") || !strings.HasSuffix(name, ".dist-info") {
+				continue
+			}
+			v := strings.TrimSuffix(strings.TrimPrefix(name, ovPyPackage+"-"), ".dist-info")
+			if ovVersionCoreRe.MatchString(v) {
+				return v
+			}
+		}
+	}
+	return ""
+}
+
+// ovSitePackagesDirs 列出可能装着 openviking 的 site-packages 目录。
+func ovSitePackagesDirs(bin, venvRoot string) []string {
+	var dirs []string
+	add := func(p string) {
+		if p == "" {
+			return
+		}
+		if st, err := os.Stat(p); err == nil && st.IsDir() {
+			dirs = append(dirs, p)
+		}
+	}
+	if venvRoot != "" {
+		// Windows 的 venv 布局：<root>\Lib\site-packages
+		add(filepath.Join(venvRoot, "Lib", "site-packages"))
+		// POSIX：<root>\lib\python3.x\site-packages
+		if gl, err := filepath.Glob(filepath.Join(venvRoot, "lib", "python*", "site-packages")); err == nil {
+			for _, p := range gl {
+				add(p)
+			}
+		}
+	}
+	if bin != "" {
+		dir := filepath.Dir(bin)
+		for i := 0; i < 4; i++ {
+			add(filepath.Join(dir, "site-packages"))
+			add(filepath.Join(dir, "Lib", "site-packages"))
+			parent := filepath.Dir(dir)
+			if parent == dir {
+				break
+			}
+			dir = parent
+		}
+	}
+	return dirs
+}
+
+// versionFromInterpreter 问解释器要版本（importlib.metadata 与 pip show 两条都试）。
+func versionFromInterpreter(venvRoot string) string {
+	var pys [][]string
+	if p := ovVenvPython(venvRoot); p != "" {
+		pys = append(pys, []string{p})
+	}
+	if pref, _ := ovPythonProbe(); len(pref) > 0 {
+		pys = append(pys, pref)
+	}
+	for _, py := range pys {
+		ctx, cancel := context.WithTimeout(context.Background(), 8*time.Second)
+		meta := append(append([]string{}, py...),
+			"-c", "import importlib.metadata as m;print(m.version('"+ovPyPackage+"'))")
+		out, _, _ := ovCapture(ctx, meta)
+		cancel()
+		if v := ovVersionToken(strings.TrimSpace(out)); v != "" {
+			return v
+		}
+
+		ctx2, cancel2 := context.WithTimeout(context.Background(), 8*time.Second)
+		show := append(append([]string{}, py...), "-m", "pip", "show", ovPyPackage)
+		out2, _, _ := ovCapture(ctx2, show)
+		cancel2()
+		for _, line := range strings.Split(out2, "\n") {
+			if !strings.HasPrefix(strings.ToLower(strings.TrimSpace(line)), "version:") {
+				continue
+			}
+			if v := ovVersionToken(line); v != "" {
+				return v
+			}
+		}
+	}
+	return ""
+}
+
+// ovVersionParts 把版本号拆成三段数字；不是 x.y.z 就返回 false。
+func ovVersionParts(v string) ([3]int, bool) {
+	m := ovVersionCoreRe.FindString(v)
+	if m == "" {
+		return [3]int{}, false
+	}
+	nums := regexp.MustCompile(`\d+`).FindAllString(m, 3)
+	var out [3]int
+	if len(nums) == 0 {
+		return out, false
+	}
+	for i := 0; i < len(nums) && i < 3; i++ {
+		n, err := strconv.Atoi(nums[i])
+		if err != nil {
+			return out, false
+		}
+		out[i] = n
+	}
+	return out, true
+}
+
+// ovVersionLess 报告 cur 是否比 latest 旧（只比数字段，后缀忽略）。
+func ovVersionLess(cur, latest string) bool {
+	c, ok1 := ovVersionParts(cur)
+	l, ok2 := ovVersionParts(latest)
+	if !ok1 || !ok2 {
+		return false
+	}
+	for i := 0; i < 3; i++ {
+		if c[i] != l[i] {
+			return c[i] < l[i]
+		}
+	}
+	return false
+}
+
+// ovIsPreRelease 报告版本号是不是预发布。
+//
+// ⚠️ PEP 440 的预发布形态**不一定用 '-' 分隔**：实测本机 `ov --version` 吐的是
+// `openviking 0.4.16.dev0`（用 '.'），而 PyPI 上还有 `0.6.0rc1` 这种**连字符都没有**的。
+// 所以判据是「后缀里出现 dev / rc / alpha / beta / pre 就算预发布」，
+// 而不是「有没有 '-'」—— 否则 dev 版会被当成正式版，界面就会说「已是最新」。
+func ovIsPreRelease(v string) bool {
+	_, suffix, ok := ovSplitVersion(v)
+	if !ok {
+		return false
+	}
+	lower := strings.ToLower(strings.TrimLeft(suffix, "-._"))
+	if lower == "" {
+		return false
+	}
+	for _, p := range []string{"dev", "rc", "alpha", "beta", "pre"} {
+		if strings.HasPrefix(lower, p) {
+			return true
+		}
+	}
+	/* PEP 440 里 alpha / beta 可以只写一个字母（"1.0.0a2" = "1.0.0alpha2"）。
+	   要看字母后面是不是数字或结尾 —— 否则 "abc" 之类会被误判。 */
+	for _, p := range []string{"a", "b"} {
+		if !strings.HasPrefix(lower, p) {
+			continue
+		}
+		rest := lower[len(p):]
+		if rest == "" || (rest[0] >= '0' && rest[0] <= '9') {
+			return true
+		}
+	}
+	return false
+}
+
+/* ── python ── */
+
+// findPython310 找一个能用的 python（≥3.10）。返回 (命令前缀, 版本)。
+//
+// 顺序：环境变量 → python → py -3 → python3。
+// ⚠️ Windows 上 `python3` 是 Microsoft Store 的**占位桩**：跑它会弹商店、且没有输出。
+//
+//	所以它排在最后，而且必须靠「真能跑出版本号」来判活 —— 这也顺带挡掉了另一个坑：
+//	venv 的 `python` 指向的基解释器一旦被换掉/搬走，L1/L3 都会失灵（见 versionFromDistInfo）。
+func findPython310() ([]string, string) {
+	var cands [][]string
+	if p := strings.TrimSpace(os.Getenv(ovEnvPython)); p != "" {
+		cands = append(cands, []string{p})
+	}
+	cands = append(cands, []string{"python"}, []string{"py", "-3"}, []string{"python3"})
+
+	for _, c := range cands {
+		if len(c) == 1 && ovIsStoreStub(c[0]) {
+			continue
+		}
+		ver, ok := probePython(c)
+		if !ok {
+			continue
+		}
+		if !ovPythonVersionOK(ver) {
+			continue
+		}
+		return c, ver
+	}
+	return nil, ""
+}
+
+// ovIsStoreStub 报告这个命令是不是 Windows 上的 Microsoft Store 占位桩
+// （路径在 WindowsApps 下 —— 那是 Store 的转发器，不是真的解释器）。
+func ovIsStoreStub(name string) bool {
+	p, err := exec.LookPath(name)
+	if err != nil {
+		return false
+	}
+	return strings.Contains(strings.ToLower(filepath.ToSlash(p)), "/windowsapps/")
+}
+
+// probePython 跑一次 `python -c "print(sys.version)"`，拿到三段版本号。
+func probePython(argv []string) (string, bool) {
+	ctx, cancel := context.WithTimeout(context.Background(), 8*time.Second)
+	defer cancel()
+	full := append(append([]string{}, argv...),
+		"-c", "import sys;print('%d.%d.%d'%sys.version_info[:3])")
+	out, _, err := ovCapture(ctx, full)
+	if err != nil {
+		return "", false
+	}
+	v := strings.TrimSpace(strings.SplitN(out, "\n", 2)[0])
+	if !ovVersionCoreRe.MatchString(v) {
+		return "", false
+	}
+	return v, true
+}
+
+// ovPythonVersionOK 判断版本是否 ≥ 3.10（OpenViking 的硬要求）。
+func ovPythonVersionOK(v string) bool {
+	parts := strings.Split(v, ".")
+	if len(parts) < 2 {
+		return false
+	}
+	maj, err1 := strconv.Atoi(parts[0])
+	min, err2 := strconv.Atoi(parts[1])
+	if err1 != nil || err2 != nil {
+		return false
+	}
+	return maj > 3 || (maj == 3 && min >= 10)
+}
+
+/* ── PyPI 最新版本 ── */
+
+// fetchPyPILatest 查 PyPI 上某个包的最新版本。
+func fetchPyPILatest(pkg string) (string, error) {
+	client := &http.Client{Timeout: 6 * time.Second}
+	u := "https://pypi.org/pypi/" + url.PathEscape(pkg) + "/json"
+	resp, err := client.Get(u)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("PyPI 返回 %d", resp.StatusCode)
+	}
+	var j struct {
+		Info struct {
+			Version string `json:"version"`
+		} `json:"info"`
+	}
+	if err := json.NewDecoder(io.LimitReader(resp.Body, 1<<20)).Decode(&j); err != nil {
+		return "", err
+	}
+	v := strings.TrimSpace(j.Info.Version)
+	if v == "" {
+		return "", fmt.Errorf("PyPI 没给版本号")
+	}
+	return v, nil
+}
+
+/* ── 服务端组装 ── */
+
+// ovLatestVersion 取 PyPI 最新版本。
+//
+// 缓存策略：成功缓存 6h，失败缓存 15min（失败不该每次开页面都重试一次外网）。
+// 返回 (最新版本, 是否真的拿到了)。拿不到时**不报错** —— 界面照常显示本机状态，
+// 只是「最新版本」那一栏空着 + note 说明查不到。
+func (s *Service) ovLatestVersion(pkg string) (string, bool) {
+	s.ovMu.Lock()
+	ttl := 6 * time.Hour
+	if !s.ovLatestOK {
+		ttl = 15 * time.Minute
+	}
+	fresh := !s.ovLatestAt.IsZero() && time.Since(s.ovLatestAt) < ttl
+	v, ok := s.ovLatest, s.ovLatestOK
+	s.ovMu.Unlock()
+	if fresh {
+		return v, ok
+	}
+
+	nv, err := pypiLatest(pkg)
+	s.ovMu.Lock()
+	s.ovLatestAt = time.Now()
+	if err == nil && nv != "" {
+		s.ovLatest, s.ovLatestOK = nv, true
+	} else {
+		s.ovLatest, s.ovLatestOK = "", false
+	}
+	v, ok = s.ovLatest, s.ovLatestOK
+	s.ovMu.Unlock()
+	return v, ok
+}
+
+// ovSteps 构造安装 / 升级步骤（argv 数组，不过 shell）。
+//
+// 三步：
+//
+//	<py> -m venv <venv>                    建隔离环境（已有就复用，不删）
+//	<venvPy> -m pip install [--upgrade] openviking
+//	<venvPy> -m pip show openviking        只为把版本打进日志（失败不致命）
+//
+// 为什么不用官方那条 `pip install openviking --upgrade --force-reinstall`：
+// 它会把依赖一起重装，又慢又容易在旧依赖上翻车；升级只需要 `--upgrade`。
+func ovSteps() (install, upgrade []pluginStep) {
+	py, _ := ovPythonProbe()
+	if len(py) == 0 {
+		return nil, nil
+	}
+	venvRoot := ovVenvRoot()
+	venvPy := ovVenvPython(venvRoot)
+
+	mk := func(extra ...string) []pluginStep {
+		mkVenv := append(append([]string{}, py...), "-m", "venv", venvRoot)
+		installArgv := append([]string{venvPy}, "-m", "pip",
+			"install", "--disable-pip-version-check")
+		installArgv = append(installArgv, extra...)
+		installArgv = append(installArgv, ovPyPackage)
+		showArgv := append([]string{venvPy}, "-m", "pip", "show", ovPyPackage)
+		return []pluginStep{
+			{Args: mkVenv},
+			{Args: installArgv},
+			{Args: showArgv, Optional: true, SkipNote: "pip show 没输出 —— 版本号改从安装元数据取"},
+		}
+	}
+	return mk(), mk("--upgrade")
+}
+
+// knowledgeInfoOf 组装一项知识库的完整状态（探测 → 填 note）。
+func (s *Service) knowledgeInfoOf(spec knowledgeSpec) knowledgeInfo {
+	info := knowledgeInfo{
+		ID: spec.ID, Name: spec.Name, CLI: spec.CLI,
+		Tagline: spec.Tagline, Description: spec.Description,
+		Requirements: spec.Requirements, Homepage: spec.Homepage,
+		Examples: spec.Examples, UsePrompt: spec.UsePrompt,
+	}
+
+	d := detectOpenViking()
+	if d.Bin != "" {
+		info.Installed = true
+		info.Bin = d.Bin
+		info.BinSource = d.Source
+		info.Version = readOpenVikingVersion(d.Bin, d.VenvRoot)
+	}
+
+	if pref, ver := ovPythonProbe(); len(pref) > 0 {
+		info.PythonPath = strings.Join(pref, " ")
+		info.PythonVersion = ver
+	}
+
+	latest, latestKnown := s.ovLatestVersion(spec.PyPIPackage)
+	info.LatestVersion = latest
+	if latestKnown && !ovIsPreRelease(latest) && info.Version != "" {
+		info.UpgradeAvailable = ovVersionLess(info.Version, latest)
+	}
+
+	isteps, usteps := ovSteps()
+	info.Install = pluginCommands(isteps)
+	info.Upgrade = pluginCommands(usteps)
+	info.Note = ovNote(info, d, latest, latestKnown)
+	return info
+}
+
+// ovNote 说明「为什么是现在这个状态」—— 客户端原样显示，不自己编。
+func ovNote(info knowledgeInfo, d ovDetect, latest string, latestKnown bool) string {
+	var b strings.Builder
+	switch {
+	case info.Installed && info.Version != "":
+		fmt.Fprintf(&b, "已安装 v%s（%s）", info.Version, ovSourceLabel(d.Source))
+	case info.Installed:
+		fmt.Fprintf(&b, "已安装（%s），但读不到版本号（该 CLI 可能没有 --version）", ovSourceLabel(d.Source))
+	default:
+		b.WriteString("未安装：PATH 上没有 ov，也没有 " + ovVenvRoot())
+		if info.PythonPath == "" {
+			b.WriteString("；还没找到 Python ≥ 3.10，装不了")
+		}
+	}
+	if info.UpgradeAvailable {
+		fmt.Fprintf(&b, "；有新版 v%s 可升级", latest)
+	} else if latestKnown && info.Version != "" && !ovIsPreRelease(latest) {
+		fmt.Fprintf(&b, "；已是最新（v%s）", latest)
+	} else if !latestKnown {
+		b.WriteString("；查不到最新版本（离线或 PyPI 不可达）")
+	}
+	if info.Installed && info.BinSource == "venv" {
+		b.WriteString("。装完还要配 ~/.openviking/ov.conf（workspace + embedding / vlm 的 api_key）才会真的开始检索")
+	}
+	return b.String()
+}
+
+// ovSourceLabel 把命令来源说成人话。
+func ovSourceLabel(source string) string {
+	switch source {
+	case "env":
+		return "命令由环境变量指定"
+	case "venv":
+		return "命令在本项目的隔离环境里"
+	case "path":
+		return "命令在 PATH 上"
+	default:
+		return ""
+	}
+}
+
+/* ── 接口 ── */
+
+// handleKnowledge GET /desk/knowledge：知识库目录 + 本机安装状态。
+func (s *Service) handleKnowledge(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		writeErr(w, http.StatusMethodNotAllowed, "GET only")
+		return
+	}
+	specs := knowledgeSpecs()
+	items := make([]knowledgeInfo, 0, len(specs))
+	for _, k := range specs {
+		items = append(items, s.knowledgeInfoOf(k))
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"knowledge": items})
+}
+
+/* handleKnowledgeAction POST /desk/knowledge/{id}/{install|upgrade}
+ *
+ * 回 SSE：`event: open`（这次要跑哪几条命令）→ 每条命令一行 `event: step`，
+ * 输出逐行 `event: line` → `event: end`（ok / code / 刷新后的状态）。
+ * 用 SSE 而不是等一个 JSON：pip 装一个包几秒到几十秒，手机上必须看得见在动。 */
+func (s *Service) handleKnowledgeAction(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	rest := strings.TrimPrefix(r.URL.Path, "/desk/knowledge/")
+	parts := strings.Split(strings.Trim(rest, "/"), "/")
+	if len(parts) != 2 {
+		writeErr(w, http.StatusNotFound, "用法：POST /desk/knowledge/{id}/{install|upgrade}")
+		return
+	}
+	spec, ok := findKnowledge(parts[0])
+	if !ok {
+		writeErr(w, http.StatusNotFound, "没有这个知识库："+parts[0])
+		return
+	}
+	isteps, usteps := ovSteps()
+	var steps []pluginStep
+	switch parts[1] {
+	case "install":
+		steps = isteps
+	case "upgrade":
+		steps = usteps
+	default:
+		writeErr(w, http.StatusNotFound, "动作只有 install / upgrade")
+		return
+	}
+	if len(steps) == 0 {
+		writeErr(w, http.StatusBadRequest, "没找到可用的 Python（需要 ≥ 3.10），装不了")
+		return
+	}
+
+	// 并发保护：两个客户端同时点安装会抢同一个 venv。
+	s.ovMu.Lock()
+	if s.ovBusy {
+		s.ovMu.Unlock()
+		writeErr(w, http.StatusConflict, "已有安装 / 升级在进行，请等它结束")
+		return
+	}
+	s.ovBusy = true
+	s.ovMu.Unlock()
+	defer func() {
+		s.ovMu.Lock()
+		s.ovBusy = false
+		s.ovMu.Unlock()
+	}()
+
+	w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("X-Accel-Buffering", "no")
+	flusher, _ := w.(http.Flusher)
+	send := func(event string, payload any) {
+		b, _ := json.Marshal(payload)
+		if event != "" {
+			fmt.Fprintf(w, "event: %s\n", event)
+		}
+		fmt.Fprintf(w, "data: %s\n\n", b)
+		if flusher != nil {
+			flusher.Flush()
+		}
+	}
+
+	cmds := make([]string, 0, len(steps))
+	for _, st := range steps {
+		cmds = append(cmds, st.Command())
+	}
+	send("open", map[string]any{"id": spec.ID, "action": parts[1], "commands": cmds})
+
+	/* 与 /desk/ask 同一口径：客户端断连不是「取消安装」。
+	   装到一半被手机锁屏杀掉会更糟（半个包装在盘上），所以跑完再说。 */
+	ctx := context.WithoutCancel(r.Context())
+	failed := ""
+	failCode := 0
+	for i, st := range steps {
+		send("step", map[string]any{"index": i, "command": st.Command()})
+		code, err := runPluginStep(ctx, st, func(line string) {
+			send("line", map[string]any{"index": i, "line": line})
+		})
+		if err != nil || code != 0 {
+			if st.Optional {
+				send("line", map[string]any{"index": i, "line": "↷ " + st.SkipNote})
+				continue
+			}
+			if err != nil {
+				failed = err.Error()
+			} else {
+				failed = fmt.Sprintf("%s 退出码 %d", st.Command(), code)
+			}
+			failCode = code
+			break
+		}
+	}
+
+	info := s.knowledgeInfoOf(spec) // 跑完重新探一次：成功与否都让界面拿到最新状态
+	if failed != "" {
+		send("end", map[string]any{"ok": false, "code": failCode, "error": failed, "knowledge": info})
+		return
+	}
+	send("end", map[string]any{"ok": true, "code": 0, "knowledge": info})
+}
+
+/* ── 小工具 ── */
+
+// ovCapture 跑一条命令，分别拿到 stdout 与 stderr。
+func ovCapture(ctx context.Context, argv []string) (string, string, error) {
+	if len(argv) == 0 {
+		return "", "", fmt.Errorf("空命令")
+	}
+	cmd := exec.CommandContext(ctx, argv[0], argv[1:]...)
+	var ob, eb bytes.Buffer
+	cmd.Stdout = &ob
+	cmd.Stderr = &eb
+	err := cmd.Run()
+	return ob.String(), eb.String(), err
+}