@joekytc/dsh-swarm 0.1.2 → 0.3.0

package/skills/llm-wiki-skill/packages/graph-engine/test/viewport.test.ts

@@ -0,0 +1,213 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  buildRenderableGraph,
+  centerRendererViewportOnPoint,
+  createViewportFrameCommitter,
+  fitRendererViewportToPoints,
+  normalizeWheelDelta,
+  panRendererViewport,
+  rendererViewportToMinimapRect,
+  screenPointToWorldPoint,
+  visibleWorldRectForViewport,
+  visibleWorldRectToMinimapRect,
+  rendererViewportToTransform,
+  viewportAfterResize,
+  viewportAfterWheelZoom,
+  worldPointToScreenPoint
+} from "../src/render";
+import type { GraphData, PinMap } from "../src/types";
+
+function sampleGraph(): GraphData {
+  return {
+    meta: {
+      build_date: "2026-06-13T00:00:00.000Z",
+      wiki_title: "Viewport Fixture",
+      total_nodes: 2,
+      total_edges: 1
+    },
+    nodes: [
+      { id: "a", label: "A", type: "topic", community: "c1", source_path: "wiki/a.md", x: 20, y: 30 },
+      { id: "b", label: "B", type: "entity", community: "c1", source_path: "wiki/b.md", x: 60, y: 55 }
+    ],
+    edges: [{ id: "ab", from: "a", to: "b", type: "EXTRACTED", weight: 1 }]
+  };
+}
+
+describe("renderer viewport state", () => {
+  it("serializes pan and zoom as one content-layer transform", () => {
+    assert.equal(
+      rendererViewportToTransform({ x: 32.1254, y: -18.8754, scale: 1.4567 }),
+      "translate(32.125px, -18.875px) scale(1.457)"
+    );
+  });
+
+  it("clamps focus-fit zoom so a tiny community does not blow up to fullscreen", () => {
+    const size = { width: 1440, height: 900 };
+    // 极小包围盒：聚焦一个只有几个聚集节点的小社区
+    const tightCluster = [
+      { x: 500, y: 400 },
+      { x: 520, y: 415 },
+      { x: 510, y: 430 }
+    ];
+    // 默认 fit 会把这么小的簇放大到上限（远超可读尺寸）——这正是"切社区节点爆大"的来源
+    const defaultFit = fitRendererViewportToPoints(tightCluster, size);
+    assert.ok(defaultFit.scale > 1.5, `sanity: default fit over-zooms a tiny cluster (got ${defaultFit.scale})`);
+    // focusCommunity 传保守 maxScale 后，缩放被钳住，节点保持可读、社区居中留白
+    const clamped = fitRendererViewportToPoints(tightCluster, size, { maxScale: 1.5 });
+    assert.ok(clamped.scale <= 1.5, `focus fit must clamp zoom to <= 1.5 (got ${clamped.scale})`);
+  });
+
+  it("keeps pin coordinates separate from viewport transforms", () => {
+    const pins: PinMap = {
+      "wiki/a.md": { x: 420, y: 210 }
+    };
+    const beforePins = structuredClone(pins);
+    const beforeGraph = buildRenderableGraph(sampleGraph(), { pins });
+
+    rendererViewportToTransform({ x: 120, y: -64, scale: 2.25 });
+    const afterGraph = buildRenderableGraph(sampleGraph(), { pins });
+
+    assert.deepEqual(pins, beforePins);
+    assert.deepEqual(
+      afterGraph.nodes.map((node) => [node.id, node.point]),
+      beforeGraph.nodes.map((node) => [node.id, node.point])
+    );
+    assert.deepEqual(afterGraph.nodes.find((node) => node.id === "a")?.point, { x: 420, y: 210 });
+  });
+
+  it("normalizes pixel, line, and page wheel deltas separately", () => {
+    assert.equal(normalizeWheelDelta({ deltaY: 12, deltaMode: 0 }), 12);
+    assert.equal(normalizeWheelDelta({ deltaY: 2, deltaMode: 1 }), 36);
+    assert.equal(normalizeWheelDelta({ deltaY: 1, deltaMode: 2 }), 720);
+  });
+
+  it("zooms around the pointer and pans without changing scale", () => {
+    const viewport = { x: 0, y: 0, scale: 1 };
+    const zoomed = viewportAfterWheelZoom(
+      viewport,
+      { deltaY: -120, deltaMode: 0 },
+      { x: 250, y: 150 },
+      { width: 1000, height: 680 }
+    );
+    const panned = panRendererViewport(zoomed, { x: 40, y: -25 }, { width: 1000, height: 680 });
+
+    assert.ok(zoomed.scale > 1);
+    assert.ok(zoomed.x < 0, `zoom should move x around pointer, got ${zoomed.x}`);
+    assert.ok(zoomed.y < 0, `zoom should move y around pointer, got ${zoomed.y}`);
+    assert.equal(panned.scale, zoomed.scale);
+    assert.equal(panned.x, zoomed.x + 40);
+    assert.equal(panned.y, zoomed.y - 25);
+  });
+
+  it("keeps the world point under the pointer stable during wheel zoom", () => {
+    const viewport = { x: -180, y: 64, scale: 1.25 };
+    const size = { width: 1170, height: 856 };
+    const pointer = { x: 420, y: 315 };
+    const anchoredWorldPoint = screenPointToWorldPoint(pointer, viewport, size);
+    const zoomed = viewportAfterWheelZoom(viewport, { deltaY: -100, deltaMode: 0 }, pointer, size);
+
+    assertPointNear(worldPointToScreenPoint(anchoredWorldPoint, zoomed, size), pointer);
+  });
+
+  it("fits graph points into the viewport", () => {
+    const fitted = fitRendererViewportToPoints(
+      [{ x: 120, y: 80 }, { x: 880, y: 600 }],
+      { width: 1000, height: 680 }
+    );
+
+    assert.ok(fitted.scale >= 0.5);
+    assert.ok(fitted.scale <= 4);
+    assert.notDeepEqual(fitted, { x: 0, y: 0, scale: 1 });
+  });
+
+  it("centers a model point while preserving the current zoom scale", () => {
+    const centered = centerRendererViewportOnPoint(
+      { x: 500, y: 340 },
+      { x: -20, y: -30, scale: 2 },
+      { width: 1000, height: 680 }
+    );
+
+    assert.equal(centered.scale, 2);
+    assert.deepEqual(centered, { x: -500, y: -340, scale: 2 });
+  });
+
+  it("keeps a selected model point visually anchored when the viewport host resizes", () => {
+    const point = { x: 760, y: 340 };
+    const beforeSize = { width: 1170, height: 856 };
+    const afterSize = { width: 750, height: 856 };
+    const before = centerRendererViewportOnPoint(point, { x: 0, y: 0, scale: 1.5 }, beforeSize);
+    const resized = viewportAfterResize(before, beforeSize, afterSize, { anchorPoint: point });
+    const screenRatio = (
+      resized.x + resized.scale * (point.x / 1000 * afterSize.width)
+    ) / afterSize.width;
+
+    assert.equal(resized.scale, before.scale);
+    assert.ok(screenRatio >= 0.18, `anchored point should not hug the left edge, got ${screenRatio}`);
+    assert.ok(screenRatio <= 0.78, `anchored point should stay clear of the drawer edge, got ${screenRatio}`);
+  });
+
+  it("maps the current viewport to a minimap rectangle", () => {
+    const viewport = { x: -250, y: -170, scale: 2 };
+    const size = { width: 1000, height: 680 };
+    const rect = rendererViewportToMinimapRect(
+      viewport,
+      size
+    );
+    const geometryRect = visibleWorldRectToMinimapRect(visibleWorldRectForViewport(viewport, size));
+
+    assert.ok(rect.x > 0);
+    assert.ok(rect.y > 0);
+    assert.ok(rect.width > 2);
+    assert.ok(rect.height > 2);
+    assertPointNear(rect, geometryRect);
+  });
+
+  it("maps viewport and minimap rectangles through expanded world bounds", () => {
+    const viewport = centerRendererViewportOnPoint(
+      { x: 1240, y: 816 },
+      { x: 0, y: 0, scale: 2 },
+      { width: 1000, height: 680 },
+      { worldBounds: { minX: 0, minY: 0, maxX: 1320, maxY: 896, width: 1320, height: 896 } }
+    );
+    const rect = rendererViewportToMinimapRect(
+      viewport,
+      { width: 1000, height: 680 },
+      { worldBounds: { minX: 0, minY: 0, maxX: 1320, maxY: 896, width: 1320, height: 896 } }
+    );
+
+    assert.ok(rect.x > 90, `expanded-world minimap rect should move near the outlier, got ${rect.x}`);
+    assert.ok(rect.y > 30, `expanded-world minimap rect should move near the outlier, got ${rect.y}`);
+    assert.ok(rect.width > 2);
+    assert.ok(rect.height > 2);
+  });
+
+  it("coalesces viewport writes to one requestAnimationFrame callback", () => {
+    const callbacks: Array<() => void> = [];
+    const writes: Array<{ x: number; y: number; scale: number }> = [];
+    const committer = createViewportFrameCommitter((viewport) => writes.push(viewport), {
+      requestAnimationFrame(callback) {
+        callbacks.push(callback);
+        return callbacks.length;
+      }
+    });
+
+    committer.schedule({ x: 10, y: 0, scale: 1 });
+    committer.schedule({ x: 20, y: 0, scale: 1 });
+    committer.schedule({ x: 30, y: 0, scale: 1 });
+
+    assert.equal(callbacks.length, 1);
+    assert.deepEqual(writes, []);
+    callbacks[0]();
+    assert.deepEqual(writes, [{ x: 30, y: 0, scale: 1 }]);
+  });
+});
+
+function assertNear(actual: number, expected: number, message?: string): void {
+  assert.ok(Math.abs(actual - expected) < 0.01, `${message ?? "number"}: expected ${expected}, got ${actual}`);
+}
+
+function assertPointNear(actual: { x: number; y: number }, expected: { x: number; y: number }): void {
+  assertNear(actual.x, expected.x, "x");
+  assertNear(actual.y, expected.y, "y");
+}

