jishushell 0.5.22 → 0.6.18

package/apps/anythingllm-container.yaml

@@ -5,6 +5,8 @@ jishushell:
   min_version: "0.5.15"
 description: "Mintplex Labs 开源 RAG 引擎：单容器 + 内置 LanceDB 向量库 + 内置 Xenova ONNX embedder（默认零外部依赖）+ OpenAI 兼容 chat API；通过 anythingllm-shim 暴露 kb_search 工具给 OpenClaw agent"
 singleInstance: true
+integrations:
+  - kind: anythingllm
 
 # 拓扑（单容器，无 sidecar）
 #   anythingllm (port 3001) ── host :18097 ── 用户浏览器 / shim API 调
@@ -21,15 +23,18 @@ singleInstance: true
 #   - STORAGE_DIR 落到 bind-mounted /app/server/storage，模型/向量/文件全持久化
 #   - DISABLE_TELEMETRY=true 不发数据回 Mintplex
 #   - 默认 embedder 内置（Xenova/all-MiniLM-L6-v2 ONNX）—— 不配 EMBEDDING_ENGINE 走 native
-#   - LLM provider 不预设；用户首启时 setup wizard 或 API 配，或者让 shim 通过 API 预填
+#   - AnythingLLM 的启动后 bootstrap 由 `anythingllm` integration 负责：
+#     等 /api/ping、写 Generic OpenAI provider、生成 dev API key、写
+#     provider-credentials、建 default workspace。
+#   - 该 bootstrap 现在写的是 Core proxy URL + instance-scoped proxy token，
+#     不再把真实 upstream key 写进 AnythingLLM 私有配置。
 #
 # 端口选择：18097 在 panel 18xxx 段，避开 18088 filebrowser / 18092-18096 weknora 段
 # (虽然 weknora 已卸) / 18099 fastembed-bge (已删) / 18790 openclaw gateway。
 #
-# host_network: docker_bridge 让 anythingllm-shim 容器（实际跑在 claw1 gateway
-# 容器内）经 host.docker.internal:18097 调 AnythingLLM（跟之前 fastembed-bge
-# 同套路；nomad.hcl 已经声明 docker_bridge host_network）。同时用户浏览器
-# 走 LAN IP 10.188.5.25:18097 直接访问 UI（双地址 docker-proxy 自动处理）。
+# 端口使用默认 host_network: external，让用户浏览器和其它容器都走 LAN IP
+# 10.188.5.25:18097 访问。不要改成 docker_bridge；那会只绑定 docker0，
+# 导致 UI 从局域网不可达。
 
 tasks:
   - name: anythingllm
@@ -62,13 +67,12 @@ tasks:
         port: 18097
         container_port: 3001
         visibility: external
-        # 不指定 host_network → 默认 0.0.0.0 publish：LAN（用户浏览器）和
-        # docker0 (172.17.0.1，shim 经 host.docker.internal 调) 全覆盖。
-        # 之前 docker_bridge 只绑 172.17.0.1，UI 不可达。
+        # 不指定 host_network → 默认 external：绑定主机对外网卡，和
+        # capability registry 广告给其它容器的 LAN IP 保持一致。
     volumes:
       # 单一数据卷涵盖 sqlite + LanceDB + workspace docs + embedder ONNX cache。
       # 跟其它 app 数据目录保持隔离习惯。
-      - source: "~/.jishushell/apps/${app_id}/data"
+      - source: "~/.jishushell/apps/${instance.id}/data"
         target: "/app/server/storage"
     health:
       http:
@@ -87,8 +91,13 @@ provides:
   # panel 注入 ANYTHINGLLM_BASE_URL。命名遵循 `<category>-<name>` 约定
   # （见 scripts/check-app-spec.mjs 的 categoryOf 分类规则）。
   - capability: "knowledge-anythingllm"
+    id: "anythingllm"
+    kind: "knowledge"
+    interface: "kb-search"
     task: "anythingllm"
     port: 18097
+    endpoint:
+      portName: "http"
     path: "/api/v1"
     protocol: "http"
     visibility: "external"
