jishushell 0.4.24 → 0.5.15

package/apps/weknora-container.yaml

@@ -0,0 +1,471 @@
+id: weknora-container
+name: WeKnora
+version: "1.0.0"
+jishushell:
+  min_version: "0.5.15"
+description: "Tencent 开源 RAG 知识库：文档解析 + 向量检索 + 对话式问答（5 容器单 Nomad TaskGroup）"
+singleInstance: true
+
+# 拓扑（每个 task 独立 docker netns，跨 task 经 host.docker.internal:<host-port>）：
+# 注：原始设计想用 Nomad group bridge mode 让 task 共享 netns 走 127.0.0.1，
+# 但需要 /opt/cni/bin/ 下的 containernetworking 插件（Pi 默认没装）。退而用
+# host 端口发布 + host.docker.internal 路由（panel `extra_hosts:host-gateway`
+# 已 mapping 到 172.17.0.1 = docker0 bridge gateway）。
+# 关键：5 个发布端口都设 `host_network: docker_bridge` 让 panel/Nomad 把
+# docker-proxy 绑到 docker0 IP（172.17.0.1），peer 容器走 host.docker.internal
+# 即 172.17.0.1 时打得通。要求 nomad.hcl 声明 `host_network "docker_bridge"
+# { cidr = "172.17.0.0/16" }`（panel doctor 会自动写入）。
+#
+#   weknora-ui  (nginx :80)  ─proxy_pass─►  weknora-app :8080
+#       │                                       │
+#       │                                       ├─► paradedb :5432   (PG17 + pgvector + FTS5；同时承担 vector store)
+#       │                                       ├─► redis    :6379   (任务队列 / 流式响应缓存)
+#       │                                       └─► docreader:50051  (gRPC：PDF / Word / Markdown 解析)
+#       │
+#  host :18092  ◄── published (visibility: external)
+#
+# 关键裁剪（相对官方 docker-compose）：
+#  - RETRIEVE_DRIVER=postgres：复用 paradedb 的 pgvector，**不装 Qdrant / Milvus / Weaviate**（省 1 task + ~70MB 下载）
+#  - WEKNORA_SANDBOX_MODE=disabled：不装 weknora-sandbox（省 ~80MB；阉割 agent 工具沙箱执行，RAG 主流程不受影响）
+#  - 不装 Neo4j / MinIO / Langfuse / Jaeger / SearXNG / Doris / ClickHouse / Dex（都是 profile 才启的）
+#
+# 镜像总下载：~2.8 GB (arm64) / ~3.0 GB (amd64)；解压磁盘 ~6.5 GB
+# 稳态内存预算：~1.5–2.0 GB（4 GB Pi 紧张，建议 8 GB Pi 5 / x86 节点）
+
+tasks:
+  # ────────────────────────────────────────────────────────────────
+  # 1) PostgreSQL（ParadeDB：PG17 + pgvector + ParadeDB BM25 全文）
+  #    role: sidecar → prestart 起来并持续运行；service tasks 在所有
+  #    sidecar Running 后再启动（但 Running ≠ Ready，weknora-app 自己
+  #    要靠连接重试兜住 DB init 的 30s 窗口）。
+  # ────────────────────────────────────────────────────────────────
+  - name: paradedb
+    role: sidecar
+    runtime: container
+    image: "paradedb/paradedb:v0.22.2-pg17"
+    user: "host"
+    env:
+      POSTGRES_USER: "weknora"
+      # ⚠️ 开发默认值。生产请改：
+      #   docker exec -it <container> psql -U weknora -c "ALTER USER weknora WITH PASSWORD '<new>'"
+      # 并同步更新 weknora-app 的 DB_PASSWORD。
+      POSTGRES_PASSWORD: "weknora-dev-pg-pw"
+      POSTGRES_DB: "WeKnora"
+      PGDATA: "/var/lib/postgresql/data/pgdata"
+    resources:
+      cpu: "500m"
+      memory: "384Mi"
+    ports:
+      - name: pg
+        port: 18093
+        container_port: 5432
+        visibility: external
+        host_network: docker_bridge
+    volumes:
+      - source: "~/.jishushell/apps/${app_id}/postgres"
+        target: "/var/lib/postgresql/data"
+
+  # ────────────────────────────────────────────────────────────────
+  # 2) Redis（任务队列 + Stream Manager 状态）
+  # ────────────────────────────────────────────────────────────────
+  - name: redis
+    role: sidecar
+    runtime: container
+    image: "redis:7.0-alpine"
+    user: "host"
+    args:
+      - "redis-server"
+      - "--appendonly"
+      - "yes"
+      # 无密码：仅 group 内 127.0.0.1 可达，未发布到宿主。
+      # 如需密码，加 --requirepass <pw> 并同步设 weknora-app 的 REDIS_PASSWORD。
+    resources:
+      cpu: "100m"
+      memory: "96Mi"
+    ports:
+      - name: redis
+        port: 18094
+        container_port: 6379
+        visibility: external
+        host_network: docker_bridge
+    volumes:
+      - source: "~/.jishushell/apps/${app_id}/redis"
+        target: "/data"
+
+  # ────────────────────────────────────────────────────────────────
+  # 3) docreader（最大头：1.7 GB；Python + markitdown + PDF 渲染）
+  #    weknora-app `depends_on: docreader (service_healthy)` 是 core
+  #    依赖，**不能砍**。
+  # ────────────────────────────────────────────────────────────────
+  - name: docreader
+    role: sidecar
+    runtime: container
+    image: "wechatopenai/weknora-docreader:latest"
+    # Image entrypoint uses `uv` package manager which writes to /.cache/uv;
+    # forcing host uid (1000:1000) gets Permission denied on the root-owned
+    # filesystem and the container exits 2. Run as root — image is read-only
+    # in the layers that matter; runtime writes go to /tmp/docreader (bind
+    # mount, panel-user owned).
+    user: "0:0"
+    env:
+      DOCREADER_IMAGE_OUTPUT_DIR: "/tmp/docreader"
+      MAX_FILE_SIZE_MB: "50"
+      DOCREADER_MARKITDOWN_MAX_WORKERS: "1"
+      DOCREADER_PDF_RENDER_MAX_WORKERS: "1"
+      DOCREADER_PDF_RENDER_DPI: "200"
+      DOCREADER_PDF_JPEG_QUALITY: "90"
+    resources:
+      cpu: "800m"
+      memory: "768Mi"
+    ports:
+      - name: grpc
+        port: 18095
+        container_port: 50051
+        visibility: external
+        host_network: docker_bridge
+    volumes:
+      # tmp 目录与 weknora-app 共享，docreader 写 / app 读（图片提取场景）。
+      - source: "~/.jishushell/apps/${app_id}/docreader-tmp"
+        target: "/tmp/docreader"
+
+  # ────────────────────────────────────────────────────────────────
+  # 4) WeKnora 后端 app（Go）
+  # ────────────────────────────────────────────────────────────────
+  - name: app
+    role: service
+    runtime: container
+    image: "wechatopenai/weknora-app:latest"
+    # Image entrypoint chowns /app/skills/preloaded; with host uid the
+    # chown fails with "Operation not permitted" and the container crashes.
+    # Bind-mounted /data/files is panel-user owned (1000) — Go binary opens
+    # it as root without issue.
+    user: "0:0"
+    # panel default is cap_drop:ALL; weknora-app entrypoint does
+    # `chown -R appuser /app/skills/preloaded` at startup → needs CHOWN.
+    # It then `su appuser` to drop to non-root → needs SETUID/SETGID/SETPCAP.
+    cap_add: ["CHOWN", "FOWNER", "DAC_OVERRIDE", "SETUID", "SETGID", "SETPCAP"]
+    env:
+      # ── 基础运行时 ──
+      GIN_MODE: "release"
+      LOG_LEVEL: "info"
+      TZ: "Asia/Shanghai"
+      WEKNORA_LANGUAGE: "zh-CN"
+      DISABLE_REGISTRATION: "false"
+
+      # ── 数据库（host_network: docker_bridge → 绑 docker0 IP，
+      #       host.docker.internal=172.17.0.1 容器内可达） ──
+      DB_DRIVER: "postgres"
+      DB_HOST: "host.docker.internal"
+      DB_PORT: "18093"
+      DB_USER: "weknora"
+      DB_PASSWORD: "weknora-dev-pg-pw"
+      DB_NAME: "WeKnora"
+
+      # ── 向量检索：走 paradedb 的 pgvector（砍 Qdrant / Milvus / Weaviate） ──
+      RETRIEVE_DRIVER: "postgres"
+
+      # ── Redis ──
+      REDIS_ADDR: "host.docker.internal:18094"
+      REDIS_DB: "0"
+      REDIS_PREFIX: "stream:"
+      STREAM_MANAGER_TYPE: "redis"
+
+      # ── docreader gRPC ──
+      DOCREADER_ADDR: "host.docker.internal:18095"
+      DOCREADER_TRANSPORT: "grpc"
+
+      # ── 文件存储：local 模式，写到 bind-mounted /data/files ──
+      STORAGE_TYPE: "local"
+      LOCAL_STORAGE_BASE_DIR: "/data/files"
+      MAX_FILE_SIZE_MB: "50"
+
+      # ── Sandbox：关。Agent 工具调用执行能力不可用，RAG 主流程不受影响。 ──
+      #   如需开启：(a) 把 weknora-sandbox 也加进 tasks[]；(b) 改为
+      #   WEKNORA_SANDBOX_MODE=docker；(c) 注意 sandbox 需要 docker.sock 挂载，
+      #   Nomad 调度的容器内不一定有权限——可能需要额外设计。
+      WEKNORA_SANDBOX_MODE: "disabled"
+
+      # ── 安全密钥 ⚠️ 开发默认值，生产前必改 ──
+      #   推荐：openssl rand -hex 32 重新生成；同步改前端 NEXTAUTH_SECRET 之类。
+      JWT_SECRET: "weknora-dev-jwt-secret-CHANGE-ME-IN-PROD"
+      TENANT_AES_KEY: "weknora-dev-tenant-key-32bytes!!"
+      SYSTEM_AES_KEY: "weknora-dev-system-key-32bytes!!"
+
+      # ── LLM provider：留空，让用户在 WeKnora UI 里手动配。 ──
+      #   想用 panel 内嵌 LLM proxy（推荐）的话，UI 里填：
+      #     base_url:  http://host.docker.internal:8090/proxy/v1
+      #     api_key:   <从 panel /instances/:id 拿到的 sk-js-*>
+      #   这样审计 / 限流 / 上游切换都收敛在 panel 一层。
+      OLLAMA_BASE_URL: ""
+
+      # ── Tracing / Observability：全关 ──
+      LANGFUSE_ENABLED: "false"
+      OTEL_TRACES_EXPORTER: "none"
+      OTEL_METRICS_EXPORTER: "none"
+      OTEL_LOGS_EXPORTER: "none"
+      ENABLE_GRAPH_RAG: "false"
+      NEO4J_ENABLE: "false"
+
+      # ── 并发 ──
+      CONCURRENCY_POOL_SIZE: "5"
+
+      # ── SSRF 白名单：默认走 panel 反代，无需对外。 ──
+      SSRF_WHITELIST: ""
+      SSRF_WHITELIST_EXTRA: ""
+    resources:
+      cpu: "600m"
+      memory: "640Mi"
+    ports:
+      - name: http
+        # Published on docker0 so the ui task can reach backend via
+        # host.docker.internal:18096 (no shared netns on Pi w/o CNI).
+        port: 18096
+        container_port: 8080
+        visibility: external
+        host_network: docker_bridge
+    volumes:
+      # 知识库附件落盘。与 ~/.jishushell/files/ 故意分离 ——
+      # WeKnora 自己管文件元数据 / RAG 索引，避免与 panel W3 FTS5 打架。
+      - source: "~/.jishushell/apps/${app_id}/files"
+        target: "/data/files"
+
+  # ────────────────────────────────────────────────────────────────
+  # 5) WeKnora 前端 UI（nginx + Vue dist）
+  #    ⚠️ 镜像不支持 BASE_URL 子路径 → 不走 panel /apps/weknora/* 反代，
+  #    用端口直连 18092。子路径要走需 fork 镜像（vite.config base + nginx
+  #    location prefix），暂列为后续工作。
+  # ────────────────────────────────────────────────────────────────
+  - name: ui
+    role: service
+    runtime: container
+    image: "wechatopenai/weknora-ui:latest"
+    # nginx entrypoint needs to mkdir /var/cache/nginx/client_temp and
+    # rewrite /etc/nginx/conf.d/default.conf via envsubst — both require root.
+    # Host uid breaks both steps and the container crashloops.
+    user: "0:0"
+    # nginx master spawns workers as uid 101 (nginx user) and chowns the
+    # cache dir to it — needs CHOWN to do so even when master is root.
+    cap_add: ["CHOWN", "SETGID", "SETUID"]
+    env:
+      MAX_FILE_SIZE_MB: "50"
+      APP_HOST: "host.docker.internal"
+      APP_PORT: "18096"
+      APP_SCHEME: "http"
+    resources:
+      cpu: "100m"
+      memory: "48Mi"
+    ports:
+      - name: http
+        # 18092 在 panel 18xxx 范围内（filebrowser 18088 / openclaw-gw 18790）。
+        # 避开 OpenWebUI 3000、SearXNG 8080、panel 8090。
+        port: 18092
+        container_port: 80
+        visibility: external
+    volumes:
+      # 覆盖镜像内的 nginx 模板：上游模板带 `add_header X-Frame-Options
+      # SAMEORIGIN`，panel 实例详情页 iframe (origin=panel:8090) 嵌
+      # WeKnora UI (origin=panel:18092) 会被浏览器拒绝。我们这份完全
+      # 照搬上游 location 块，只去掉 X-Frame-Options/CSP 限制，保留
+      # ${APP_HOST}/${APP_PORT}/${APP_SCHEME}/${MAX_FILE_SIZE} 由镜像
+      # docker-entrypoint.sh envsubst。
+      - source: "~/.jishushell/apps/${app_id}/nginx/default.conf.template"
+        target: "/etc/nginx/templates/default.conf.template"
+        readonly: true
+    health:
+      http:
+        path: /
+        port: 80
+      interval: "15s"
+      timeout: "5s"
+      retries: 6
+      start_period: "60s"   # 等 paradedb 初始化 + weknora-app boot + nginx 上线
+
+provides:
+  # ⚠️ Capability 命名特意避开 `web-<slug>` 和 `<slug>-ui` 这两种 panel 顶层
+  # `/apps/<slug>/*` 反代会命中的模式（详见 src/server.ts:69 resolveAppSlugUpstream）。
+  # 原因：panel 反代**不去掉** `/apps/<slug>` 前缀（server.ts:382 注释），原样
+  # 转发给上游；而 WeKnora 前端镜像的 nginx 只 listen `/`、vite build 也没设
+  # `base`——任何 `/apps/weknora/*` 请求到了 ui 容器都会 404。
+  #
+  # 因此用 `knowledge-weknora`（业务命名、非通配前缀），让它**只**进 capability
+  # registry 供未来 agent `requires:` 注入使用，**不**触发 panel 顶层反代。
+  # 用户访问 UI 走端口直连：http://<host>:18092/。
+  - capability: "knowledge-weknora"
+    task: "ui"
+    port: 18092
+    path: "/"
+    protocol: "http"
+    visibility: "external"
+    # 强制 iframe 走 panel 反代而不是端口直连。原因：
+    #   1. 用户从 panel 8090 同源加载详情页，corp 防火墙 / VPN / 混合内容
+    #      策略可能让 8090 通但 18092 不通（典型："refused to connect"）。
+    #   2. nginx SAMEORIGIN/CSP 即便去掉了，浏览器 Private Network Access
+    #      仍可能拒绝跨网段 iframe；走 panel 反代后 iframe src 与 panel
+    #      同源，绕开所有边界检查。
+    #   3. WeKnora 前端 vite build 没设 `base`，绝对路径 `/api/...` 直接
+    #      打到 panel API → 但反代会把 base 改成 /api/instances/.../provides/
+    #      /knowledge-weknora/，后续相对 fetch 正确（panel 反代有 base 重写）。
+    # Direct mode: iframe loads http://<host>:18092/ instead of the panel
+    # capability proxy. The proxy path approach kept tripping over WeKnora's
+    # axios 401 interceptor, which hard-codes `window.location.href = '/login'`
+    # and bounces the iframe to the panel root login page. Rewriting that
+    # literal at the proxy works for the assignment but the bundle has
+    # additional indirect navigations (vue-router fallback when pushState is
+    # blocked, internal pinia store actions) that aren't reachable from a
+    # text rewrite — same-origin iframe vs. direct iframe tradeoff favors
+    # direct here because the dev/internal browser already reaches 18092
+    # successfully (popout link confirmed working).
+    embedded: "direct"
+    description: "WeKnora 知识库 Web UI"
+
+lifecycle:
+  install:
+    # 镜像按尺寸升序下载：小的先稳，大的（docreader 1.7GB）放最后，
+    # 万一失败下次重试时小的全部 skip，从大的断点续。
+    - downloadImage: "redis:7.0-alpine"
+    - downloadImage: "wechatopenai/weknora-ui:latest"
+    - downloadImage: "wechatopenai/weknora-app:latest"
+    - downloadImage: "paradedb/paradedb:v0.22.2-pg17"
+    # docreader 单独给 30 分钟总超时 + 30 分钟 idle 超时（1.7GB 内含 400MB+ 的
+    # 大 layer；Pi 带宽 ~2 MB/s 下单 layer 下载耗时可超 panel 默认 180s idle
+    # → 误判 stalled。设 30 分钟 idle 给慢网充足时间）。
+    - downloadImage: "wechatopenai/weknora-docreader:latest"
+      timeout_ms: 1800000
+      idle_timeout_ms: 1800000
+
+    - mkdir: "~/.jishushell/apps/${app_id}/postgres"
+    - mkdir: "~/.jishushell/apps/${app_id}/redis"
+    - mkdir: "~/.jishushell/apps/${app_id}/docreader-tmp"
+    - mkdir: "~/.jishushell/apps/${app_id}/files"
+    - mkdir: "~/.jishushell/apps/${app_id}/nginx"
+    # 写自定义 nginx 模板（去掉 X-Frame-Options 让 panel 实例详情页能
+    # iframe 嵌入）。单引号 heredoc 关掉 shell 展开，保留 ${APP_HOST}/
+    # ${APP_PORT}/${APP_SCHEME}/${MAX_FILE_SIZE} 由镜像 envsubst 替换。
+    - run: |
+        set -e
+        TPL="$HOME/.jishushell/apps/${app_id}/nginx/default.conf.template"
+        cat > "$TPL" <<'NGX'
+        server {
+            listen 80;
+            server_name localhost;
+
+            client_max_body_size ${MAX_FILE_SIZE};
+
+            gzip on;
+            gzip_min_length 1024;
+            gzip_comp_level 6;
+            gzip_types text/plain text/css application/json application/javascript
+                       application/xml text/xml application/x-javascript;
+
+            # X-Frame-Options 故意不发：panel 实例详情页 (origin=panel:8090)
+            # 要 iframe 嵌入本服务 (origin=panel:18092)，原版 SAMEORIGIN
+            # 会被浏览器拒。其余安全头照旧。
+            add_header X-Content-Type-Options nosniff always;
+            add_header Referrer-Policy strict-origin-when-cross-origin always;
+
+            location /assets/ {
+                root /usr/share/nginx/html;
+                expires max;
+                add_header Cache-Control "public, max-age=31536000, immutable";
+            }
+
+            location = /files {
+                proxy_pass ${APP_SCHEME}://${APP_HOST}:${APP_PORT}/files;
+                proxy_http_version 1.1;
+                proxy_set_header Host $host;
+                proxy_set_header X-Real-IP $remote_addr;
+                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            }
+
+            location /api/ {
+                proxy_pass ${APP_SCHEME}://${APP_HOST}:${APP_PORT}/api/;
+                proxy_http_version 1.1;
+                proxy_set_header Host $host;
+                proxy_set_header X-Real-IP $remote_addr;
+                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+                proxy_set_header Connection "";
+                proxy_buffering off;
+                proxy_cache off;
+                proxy_read_timeout 3600s;
+                proxy_send_timeout 3600s;
+                proxy_connect_timeout 30s;
+                proxy_next_upstream error timeout http_502 http_503 http_504;
+                proxy_next_upstream_tries 3;
+            }
+
+            location / {
+                root /usr/share/nginx/html;
+                try_files $uri $uri/ /index.html;
+                add_header Cache-Control "no-cache, must-revalidate";
+            }
+        }
+        NGX
+        chmod 644 "$TPL"
+        echo "[install] wrote nginx template (no X-Frame-Options) → $TPL"
+
+  pre_start:
+    # 幂等：start/restart 都过这条路径，目录被误删可自愈。
+    - mkdir: "~/.jishushell/apps/${app_id}/postgres"
+    - mkdir: "~/.jishushell/apps/${app_id}/redis"
+    - mkdir: "~/.jishushell/apps/${app_id}/docreader-tmp"
+    - mkdir: "~/.jishushell/apps/${app_id}/files"
+    - mkdir: "~/.jishushell/apps/${app_id}/nginx"
+    - run: |
+        set -e
+        TPL="$HOME/.jishushell/apps/${app_id}/nginx/default.conf.template"
+        if [ ! -f "$TPL" ]; then
+          cat > "$TPL" <<'NGX'
+        server {
+            listen 80;
+            server_name localhost;
+            client_max_body_size ${MAX_FILE_SIZE};
+            gzip on;
+            gzip_min_length 1024;
+            gzip_comp_level 6;
+            gzip_types text/plain text/css application/json application/javascript
+                       application/xml text/xml application/x-javascript;
+            add_header X-Content-Type-Options nosniff always;
+            add_header Referrer-Policy strict-origin-when-cross-origin always;
+            location /assets/ {
+                root /usr/share/nginx/html;
+                expires max;
+                add_header Cache-Control "public, max-age=31536000, immutable";
+            }
+            location = /files {
+                proxy_pass ${APP_SCHEME}://${APP_HOST}:${APP_PORT}/files;
+                proxy_http_version 1.1;
+                proxy_set_header Host $host;
+                proxy_set_header X-Real-IP $remote_addr;
+                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            }
+            location /api/ {
+                proxy_pass ${APP_SCHEME}://${APP_HOST}:${APP_PORT}/api/;
+                proxy_http_version 1.1;
+                proxy_set_header Host $host;
+                proxy_set_header X-Real-IP $remote_addr;
+                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+                proxy_set_header Connection "";
+                proxy_buffering off;
+                proxy_cache off;
+                proxy_read_timeout 3600s;
+                proxy_send_timeout 3600s;
+                proxy_connect_timeout 30s;
+                proxy_next_upstream error timeout http_502 http_503 http_504;
+                proxy_next_upstream_tries 3;
+            }
+            location / {
+                root /usr/share/nginx/html;
+                try_files $uri $uri/ /index.html;
+                add_header Cache-Control "no-cache, must-revalidate";
+            }
+        }
+        NGX
+          chmod 644 "$TPL"
+        fi
+
+  uninstall:
+    - deleteImage: "wechatopenai/weknora-docreader:latest"
+    - deleteImage: "paradedb/paradedb:v0.22.2-pg17"
+    - deleteImage: "wechatopenai/weknora-app:latest"
+    - deleteImage: "wechatopenai/weknora-ui:latest"
+    - deleteImage: "redis:7.0-alpine"