package/skills/llm-wiki-skill/packages/graph-engine/test/vis-network-trial-adapter.test.ts

@@ -0,0 +1,82 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { buildCommunityAggregationMarkers } from "../src";
+import type { GraphData, PinMap } from "../src/types";
+import { buildVisNetworkTrialModel } from "./vis-network-trial-adapter";
+
+describe("vis-network trial adapter", () => {
+  it("preserves graph semantics for the isolated Canvas comparison route", () => {
+    const data = graphFixture();
+    const pins: PinMap = {
+      "wiki/a.md": { x: 10, y: 20, coordinateSpace: "world" }
+    };
+    const aggregationMarkers = buildCommunityAggregationMarkers(data, {
+      pins,
+      searchResultIds: ["b"],
+      selectedNodeIds: ["a"],
+      minCommunitySize: 2
+    });
+
+    const model = buildVisNetworkTrialModel(data, {
+      pins,
+      searchResultIds: ["b"],
+      selection: { kind: "node", id: "a" },
+      aggregationMarkers
+    });
+
+    assert.equal(model.nodes.length, 3);
+    assert.equal(model.edges.length, 2);
+    assert.deepEqual(model.nodes.map((node) => node.id), ["a", "b", "c"]);
+    assert.equal(model.nodes.find((node) => node.id === "a")?.selected, true);
+    assert.equal(model.nodes.find((node) => node.id === "a")?.pinned, true);
+    assert.equal(model.nodes.find((node) => node.id === "b")?.searchHit, true);
+    assert.equal(model.nodes.find((node) => node.id === "b")?.communityId, "alpha");
+    assert.deepEqual(model.communities.map((community) => community.id), ["alpha", "beta"]);
+    assert.deepEqual(model.communities.find((community) => community.id === "alpha")?.searchResultIds, ["b"]);
+    assert.equal(model.aggregations.length, 1);
+    assert.deepEqual(model.aggregations[0]?.selectedNodeIds, ["a"]);
+    assert.deepEqual(model.aggregations[0]?.searchResultIds, ["b"]);
+    assert.deepEqual(model.aggregations[0]?.pinnedNodeIds, ["a"]);
+
+    assert.equal(model.behavior.route, "candidate-global");
+    assert.deepEqual(model.behavior.searchHighlight.map((item) => item.nodeId), ["b"]);
+    assert.deepEqual(model.behavior.pinInsideAggregation[0]?.pinnedNodeIds, ["a"]);
+    assert.deepEqual(model.behavior.selectedObjectInsideAggregation[0]?.selectedNodeIds, ["a"]);
+    assert.ok(model.behavior.containerSelect.some((item) => item.containerId === "alpha"));
+    assert.ok(model.behavior.enterCommunity.some((item) => item.communityId === "alpha"));
+  });
+});
+
+function graphFixture(): GraphData {
+  return {
+    meta: {
+      build_date: "2026-06-19T00:00:00.000Z",
+      wiki_title: "vis-network trial adapter",
+      total_nodes: 3,
+      total_edges: 2
+    },
+    nodes: [
+      { id: "a", label: "Alpha", type: "topic", community: "alpha", source_path: "wiki/a.md", x: 0, y: 0 },
+      { id: "b", label: "Beta needle", type: "entity", community: "alpha", source_path: "wiki/b.md", x: 10, y: 0 },
+      { id: "c", label: "Gamma", type: "source", community: "beta", source_path: "wiki/c.md", x: 20, y: 0 }
+    ],
+    edges: [
+      { id: "a-b", from: "a", to: "b", type: "EXTRACTED", weight: 1 },
+      { id: "b-c", from: "b", to: "c", type: "INFERRED", weight: 0.7 }
+    ],
+    learning: {
+      version: 1,
+      entry: { recommended_start_node_id: "a", recommended_start_reason: "fixture", default_mode: "global" },
+      views: {
+        path: { enabled: false, start_node_id: null, node_ids: [], degraded: false },
+        community: { enabled: false, community_id: null, label: null, node_ids: [], is_weak: false, degraded: false },
+        global: { enabled: true, node_ids: ["a", "b", "c"], degraded: false }
+      },
+      communities: [
+        { id: "alpha", label: "Alpha", node_count: 2 },
+        { id: "beta", label: "Beta", node_count: 1 }
+      ]
+    }
+  };
+}