@@ -111,177 +120,11 @@ lifecycle:
     - downloadImage: "mintplexlabs/anythingllm:latest"
       timeout_ms: 1800000
       idle_timeout_ms: 1800000
-    - mkdir: "~/.jishushell/apps/${app_id}/data"
+    - mkdir: "~/.jishushell/apps/${instance.id}/data"
 
   pre_start:
     # 幂等：start/restart 都过这条路径，目录被误删可自愈。
-    - mkdir: "~/.jishushell/apps/${app_id}/data"
-
-  post_start:
-    # 首启自动布线，幂等可重跑：
-    #   1) 等 /api/ping 200（首启要解压 ~150MB Xenova ONNX，Pi 上 ~60-120s）
-    #   2) 从 panel 拿默认 LLM provider 凭据（GET /api/internal/default-provider）
-    #      panel 端 default_provider 没设 → ready:false → 跳过 LLM 自配，
-    #      留给用户在 UI 里手动选
-    #   3) ready:true 时把 generic-openai provider 灌进去（无视用户上游真协议；
-    #      panel proxy 反正只暴露 OpenAI 兼容口子）
-    #   4) 生成 AnythingLLM dev API key（POST /api/system/generate-api-key，
-    #      单用户模式无 auth），落 credentials.json
-    #   5) 建默认 workspace "default"（已存在则忽略，AnythingLLM 自身的 unique 约束）
-    #
-    # 关键设计：整个脚本必须幂等。每次 start/restart 都重跑，但：
-    #   - update-env 重复 POST = 同样的环境值再写一遍，OK
-    #   - generate-api-key 重复调 = 多生成几把 key（不丢失旧的，但旧的也能用，
-    #     credentials.json 只保留最新一把，shim 端拿这把就行）
-    #   - workspace/new 重复调 = AnythingLLM 返回 409 / 重复，被 || true 吞掉
-    #
-    # 失败处理：任何一步失败都 set -e 兜，post_start 整体失败 → app 状态停留
-    # 在 "installed" 但 currentTaskStatus=error，用户在 UI 上看得到，重启再跑。
-    # 全部 JSON 解析 / 文件写入走 `node -e` —— node 是 panel 装机后**唯一**
-    # 必定存在的运行时（jishushell 本身跑在 node 上）。jq 在 Pi/Debian 默认不装；
-    # python3 在 Alpine slim / 极简 Linux 上不一定有。用 node 才能保证第三方
-    # 用户初装即可用。
-    - run: |
-        set -e
-        BASE_URL="http://${JISHUSHELL_LAN_HOST:-127.0.0.1}:18097"
-        CRED_DIR="$HOME/.jishushell/apps/anythingllm-container"
-        CRED_FILE="$CRED_DIR/credentials.json"
-        mkdir -p "$CRED_DIR"
-
-        # jget <dot.path> — read JSON from stdin, print field at path, empty on miss
-        jget() {
-          node -e 'let s="";process.stdin.on("data",c=>s+=c).on("end",()=>{try{let v=JSON.parse(s);for(const k of process.argv[1].split("."))v=v?.[k];process.stdout.write(v==null?"":String(v));}catch{process.stdout.write("")}})' "$1"
-        }
-
-        echo "[post_start] waiting for AnythingLLM /api/ping ..."
-        for i in $(seq 1 60); do
-          code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "$BASE_URL/api/ping" || echo 000)
-          if [ "$code" = "200" ]; then
-            echo "[post_start] /api/ping is 200 (after ${i}x2s)"
-            break
-          fi
-          sleep 2
-        done
-        # final check; if still down, post_start fails fast
-        curl -sf --max-time 5 "$BASE_URL/api/ping" >/dev/null
-
-        echo "[post_start] fetching panel default provider ..."
-        DP_JSON=$(curl -sf --max-time 8 \
-          -H "X-Jishushell-Internal-Token: $JISHUSHELL_INTERNAL_TOKEN" \
-          "$JISHUSHELL_PANEL_URL/api/internal/default-provider" || echo '{"ready":false,"reason":"panel_unreachable"}')
-        READY=$(printf '%s' "$DP_JSON" | jget ready)
-
-        if [ "$READY" = "true" ]; then
-          MODEL=$(printf '%s' "$DP_JSON" | jget modelId)
-          # W1 直连上游：用户上游 baseUrl + decrypted apiKey 直接给 AnythingLLM。
-          # 牺牲了 panel proxy 的 rate-limit / circuit-break / usage logging —
-          # W2 加 app-scoped proxy key 后切回经 proxy。
-          BASE=$(printf '%s' "$DP_JSON" | jget baseUrl)
-          KEY=$(printf '%s' "$DP_JSON" | jget apiKey)
-          echo "[post_start] configuring LLM provider: $MODEL @ $BASE"
-          # Build update-env body in node so apiKey / baseUrl / modelId can contain
-          # `"`, `\`, newlines, or any other JSON-significant chars without breaking
-          # the shell-interpolated payload (review finding F5).
-          UPDATE_BODY=$(BASE="$BASE" KEY="$KEY" MODEL="$MODEL" node -e '
-            process.stdout.write(JSON.stringify({
-              LLMProvider: "generic-openai",
-              GenericOpenAiBasePath: process.env.BASE,
-              GenericOpenAiKey: process.env.KEY,
-              GenericOpenAiModelPref: process.env.MODEL,
-              GenericOpenAiMaxTokens: "4096",
-            }));
-          ')
-          # Tolerate 401/403 — AnythingLLM ships single-user no-auth by default,
-          # but a user can opt-in to password protection via UI. validatedRequest
-          # then mandates a JWT we don't have, and there's no admin-bootstrap
-          # endpoint we can call here. Log the actionable next step and continue
-          # so the script stays idempotent (review finding F1).
-          UPDATE_HTTP=$(curl -s -o /tmp/anyllm-upd.txt -w '%{http_code}' --max-time 10 \
-            -X POST "$BASE_URL/api/system/update-env" \
-            -H "Content-Type: application/json" \
-            --data "$UPDATE_BODY" || echo 000)
-          case "$UPDATE_HTTP" in
-            2*) echo "[post_start] LLM provider configured" ;;
-            401|403)
-              echo "[post_start] WARN: AnythingLLM /api/system/update-env returned HTTP $UPDATE_HTTP — looks like a password is set; configure LLM in the UI then restart"
-              ;;
-            *)
-              echo "[post_start] WARN: update-env HTTP $UPDATE_HTTP — leaving LLM unconfigured"
-              [ -s /tmp/anyllm-upd.txt ] && head -c 400 /tmp/anyllm-upd.txt
-              ;;
-          esac
-        else
-          REASON=$(printf '%s' "$DP_JSON" | jget reason)
-          echo "[post_start] skip LLM auto-config (reason=${REASON:-unknown}); user will pick in UI"
-        fi
-
-        # 复用已存在的 dev API key（generate-api-key 增量、不可撤销，
-        # 每次重启重生只会堆 key；credentials.json 保稳定）。
-        if [ -f "$CRED_FILE" ]; then
-          KEY_JSON=$(CRED_FILE="$CRED_FILE" node -e 'try{const j=JSON.parse(require("fs").readFileSync(process.env.CRED_FILE,"utf-8"));process.stdout.write(String(j.apiKey||""))}catch{process.stdout.write("")}')
-        else
-          KEY_JSON=""
-        fi
-        if [ -n "$KEY_JSON" ]; then
-          echo "[post_start] reusing existing dev API key from $CRED_FILE"
-        else
-          echo "[post_start] generating new dev API key ..."
-          # Same 401 tolerance as update-env: if the user enabled password
-          # protection, generate-api-key needs a JWT. Surface the next step
-          # and exit cleanly so OpenClaw adapters fall back to "knowledge
-          # unconfigured" instead of leaving post_start in a permanent error.
-          GEN_HTTP=$(curl -s -o /tmp/anyllm-gen.json -w '%{http_code}' --max-time 8 \
-            -X POST "$BASE_URL/api/system/generate-api-key" || echo 000)
-          case "$GEN_HTTP" in
-            2*)
-              KEY_JSON=$(jget apiKey.secret < /tmp/anyllm-gen.json)
-              if [ -z "$KEY_JSON" ]; then
-                echo "[post_start] WARN: generate-api-key returned 2xx but apiKey.secret missing — skipping kb wiring"
-                head -c 400 /tmp/anyllm-gen.json; echo
-              fi
-              ;;
-            401|403)
-              echo "[post_start] WARN: generate-api-key HTTP $GEN_HTTP — AnythingLLM is password-protected. Generate a dev API key in the UI (Settings → API Keys) and write it to $CRED_FILE, then restart. Skipping kb wiring for this start."
-              ;;
-            *)
-              echo "[post_start] WARN: generate-api-key HTTP $GEN_HTTP — skipping kb wiring"
-              [ -s /tmp/anyllm-gen.json ] && head -c 400 /tmp/anyllm-gen.json
-              ;;
-          esac
-        fi
-
-        if [ -z "$KEY_JSON" ]; then
-          echo "[post_start] no API key available; skipping workspace seed + credentials write (post_start still considered success)"
-          echo "[post_start] DONE"
-          exit 0
-        fi
-
-        echo "[post_start] ensuring default workspace ..."
-        WS_HTTP=$(curl -s -o /tmp/anyllm-ws.json -w '%{http_code}' --max-time 10 \
-          -X POST "$BASE_URL/api/v1/workspace/new" \
-          -H "Authorization: Bearer $KEY_JSON" \
-          -H "Content-Type: application/json" \
-          -d '{"name":"default"}')
-        echo "[post_start] workspace POST → HTTP $WS_HTTP"
-        case "$WS_HTTP" in
-          2*) : ;;
-          4*) echo "  (likely already exists; ignoring)" ;;
-          *)  echo "[post_start] FAIL: workspace creation HTTP $WS_HTTP"; cat /tmp/anyllm-ws.json; exit 1 ;;
-        esac
-
-        # 写 credentials.json — 用 node 避免 shell quote 注入风险。
-        APIKEY="$KEY_JSON" BASEURL="$BASE_URL" CREDFILE="$CRED_FILE" node -e '
-          const fs = require("fs");
-          fs.writeFileSync(process.env.CREDFILE, JSON.stringify({
-            apiKey: process.env.APIKEY,
-            workspace: "default",
-            baseUrl: process.env.BASEURL,
-          }, null, 2));
-          fs.chmodSync(process.env.CREDFILE, 0o600);
-        '
-        echo "[post_start] credentials.json written → $CRED_FILE"
-        echo "[post_start] DONE"
-      timeout_ms: 300000
+    - mkdir: "~/.jishushell/apps/${instance.id}/data"
 
   uninstall:
     - deleteImage: "mintplexlabs/anythingllm:latest"