package/dist/cli/app.js

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from "fs";
+import { basename, extname } from "path";
 import { stringify } from "yaml";
 import { parseFlag } from "./helpers.js";
 import { loadManagedListEntries, printManagedList } from "./managed-list.js";
@@ -328,6 +329,30 @@ function parseRemoteYamlUrl(value) {
         throw e;
     }
 }
+const BUILTIN_INSTALL_ALIASES = {
+    ollama: "ollama-binary.yaml",
+};
+async function loadBuiltinInstallYaml(source) {
+    const normalizedSource = source.trim();
+    if (!normalizedSource)
+        return null;
+    const { listBuiltinAppSpecs } = await import("../services/app/app-manager.js");
+    const templates = listBuiltinAppSpecs();
+    const normalizedWithoutExt = normalizedSource.replace(/\.ya?ml$/i, "");
+    const aliasTarget = BUILTIN_INSTALL_ALIASES[normalizedWithoutExt] ?? BUILTIN_INSTALL_ALIASES[normalizedSource];
+    const template = templates.find((entry) => {
+        if (aliasTarget && entry.fileName === aliasTarget)
+            return true;
+        if (entry.fileName === normalizedSource)
+            return true;
+        if (basename(entry.fileName, extname(entry.fileName)) === normalizedWithoutExt)
+            return true;
+        if (entry.id === normalizedWithoutExt || entry.id === normalizedSource)
+            return true;
+        return false;
+    });
+    return template?.yaml ?? null;
+}
 async function loadInstallYaml(source) {
     const remoteUrl = parseRemoteYamlUrl(source);
     if (remoteUrl) {
@@ -347,6 +372,10 @@ async function loadInstallYaml(source) {
         }
         return body;
     }
+    const builtinYaml = await loadBuiltinInstallYaml(source);
+    if (builtinYaml) {
+        return builtinYaml;
+    }
     if (!existsSync(source)) {
         throw new Error(`File not found: ${source}`);
     }
@@ -377,12 +406,41 @@ async function cmdShow(id) {
     }
     console.log(JSON.stringify(instance, null, 2));
 }