package/skills/llm-wiki-skill/packages/graph-engine/test/vis-network-trial-adapter.ts

@@ -0,0 +1,186 @@
+import {
+  buildGraphRendererAdapterData,
+  buildGraphRendererBehaviorContract,
+  type GraphRendererBehaviorContract
+} from "../src/render";
+import type {
+  GraphAggregationMarker,
+  GraphData,
+  GraphFocusInput,
+  GraphPinHint,
+  GraphTypeFilters,
+  NodeId,
+  PinMap,
+  SelectionInput
+} from "../src/types";
+
+export interface VisNetworkTrialOptions {
+  pins?: PinMap;
+  selection?: SelectionInput | null;
+  searchResultIds?: NodeId[];
+  aggregationMarkers?: GraphAggregationMarker[];
+  focus?: GraphFocusInput;
+  typeFilters?: GraphTypeFilters;
+}
+
+export interface VisNetworkTrialModel {
+  nodes: VisNetworkTrialNode[];
+  edges: VisNetworkTrialEdge[];
+  communities: VisNetworkTrialCommunity[];
+  aggregations: VisNetworkTrialAggregation[];
+  behavior: GraphRendererBehaviorContract;
+}
+
+export interface VisNetworkTrialNode {
+  id: string;
+  label: string;
+  x: number;
+  y: number;
+  size: number;
+  color: string;
+  communityId: string | null;
+  sourcePath: string;
+  selected: boolean;
+  searchHit: boolean;
+  pinned: boolean;
+  pinHint: GraphPinHint;
+  aggregationIds: string[];
+}
+
+export interface VisNetworkTrialEdge {
+  id: string;
+  from: string;
+  to: string;
+  color: string;
+  width: number;
+  relationType: string | null;
+}
+
+export interface VisNetworkTrialCommunity {
+  id: string;
+  label: string;
+  nodeIds: string[];
+  selected: boolean;
+  searchResultIds: string[];
+  pinnedNodeIds: string[];
+}
+
+export interface VisNetworkTrialAggregation {
+  id: string;
+  communityId: string | null;
+  nodeIds: string[];
+  selectedNodeIds: string[];
+  searchResultIds: string[];
+  pinnedNodeIds: string[];
+  totalCount: number;
+}
+
+const COMMUNITY_COLORS = [
+  "#2563eb",
+  "#059669",
+  "#d97706",
+  "#7c3aed",
+  "#dc2626",
+  "#0891b2",
+  "#4f46e5",
+  "#65a30d"
+];
+
+export function buildVisNetworkTrialModel(data: GraphData, options: VisNetworkTrialOptions = {}): VisNetworkTrialModel {
+  const adapter = buildGraphRendererAdapterData(data, options);
+  const adapterNodeById = new Map(adapter.nodes.map((node) => [node.id, node]));
+  const nodeIds = new Set(data.nodes.map((node) => node.id));
+  const communityNodeIds = new Map<string, string[]>();
+  for (const node of data.nodes) {
+    const communityId = String(node.community ?? "_none");
+    const list = communityNodeIds.get(communityId) ?? [];
+    list.push(node.id);
+    communityNodeIds.set(communityId, list);
+  }
+
+  const nodes = data.nodes.map((node, index): VisNetworkTrialNode => {
+    const adapterNode = adapterNodeById.get(node.id);
+    const communityId = node.community == null ? null : String(node.community);
+    const pinHint = adapterNode?.pinHint ?? {
+      nodeId: node.id,
+      wikiPath: node.source_path ?? node.id,
+      pinned: false,
+      position: null
+    };
+    return {
+      id: node.id,
+      label: node.label,
+      x: finiteNumber(adapterNode?.point.x, finiteNumber(node.x, index % 100)),
+      y: finiteNumber(adapterNode?.point.y, finiteNumber(node.y, Math.floor(index / 100))),
+      size: pinHint.pinned ? 8 : adapterNode?.selected ? 8 : adapterNode?.searchHit ? 7 : 4,
+      color: adapterNode?.selected
+        ? "#ef4444"
+        : adapterNode?.searchHit
+          ? "#f59e0b"
+          : colorForCommunity(communityId),
+      communityId,
+      sourcePath: adapterNode?.sourcePath ?? node.source_path ?? node.id,
+      selected: adapterNode?.selected ?? false,
+      searchHit: adapterNode?.searchHit ?? false,
+      pinned: pinHint.pinned,
+      pinHint,
+      aggregationIds: adapterNode?.aggregationIds ?? []
+    };
+  });
+
+  const edges = data.edges
+    .filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to))
+    .map((edge): VisNetworkTrialEdge => ({
+      id: edge.id,
+      from: edge.from,
+      to: edge.to,
+      color: "#94a3b8",
+      width: Math.max(0.25, Math.min(1.5, Number(edge.weight ?? 0.6))),
+      relationType: edge.relation_type ?? edge.type ?? null
+    }));
+
+  const communities = adapter.communities.map((community): VisNetworkTrialCommunity => ({
+    id: community.id,
+    label: community.label,
+    nodeIds: communityNodeIds.get(community.id) ?? community.nodeIds,
+    selected: community.selected,
+    searchResultIds: community.searchResultIds,
+    pinnedNodeIds: community.pinHints.map((hint) => hint.nodeId)
+  }));
+
+  const aggregations = adapter.aggregations.map((aggregation): VisNetworkTrialAggregation => ({
+    id: aggregation.id,
+    communityId: aggregation.communityId,
+    nodeIds: aggregation.nodeIds,
+    selectedNodeIds: aggregation.selectedNodeIds,
+    searchResultIds: aggregation.searchResultIds,
+    pinnedNodeIds: aggregation.pinnedNodeIds,
+    totalCount: aggregation.totalCount
+  }));
+
+  return {
+    nodes,
+    edges,
+    communities,
+    aggregations,
+    behavior: buildGraphRendererBehaviorContract(adapter, "candidate-global")
+  };
+}
+
+function colorForCommunity(communityId: string | null): string {
+  if (!communityId) return "#64748b";
+  const index = Math.abs(hashString(communityId)) % COMMUNITY_COLORS.length;
+  return COMMUNITY_COLORS[index];
+}
+
+function hashString(value: string): number {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = ((hash << 5) - hash + value.charCodeAt(index)) | 0;
+  }
+  return hash;
+}
+
+function finiteNumber(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}