package/apps/browserless-chromium-container.yaml

@@ -10,19 +10,16 @@ tasks:
   - name: browserless
     role: service
     runtime: container
-    # rebrowser 镜像在 Chromium 源码层面 patch 了 CDP Runtime.Enable 泄露问题，
-    # 是目前对抗自动化检测最彻底的方案（适用于小红书/淘宝等强风控场景）。
-    # 如遇 ghcr.io/browserless/chromium 仍被风控，可切换为：
-    #   image: "ghcr.io/browserless/chromium:rebrowser"
-    # （rebrowser 分支由 browserless 官方维护，与 latest 保持同步）
+    # 使用 Browserless 官方公开镜像标签。ghcr.io/browserless/chromium:rebrowser
+    # 当前不存在，安装时会被 GHCR 永久拒绝为 manifest unknown。
     image: "ghcr.io/browserless/chromium:latest"
     env:
       HOST: "0.0.0.0"
       PORT: "3000"
       TOKEN: ""
-      CONCURRENT: "5"
+      CONCURRENT: "2"
       QUEUED: "10"
-      TIMEOUT: "120000"
+      TIMEOUT: "600000"
       # 反风控配置
       # STEALTH=true: 启用 puppeteer-extra-plugin-stealth，注入多项 evasion 补丁：
       #   修复 navigator.plugins/languages、WebGL vendor、canvas 指纹、chrome 对象等
