SuperAPI AI Directory

pi-setup

General & other

View repository

Updated 10-16 08:49

About this skill

Pi Setup

Help users configure Pi Agent from scratch, pairing DeepSeek V4 (built-in) + Ant-Ling Ring-2.6-1T (single-model custom provider) + ZenMux (multi-model aggregation provider, including Gemini 3.5 Flash, inclusionAI Ling-3.0-flash, Claude, GPT, etc.), install a curated set of extensions, and automatically avoid 12 known pitfalls.

User-input parameters: $ARGUMENTS

Core Principles

  1. Detection First: At each step, first probe the current state (whether pi is already installed, whether the config already exists, which shell file the key is in), then decide the action. Never blindly overwrite the user's existing config—if found to already exist, show the user a diff and ask whether to overwrite.
  2. No Plaintext Keys: In the pi config, only put !shell命令 lazy read, keep the key in the user's original file (~/.deepseek, shell rc, etc.).
  3. Interactively Confirm Key Choices: Use AskUserQuestion to collect decisions such as "which models to enable", and do not make the call for the user.
  4. Environment Variables Rely on Detection Reminders: Do not assume it is ~/.zshrc, scan all candidate files + the current process environment, and give targeted reminders based on the actual situation.

Workflow

1. Detect Current State

Run these probes in parallel and summarize them into a "current state table":

which pi && pi --version                       # pi 是否已装、版本
ls -la ~/.pi/agent/ 2>/dev/null                # 现有配置文件
cat ~/.pi/agent/settings.json 2>/dev/null      # 现有 settings(packages/默认模型)
cat ~/.pi/agent/models.json 2>/dev/null        # 现有自定义 provider
echo $SHELL                                    # 用户默认 shell
ls -la ~/.zenmux ~/.config/zenmux 2>/dev/null  # ZenMux 密钥文件候选

Organize "installed/not installed, which configs already exist, default shell, whether the ZenMux key file exists" for the user, then continue.

2. Environment Variable Detection (not limited to ~/.zshrc)

This is the focus of this skill. Do not assume the key is in ~/.zshrc. Probe each required variable in the following order (DEEPSEEK_API_KEY、LING_API_KEY、ZENMUX_API_KEY, as well as any additional ones the user wants):

# a) 当前进程环境(最权威——说明已 export 且生效)
printenv DEEPSEEK_API_KEY >/dev/null && echo "DEEPSEEK_API_KEY: in live env"
printenv LING_API_KEY     >/dev/null && echo "LING_API_KEY: in live env"
printenv ZENMUX_API_KEY   >/dev/null && echo "ZENMUX_API_KEY: in live env"

# b) 独立密钥文件
[ -f ~/.deepseek ] && grep -l DEEPSEEK_API_KEY ~/.deepseek 2>/dev/null
for f in ~/.zenmux ~/.config/zenmux/key ~/.config/zenmux/api_key; do
  [ -f "$f" ] && grep -lE '^(ZENMUX_)?API_KEY=' "$f" 2>/dev/null
done

# c) 扫所有常见 shell 启动文件 + 是否带 export
for f in ~/.zshrc ~/.zshenv ~/.zprofile ~/.bashrc ~/.bash_profile ~/.profile ~/.config/fish/config.fish ~/.deepseek ~/.zenmux; do
  [ -f "$f" ] && grep -nE 'DEEPSEEK_API_KEY|LING_API_KEY|ZENMUX_API_KEY|^API_KEY=' "$f" 2>/dev/null | sed "s|^|$f:|"
done

Two common formats for ZenMux key files:

  • ~/.zenmux(or ~/.config/zenmux/key) standalone file, containing API_KEY=sk-... or ZENMUX_API_KEY=sk-...
  • Environment Variable ZENMUX_API_KEY exported in shell rc

Give reminders by case based on the detection result (write into the final report):

Detection Result Reminder Action
Variable in live env ✅ Can be used directly apiKey: "VAR_NAME"(simplest)
In some rc file and has export ✅ Takes effect in a new shell; tell the specific file
In some rc file butno export(Pitfall 1) ⚠️ Subprocesses cannot read it, use !{shell} -ic 'echo $VAR' lazy read, or suggest adding export
In a standalone file (such as ~/.deepseek) ✅ Use !awk / !grep to extract from that file
Not found at all ❗ Clearly tell the user which variable to add to which file (using the rc corresponding to their default shell), and give a pasteable line

shell rc selection is derived from $SHELL : zsh→~/.zshrc,bash→~/.bashrc(interactive)/~/.bash_profile(login), fish→~/.config/fish/config.fish。

3. AskUserQuestion — Collect Key Decisions

Use AskUserQuestion to ask the following questions all at once (merge into one call if possible).AskUserQuestion allows at most 4 options per question, and Q1 has already hit the limit, so ZenMux is added as a single bundled option (enabling both the paid + free Gemini models at the same time).

Q1 — Which models to enable(multiSelect: true, guide users to select all)

  • deepseek-v4-pro(DeepSeek V4 Pro, 1M ctx, built-in)
  • deepseek-v4-flash(DeepSeek V4 Flash, 1M ctx, built-in, cheap)
  • ant-ling/Ring-2.6-1T(Ant Ring 2.6 1T, 256K ctx, custom)
  • zenmux/google/gemini-3.5-flash(ZenMux aggregation, Google GA on May 19, strong agentic;will simultaneously enable -free limited-free version and inclusionai/ling-3.0-flash(124B MoE / 5.1B active, 262K ctx, non-reasoning model, cheap and high-volume, suitable as a cheap execution model)—the three models share the same provider block, do not occupy extra Q&A slots; cross-vendor comparisons of Claude/GPT also go through this provider, after setup just append it to models.json)
  • in the question text, write "by default it is recommended to select all—they all go into the Ctrl+P cycle list and do not occupy extra context"