package/skills/llm-wiki-skill/packages/graph-engine/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "noEmitOnError": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/skills/llm-wiki-skill/packages/graph-engine/vite.config.ts

@@ -0,0 +1,15 @@
+import { resolve } from "node:path";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  build: {
+    emptyOutDir: true,
+    lib: {
+      entry: resolve(__dirname, "src/index.ts"),
+      name: "LlmWikiGraphEngine",
+      formats: ["es", "iife"],
+      fileName: (format) => (format === "es" ? "engine.esm.js" : "engine.iife.js")
+    },
+    sourcemap: true
+  }
+});

package/skills/llm-wiki-skill/platforms/claude/CLAUDE.md

@@ -0,0 +1,37 @@
+# Claude Code 入口
+
+这是 Claude Code 的薄入口文件。共享说明看 [../../README.md](../../README.md)，核心能力看 [../../SKILL.md](../../SKILL.md)。
+
+## Claude 应该怎么装
+
+优先执行：
+
+```bash
+bash install.sh --platform claude
+```
+
+如果你还需要网页 / X / 微信公众号 / YouTube / 知乎自动提取，再执行：
+
+```bash
+bash install.sh --platform claude --with-optional-adapters
+```
+
+如果你希望 Claude Code 在会话开始时自动感知当前知识库上下文，可以执行：
+
+```bash
+bash install.sh --platform claude --install-hooks
+```
+
+默认安装位置：`~/.claude/skills/llm-wiki`
+
+安装完成后，还会一并带上 `/llm-wiki-upgrade`。以后要更新核心主线，可以直接让 Claude 执行这个命令；如果还要刷新网页 / X / 微信公众号 / YouTube / 知乎自动提取能力，再继续执行带 `--with-optional-adapters` 的升级。
+
+## 兼容入口
+
+老用户仍然可以继续执行：
+
+```bash
+bash setup.sh
+```
+
+它现在会走同一套安装流程，不再单独维护另一份逻辑。若需要自动提取 URL 类来源，再显式追加 `--with-optional-adapters`。