@@ -39,11 +36,11 @@ tasks:
       # 持久化用户数据（cookies/localStorage/session），登录后会话保持
       DATA_DIR: "/tmp/browserless-data"
     volumes:
-      - source: "~/.jishushell/apps/${app_id}/data"
+      - source: "~/.jishushell/apps/${instance.id}/data"
         target: "/tmp/browserless-data"
     resources:
       cpu: "1000m"
-      memory: "2048Mi"
+      memory: "1152Mi"
     ports:
       - name: http
         port: 3000
@@ -59,9 +56,12 @@ tasks:
 
 provides:
   - capability: "browserless-debugger"
+    kind: "ui"
+    interface: "web-ui"
     port: 3000
     path: "/debugger/"
     protocol: "http"
+    embedded: "proxy"
     description: "Browserless Debug Viewer，可在实例页中嵌入浏览器画面"
   - capability: "browserless-api"
     task: "browserless"
@@ -75,16 +75,21 @@ provides:
     protocol: "http"
     description: "Browserless API 文档页"
   - capability: "browser-ws"
+    id: "browserless"
+    kind: "browser"
+    interface: "cdp-ws"
     task: "browserless"
     port: 3000
+    endpoint:
+      portName: "http"
     protocol: "ws"
     description: "Browserless CDP/WebSocket 连接端点（ws://host:3000），用于 browser 类 require 自动绑定（命名遵循 <category>-<vendor> 约定）"
 
 lifecycle:
   install:
     - downloadImage: "ghcr.io/browserless/chromium:latest"