-async function cmdInstall(yamlPath, requestedAppId) {
-    const yamlText = await loadInstallYaml(yamlPath);
+async function cmdInstall(args) {
+    const installSource = args[0];
+    let requestedAppId;
+    for (let index = 1; index < args.length; index += 1) {
+        const value = args[index];
+        if (value === "--sudo-password") {
+            index += 1;
+            continue;
+        }
+        if (value.startsWith("--"))
+            continue;
+        requestedAppId = value;
+        break;
+    }
+    const yamlText = await loadInstallYaml(installSource);
     const { installApp } = await import("../services/app/app-manager.js");
-    const result = await installApp(yamlText, requestedAppId);
-    const installModeLabel = result.manifest.install_mode === "instance-dir" ? "instance" : "app";
-    log(c.green(`  ✓  Installed: ${result.manifest.id}  (${result.spec.name || ""} v${result.spec.version || "?"}, ${installModeLabel})`));
+    const sudoState = getCliSudoState(args);
+    while (true) {
+        try {
+            const installOptions = sudoState.password ? { exec: { sudoPassword: sudoState.password } } : undefined;
+            const result = installOptions
+                ? await installApp(yamlText, requestedAppId, installOptions)
+                : await installApp(yamlText, requestedAppId);
+            const installModeLabel = result.manifest.install_mode === "instance-dir" ? "instance" : "app";
+            log(c.green(`  ✓  Installed: ${result.manifest.id}  (${result.spec.name || ""} v${result.spec.version || "?"}, ${installModeLabel})`));
+            return;
+        }
+        catch (err) {
+            const message = err?.message || "Install failed";
+            if (isSudoPasswordError(message) && await promptForCliSudoPassword(sudoState)) {
+                continue;
+            }
+            throw err;
+        }
+    }
 }
 async function cmdProvides(args) {
     const { listProvidedCapabilities } = await import("../services/app/app-manager.js");
@@ -504,16 +562,26 @@ async function cmdUninstallAll(args = []) {
     }
 }
 async function cmdCreateInstance(appId, instanceId, name) {
-    const { getApp, installApp, resolveRequires, updateInstance } = await import("../services/app/app-manager.js");
+    const { getApp, installApp, updateInstance } = await import("../services/app/app-manager.js");
+    const { resolveConnections, resolvedToLegacyEnv } = await import("../services/connection-resolver.js");
     const appData = getApp(appId);
     if (!appData) {
         log(c.red(`  ✗  App "${appId}" not found.`));
         process.exitCode = 1;
         return;
     }
+    // PR 3 sub-step 3e: switch CLI to resolveConnections (preCreate). Pending
+    // requires are printed so the user can see what still needs binding.
     let resolvedEnv = {};
     try {
-        resolvedEnv = resolveRequires(appData.spec);
+        const { resolved, pending } = resolveConnections(appData.spec, { connections: {} }, "preCreate");
+        resolvedEnv = resolvedToLegacyEnv(resolved);
+        if (pending.length > 0) {
+            log(c.yellow(`  ⚠  ${pending.length} pending connection(s):`));
+            for (const p of pending) {
+                log(c.yellow(`     - ${p.slot} (${p.capability}): ${p.reason}`));
+            }
+        }
     }
     catch (e) {
         log(c.red(`  ✗  ${e.message}`));
@@ -705,7 +773,7 @@ export async function run(rest) {
             await cmdShow(rest[1]);
         }
         else if (appCmd === "install" && rest[1]) {
-            await cmdInstall(rest[1], rest[2]);
+            await cmdInstall(rest.slice(1));
         }
         else if (appCmd === "uninstall" && rest[1] === "--all") {
             await cmdUninstallAll(rest.slice(2));
@@ -781,7 +849,8 @@ Commands:
   list [--json]                                     列出统一受管列表（apps 下已安装应用 + instances 下遗留实例）
   provides [--json]                                 列出已安装 App 声明/注册的能力
   show <id>                                         查看 App 或实例详情（JSON）
-  install <yaml-file|https-url> [app-id]            从本地或 HTTPS YAML 安装 App，可选指定安装 id
+  install <yaml-file|https-url|builtin-id> [app-id] [--sudo-password <password>]
+                                                    从本地、HTTPS 或内置模板安装 App，可选指定安装 id
   uninstall <app-id> [--sudo-password <password>]   卸载单个 App 或实例（停止 + 删除目录）
   uninstall --all [--sudo-password <password>]      卸载全部 App 与实例
   create-instance <app-id> <inst-id> [name]         从 App 创建实例（Agent 通道由 spec.agentType 决定）
@@ -798,6 +867,7 @@ Examples:
   jishushell app install ./apps/ollama-with-hollama-binary.yaml
   jishushell app install ./apps/ollama-with-hollama-binary.yaml ollama-local
   jishushell app install https://example.com/apps/ollama-with-hollama-binary.yaml
+  jishushell app install ollama
   jishushell app list
   jishushell app provides
   jishushell app copy ollama-1