package/skills/llm-wiki-skill/platforms/claude/companions/llm-wiki-upgrade/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: llm-wiki-upgrade
+version: 1.1.0
+description: |
+  升级 llm-wiki 到最新版本。从 GitHub 拉取最新代码并通过官方 install.sh 升级核心主线。
+  网页、X、微信公众号、YouTube、知乎自动提取依赖默认不刷新；需要时再显式开启。
+  触发词：upgrade llm-wiki、更新 llm-wiki、llm-wiki 升级、llm-wiki update
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# /llm-wiki-upgrade
+
+升级 llm-wiki skill 到最新版本。
+
+## 升级流程
+
+### Step 1：读取当前版本
+
+```bash
+SKILL_DIR="$HOME/.claude/skills/llm-wiki"
+OLD_VERSION=$(grep -m1 "^## v" "$SKILL_DIR/CHANGELOG.md" 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' | head -1 || echo "unknown")
+echo "CURRENT_VERSION=$OLD_VERSION"
+```
+
+如果 `SKILL_DIR` 不存在，告知用户尚未安装 llm-wiki，停止流程。
+
+### Step 2：Clone 最新版本到临时目录
+
+```bash
+TMP_DIR=$(mktemp -d)
+git clone --depth 1 https://github.com/sdyckjq-lab/llm-wiki-skill.git "$TMP_DIR/llm-wiki-skill" 2>&1
+echo "CLONE_EXIT=$?"
+```
+
+如果 clone 失败（`CLONE_EXIT` 非 0），告知用户网络问题，停止流程。
+
+### Step 3：读取新版本号
+
+```bash
+NEW_VERSION=$(grep -m1 "^## v" "$TMP_DIR/llm-wiki-skill/CHANGELOG.md" 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' | head -1 || echo "unknown")
+echo "NEW_VERSION=$NEW_VERSION"
+```
+
+如果 `OLD_VERSION == NEW_VERSION`，告知用户已是最新版本，清理临时目录后结束：
+
+```bash
+rm -rf "$TMP_DIR"
+```
+
+### Step 4：执行官方升级
+
+从临时目录（带 `.git`）执行 `install.sh --upgrade`。
+
+注意：默认升级只更新知识库核心主线，不主动刷新网页、X、微信公众号、YouTube、知乎自动提取所需的可选依赖。
+
+```bash
+bash "$TMP_DIR/llm-wiki-skill/install.sh" --upgrade --platform claude 2>&1
+echo "UPGRADE_EXIT=$?"
+```
+
+如果 `UPGRADE_EXIT` 非 0，告知用户升级失败，展示关键信息，清理临时目录后停止流程。
+
+### Step 5：清理临时目录
+
+```bash
+rm -rf "$TMP_DIR"
+```
+
+### Step 6：展示更新内容
+
+读取 `$HOME/.claude/skills/llm-wiki/CHANGELOG.md`，提取 `OLD_VERSION` 到 `NEW_VERSION` 之间的变更，提炼 3-5 条用户最关心的变化。
+
+如果新版包含“默认只装核心主线 / 可选提取器显式开启”这类变化，要明确告诉用户：
+
+- 现在默认升级不会主动刷新网页、X、微信公众号、YouTube、知乎自动提取能力
+- 如果用户需要这些自动提取能力，可以继续执行：
+
+```bash
+bash "$HOME/.claude/skills/llm-wiki/install.sh" --upgrade --platform claude --with-optional-adapters
+```
+
+输出格式：
+
+```text
+llm-wiki $NEW_VERSION 升级完成（从 $OLD_VERSION）
+
+更新内容：
+- [变化1]
+- [变化2]
+- ...
+
+如果需要开启或刷新网页 / X / 微信公众号 / YouTube / 知乎自动提取功能，可以告诉我执行带 --with-optional-adapters 的升级。
+```

package/skills/llm-wiki-skill/platforms/codex/AGENTS.md

@@ -0,0 +1,23 @@
+# Codex 入口
+
+<!-- llm-wiki context: 如有知识库，优先查阅 wiki/index.md -->
+
+这是 Codex 的薄入口文件。共享说明看 [../../README.md](../../README.md)，核心能力看 [../../SKILL.md](../../SKILL.md)。
+
+## Codex 应该怎么装
+
+执行：
+
+```bash
+bash install.sh --platform codex
+```
+
+如果你还需要网页 / X / 微信公众号 / YouTube / 知乎自动提取，再执行：
+
+```bash
+bash install.sh --platform codex --with-optional-adapters
+```
+
+默认安装位置：`~/.codex/skills/llm-wiki`
+
+如果用户环境仍然在用旧的 `~/.Codex/skills`，安装器会自动兼容。