-    - mkdir: "~/.jishushell/apps/${app_id}/data"
+    - mkdir: "~/.jishushell/apps/${instance.id}/data"
   pre_start:
-    - mkdir: "~/.jishushell/apps/${app_id}/data"
+    - mkdir: "~/.jishushell/apps/${instance.id}/data"
   uninstall:
-    - deleteImage: "ghcr.io/browserless/chromium:latest"
+    - deleteImage: "ghcr.io/browserless/chromium:latest"

package/apps/filebrowser-container.yaml

@@ -17,6 +17,14 @@ tasks:
     # entrypoint dance from the :s6 variant — uid/gid is set once at job
     # build time.
     user: "host"
+    env:
+      # The image's baked /healthcheck.sh reads the probe port from
+      # /config/settings.json ("port": 80), not from the --port flag we pass
+      # below. Since the server actually listens on 8080, the docker
+      # HEALTHCHECK hits :80, gets connection-refused, and the container is
+      # marked unhealthy even though every HTTP endpoint answers 200.
+      # healthcheck.sh honors FB_PORT first, so pin it to the real port.
+      FB_PORT: "8080"
     args:
       # Filebrowser CLI flag precedence is Flags > Env > Config file > DB.
       # The image's init.sh seeds /config/settings.json from baked-in
@@ -50,12 +58,12 @@ tasks:
       - source: "~/.jishushell/files"
         target: "/srv"
       # SQLite settings DB + the auto-seeded admin user record.
-      - source: "~/.jishushell/apps/${app_id}/database"
+      - source: "~/.jishushell/apps/${instance.id}/database"
         target: "/database"
       # Filebrowser image's init.sh writes /config/settings.json from defaults
       # on first run; bind-mounting an app-owned dir lets us persist any
       # branding tweaks without baking them into the image.
-      - source: "~/.jishushell/apps/${app_id}/config"
+      - source: "~/.jishushell/apps/${instance.id}/config"
         target: "/config"
     health:
       http:
@@ -82,7 +90,7 @@ provides:
     protocol: "http"
     visibility: "external"
     description: "Filebrowser Web UI；panel 反代到 /apps/filebrowser/*"
-  # Web-* convention (matches web-openwebui / web-searxng) so adapters that
+  # Web-* convention (matches web-openwebui / web-searxng) so integration logic that
   # iterate "web-*" capabilities pick it up for dashboard tiles.
   - capability: "web-filebrowser"
     task: "filebrowser"