Q2 — Default model(single choice, options come from those already selected in Q1)

  • determines settings.json 's defaultProvider / defaultModel

Q3 — Default thinking level(single choice)

  • xhigh(strongest reasoning, Ring burns more tokens but high quality) / high(Gemini 3.5 Flash default recommended level) / medium(general) / off
  • Note: this is a global value, mapping differs across models (DeepSeek's minimal/low/medium are unsupported and will be clamped; Gemini's xhigh maps back to high in thinkingLevelMap; Ling-3.0-flash is anon-reasoning model, if it is chosen as the default model then defaultThinkingLevel directly write "off")

Q4 — Extension set(single choice)

  • Full 22 (features 8 + TUI 9 + behavior 5, about 7.7k tokens) / Core only (mcp-adapter, web-access, subagents, fff, context-prune) / Skip extensions

Only ask these; do not follow up with meta-questions like skill type—the parameters are already clear.

4. Write configuration files

Generate according to the user's choices.All JSON templates are in references/config-templates.md,strictly copy verbatim(especially compat.supportsDeveloperRole: false and thinkingLevelMap, this is the fix for pitfalls 2/3).

Before writing, if the file already exists: read it out and diff it to the user, overwrite only after confirmation.

  • ~/.pi/agent/auth.json → DeepSeek key(!awk from ~/.deepseek or the detected location lazily read),chmod 600
  • ~/.pi/agent/models.json → write all custom providers selected by the user into providers:
    • Ring selected → ant-ling provider block
    • ZenMux selected → zenmux provider block (by default simultaneously includes google/gemini-3.5-flash + google/gemini-3.5-flash-free + inclusionai/ling-3.0-flash three models, apiKey uses !awk lazily read from the detected ZenMux key file;note pitfall 9: for custom providers, apiKey writing a bare environment variable name will cause 403, you must use !shell the lazy-read form)
    • both selected → write both providers into the same providers object (merge, do not overwrite each other)
  • ~/.pi/agent/settings.json → defaultProvider/Model, defaultThinkingLevel, enabledModels (those selected by the user in Q1; ZenMux models in enabledModels use zenmux/google/gemini-3.5-flash form)
  • DeepSeek do not write models.json(built-in, manual configuration is harmful—see pitfall 7)
  • Models other than ZenMux Gemini (Claude / GPT, etc.)are not automatically written within the skill's default scope—will tell the user in the final report "just append to the zenmux.models array, see model IDs in https://zenmux.ai",避免硬编码不存在或已过期的 model ID

5. Install extensions

Select by Q4 pi install. See the command list in references/config-templates.md 's "Extension Installation" section. Globally skip pi-autoresearch、@vanillagreen/pi-extension-manager、@vanillagreen/pi-session-manager。

6. Fix extension shortcut conflicts (Pitfall 6)

When @plannotator/pi-extension + @marckrenn/pi-sub-bar is installed, write ~/.pi/agent/pi-sub-bar-settings.json to change cycleProvider to ctrl+alt+s(template in references).

7. Verification

cat ~/.pi/agent/models.json | python3 -m json.tool >/dev/null && echo "models.json valid"
pi --list-models | grep -iE 'Ring|deepseek-v4|gemini|ling-3'
cd /tmp && pi --provider <默认provider> --model <默认model> -p "say pong" --no-extensions
pi -p "say hi" 2>&1 | grep -i conflict   # 无输出 = 快捷键冲突已解

If ZenMux Gemini was selected in Q1, additionally verify the endpoint once with curl (to avoid interference from Pi's own extension loading):

KEY=$(awk -F= '/^(ZENMUX_)?API_KEY=/{print $2; exit}' ~/.zenmux 2>/dev/null \
       || printenv ZENMUX_API_KEY)
curl -s -X POST https://zenmux.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-3.5-flash-free","messages":[{"role":"user","content":"reply pong"}],"max_tokens":2048,"reasoning_effort":"low"}' \
  | python3 -c "import json,sys; r=json.load(sys.stdin); print('  content:', r['choices'][0]['message'].get('content','')[:80] or '(empty)')"

Non-empty output = ZenMux reachable, key valid, reasoning_effort passed through correctly. Empty content + finish_reason:length is most likely because max_tokens was set too small (Gemini 3.5 Flash reasons first by default, must be ≥2K).

For Ling-3.0-flash, run one more end-to-end smoke test (non-reasoning model, no reasoning_effort needed):

cd /tmp && pi --provider zenmux --model inclusionai/ling-3.0-flash -p "reply with exactly: PONG" --no-extensions

If any step 400 Invalid Request Messages、403 access_denied, truncation, or other anomaly occurs,first check references/troubleshooting.md(12 pitfalls: symptom→reproduction→root cause→solution), use curl probes to bisect and locate, then act.

For long code generation tasks, if there is zero output and zero files for over 3 minutes (no text, no tool call), handle perPitfall 11 : kill it directly, add the instruction "do not write code in thinking, directly call the write tool to save to disk" to the prompt, lower the thinking level, and rerun. All background/automated pi -p calls must </dev/null(Pitfall 12)。

Output

After completion, give the user a report: current-state detection results, environment variable reminders (per the table in §2), final list of generated files, the user's model/thinking choices, verification results, and a daily-use quick reference (Ctrl+L to switch models / Shift+Tab to switch thinking / Ctrl+P to cycle).

Config files go directly into ~/.pi/agent/, not to Downloads.