@@ -97,8 +105,13 @@ provides:
   # Does NOT gate any API calls; Filebrowser itself runs noauth and is guarded
   # by the panel JWT reverse-proxy layer.
   - capability: "files-filebrowser"
+    id: "filebrowser"
+    kind: "files"
+    interface: "web-file-manager"
     task: "filebrowser"
     port: 18088
+    endpoint:
+      portName: "http"
     path: "/apps/filebrowser"
     protocol: "http"
     visibility: "external"
@@ -107,8 +120,8 @@ provides:
 lifecycle:
   install:
     - downloadImage: "filebrowser/filebrowser:latest"
-    - mkdir: "~/.jishushell/apps/${app_id}/database"
-    - mkdir: "~/.jishushell/apps/${app_id}/config"
+    - mkdir: "~/.jishushell/apps/${instance.id}/database"
+    - mkdir: "~/.jishushell/apps/${instance.id}/config"
     # Seed the SQLite DB with three things Filebrowser needs in noauth mode:
     #   1. `config init --auth.method=noauth` — creates DB with noauth scheme
     #   2. `config set --baseURL=/apps/filebrowser` — bakes the sub-path so the
@@ -121,8 +134,8 @@ lifecycle:
     # Idempotent: skipped when DB already exists. Mirrors searxng's heredoc
     # settings.yml generation pattern.
     - run: |
-        DB_DIR="$HOME/.jishushell/apps/${app_id}/database"
-        CONFIG_DIR="$HOME/.jishushell/apps/${app_id}/config"
+        DB_DIR="$HOME/.jishushell/apps/${instance.id}/database"
+        CONFIG_DIR="$HOME/.jishushell/apps/${instance.id}/config"
         DB_FILE="$DB_DIR/filebrowser.db"
         if [ ! -f "$DB_FILE" ]; then
           docker run --rm \
@@ -158,7 +171,7 @@ lifecycle:
               --perm.admin >/dev/null
         fi
   pre_start:
-    - mkdir: "~/.jishushell/apps/${app_id}/database"
-    - mkdir: "~/.jishushell/apps/${app_id}/config"
+    - mkdir: "~/.jishushell/apps/${instance.id}/database"
+    - mkdir: "~/.jishushell/apps/${instance.id}/config"
   uninstall:
     - deleteImage: "filebrowser/filebrowser:latest"

package/apps/hermes-container.yaml

@@ -3,7 +3,8 @@ name: Hermes Agent
 version: "1.0.0"
 jishushell:
   min_version: "0.4.30"
-agentType: hermes
+integrations:
+  - kind: hermes
 description: "Hermes Agent 容器运行时，使用 apps 目录作为统一安装根"
 singleInstance: false
 
@@ -39,10 +40,18 @@ provides:
     task: "gateway"
     port: 8642
     protocol: "http"
+    health:
+      kind: "http"
+      path: "/health"
     description: "Hermes Agent Web UI"
   - capability: "llm-agent"
+    id: "hermes"
+    kind: "llm"
+    interface: "openai-compatible"
     task: "gateway"
     port: 8642
+    endpoint:
+      portName: "gateway"
     protocol: "http"
     path: "/v1"
     auth:
@@ -52,18 +61,30 @@ provides:
 
 requires:
   - capability: "llm"
+    slot: "llm"
+    kind: "llm"
+    interface: "openai-compatible"
     inject_as: "LLM_ENDPOINT"
     required: false
     cardinality: "one"
   - capability: "search"
+    slot: "search"
+    kind: "search"
+    interface: "searxng-json"
     inject_as: "SEARCH_API_BASE_URL"
     required: false
     cardinality: "one"
   - capability: "browser"
+    slot: "browser"
+    kind: "browser"
+    interface: "cdp-ws"
     inject_as: "BROWSER_CDP_URL"
     required: false
     cardinality: "one"
   - capability: "mcp"
+    slot: "mcp"
+    kind: "mcp"
+    interface: "mcp-http"
     inject_as: "MCP_SERVERS"
     required: false
-    cardinality: "many"
+    cardinality: "many"

package/apps/jishu-kb-container.yaml

@@ -0,0 +1,152 @@
+id: jishu-kb-container
+name: JishuShell KB
+version: "0.1.1"
+jishushell:
+  min_version: "0.5.15"
+description: "JishuShell-KB: BM25 + 向量 + cross-encoder rerank 的本地知识库（单镜像）。提供 /api/kb/* 原生检索 API + OpenAI 兼容 /v1 透传 + Web UI。"
+singleInstance: true
+integrations:
+  - kind: jishukb
+
+# 拓扑（单容器，无 sidecar）
+#   jishu-kb (container :8088) ── host :18095 ── 用户浏览器 / shim / agent
+#                              └─ /data （SQLite + 向量索引 + 上传文档 + ONNX rerank 模型）
+#
+# 端到端调用链（OpenClaw agent）：
+#   用户 → OpenClaw（自带 LLM）→ 决定调 kb_search → mcporter call kb.kb_search
+#     → jishukb-shim → POST http://host.docker.internal:18095/api/kb/default/search
+#     → 返回 ranked chunks + scores → OpenClaw 自带 LLM 拼答案 + 引用
+#
+# 关键设计：
+#   - v1 不带 auth（LAN-trust 模型，同 AnythingLLM / WeKnora / SearXNG）。
+#     JISHU_KB_AUTH_TOKEN 留空即可。
+#   - JishuKB 不再由 Core 注入 default LLM key。generation provider
+#     由用户在 JishuKB 自己的 UI 中手动配置；Core 不把真实 upstream key
+#     写进 /api/admin/provider。
+#   - Core 仍保留知识库默认 default KB 创建、provider-credentials 写入、
+#     knowledge capability 暴露等集成能力。
+#   - Ollama URL 通过 `requires: llm-ollama` 注入到 JISHU_KB_OLLAMA_URL，
+#     供 embedding/rerank 模型按需调用；未绑定时为空字符串，jishu-kb
+#     fallback 到自身 config.go 默认值。
+#
+# 端口选择：18095 在 panel 18xxx 段（anythingllm 18097、filebrowser 18088、
+#   weknora 18092-18094 已用）。
+
+tasks:
+  - name: jishukb
+    role: service
+    runtime: container
+    # 镜像 GHCR public，多架构（amd64/arm64）。Pin 0.1.1 避免 :latest 漂移。
+    image: "ghcr.io/x-aijishu/jishu-kb:0.1.1"
+    user: "host"
+    env:
+      # 监听端口（container 内）。
+      JISHU_KB_PORT: "8088"
+      # 数据持久化目录。镜像默认即 /data，显式声明便于看 spec 一目了然。
+      JISHU_KB_DATA: "/data"
+      # v1 ships without auth — see manifest top notes + plan.md §5.
+      JISHU_KB_AUTH_TOKEN: ""
+      # The panel now embeds KB through the capability proxy. That keeps
+      # absolute `/api/...` calls on the KB origin and lets the proxy
+      # bootstrap hydrate server-stored conversations into a new browser
+      # before KB's own app.js reads localStorage. Keep direct iframe
+      # embedding permissive for users who open :18095 manually.
+      #
+      # Wildcard is intentional here: panel origin can vary by LAN IP / host
+      # name, while JishuShell-KB v1 already runs without auth in the same
+      # LAN-trust model as AnythingLLM / WeKnora.
+      JISHU_KB_FRAME_ANCESTORS: "*"
+      # Ollama URL: injected by `requires: llm-ollama` 下方的 capability slot。
+      # `${requires.X}` materialization 当前不支持 `:-default` 兜底语法；
+      # 未绑定时这里就是空字符串。jishu-kb 在 internal/config/config.go
+      # 中自带默认值 http://localhost:11434，不影响启动。
+      JISHU_KB_OLLAMA_URL: "${requires.JISHU_KB_OLLAMA_URL}"
+      # rerank 默认开；topK 默认 6（与 shim 默认值保持一致）。
+      JISHU_KB_RERANK: "1"
+      JISHU_KB_TOPK: "6"
+      TZ: "Asia/Shanghai"
+      # generation provider 由用户在 JishuKB UI 内自行配置；Core 不在启动
+      # 时预置默认上游 key，避免明文落入 app 私有配置或运行时 spec。
+    resources:
+      # jishu-kb 实测 ~300-600MB RSS：Go runtime + ONNX rerank 模型（首启加载）
+      # + SQLite/向量索引 mmap。给 1024Mi 留 buffer，1 vCPU 足够并发查询。
+      cpu: "1000m"
+      memory: "1024Mi"
+    ports:
+      - name: http
+        port: 18095
+        container_port: 8088
+        visibility: external
+        # 默认 external：绑定主机对外网卡，让浏览器从 LAN IP 直接访问 Web UI。
+    volumes:
+      # 单卷涵盖 SQLite + 向量索引 + 上传文档 + ONNX 模型缓存。
+      - source: "~/.jishushell/apps/${instance.id}/data"
+        target: "/data"
+    health:
+      http:
+        # main.go:420 — endpoint 是 /health （不是 /healthz）。
+        path: /health
+        port: 8088
+      interval: "15s"
+      timeout: "5s"
+      retries: 6
+      # 首启需要预热 ONNX rerank 模型（cross-encoder/ms-marco-MiniLM 级别，
+      # 解压 + 加载 ~60-120s on Pi/ARM）。给 180s 与 AnythingLLM 看齐。
+      start_period: "180s"
+
+requires:
+  # 用户在 Connections tab 里挑一个 Ollama provider，URL 自动注入为
+  # JISHU_KB_OLLAMA_URL；用于 embedding/rerank 时调用 Ollama 后端。
+  # 未绑定时 env 为空 → jishu-kb 用自身默认 http://localhost:11434
+  # （容器内不可达，需用户在 UI 里手动配，或绑定到合适的 Ollama 实例）。
+  - capability: "llm-ollama"
+    slot: "llm"
+    kind: "llm"
+    interface: "openai-compatible"
+    inject_as: "JISHU_KB_OLLAMA_URL"
+    required: false
+    cardinality: "one"
+
+provides:
+  # 知识库 capability — agent `requires: knowledge` 时 panel 把
+  # KNOWLEDGE_BASE_URL 注入为 http://<host>:18095（裸根，shim 自己拼
+  # /api/kb/<id>/search）。命名遵循 <category>-<slug>。
+  - capability: "knowledge-jishukb"
+    id: "jishukb"
+    kind: "knowledge"
+    interface: "kb-search"
+    task: "jishukb"
+    port: 18095
+    endpoint:
+      portName: "http"
+    path: "/"
+    protocol: "http"
+    visibility: "external"
+    description: "JishuShell-KB native KB API (/api/kb/*) — kb_search returns ranked chunks + scores"
+
+  # Web UI capability。走 embedded: "proxy"：panel 通过 capability proxy
+  # 同源托管 KB 页面，代理 bootstrap 会把绝对 `/api/...`、SSE、WS 等请求
+  # 重写回 KB，并在新浏览器首屏前把服务端对话历史预装进 localStorage。
+  # 仍保留上面的 `JISHU_KB_FRAME_ANCESTORS: "*"`，便于用户手动直接打开 :18095。
+  - capability: "web-jishukb"
+    task: "jishukb"
+    port: 18095
+    path: "/"
+    protocol: "http"
+    visibility: "external"
+    embedded: "proxy"
+    description: "JishuShell-KB Web UI"
+
+lifecycle:
+  install:
+    # Container images declared in tasks[].image are pulled automatically by
+    # the install pipeline. Keep this lifecycle focused on app-owned data so
+    # docker pull uses the shared retry/idle-timeout policy.
+    - mkdir: "~/.jishushell/apps/${instance.id}/data"
+
+  pre_start:
+    # 幂等：start/restart 都过这条路径，目录被误删可自愈。
+    - mkdir: "~/.jishushell/apps/${instance.id}/data"
+
+  uninstall:
+    - deleteImage: "ghcr.io/x-aijishu/jishu-kb:0.1.1"