@qodercn-ai/qoderclicn 0.1.0

package/bundle/builtin/hook-config/SKILL.md

@@ -0,0 +1,480 @@
+---
+name: hook-config
+description:
+  Guide for creating and configuring hooks. Use when users want to add
+  automated behaviors triggered by tool execution, session lifecycle,
+  or other events in the Qoder CLI hook system.
+allowed-tools: Edit, Write
+---
+
+# Creating Hooks for Qoder CLI
+
+This skill guides you through creating hooks — automated behaviors that
+trigger on specific events like tool execution, session lifecycle, file
+changes, and notifications. Hooks are configured in settings.json files.
+
+## When to Use Hooks
+
+Use hooks when you need:
+
+- **Automated side effects** after tool execution (format, lint, test)
+- **Guardrails** before tool execution (block protected files, detect secrets)
+- **Notifications** when events occur (desktop alerts, webhooks)
+- **Validation gates** that block or allow operations based on conditions
+- **Session automation** at start, end, or compaction
+
+**When NOT to use hooks:**
+
+- One-off tasks (just do them directly)
+- Complex multi-step workflows (use agents or skills instead)
+- Anything that needs user interaction mid-execution
+
+## Configuration Scopes
+
+| Scope       | File                                 | Use Case                         |
+| ----------- | ------------------------------------ | -------------------------------- |
+| **Project** | `${QODER_CONFIG_DIR}/settings.json`         | Team-shared, version controlled  |
+| **Local**   | `${QODER_CONFIG_DIR}/settings.local.json`   | Personal, not committed          |
+| **User**    | `~/${QODER_CONFIG_DIR}/settings.json`       | Global across all projects       |
+
+**Choose project** for team guardrails and standards.
+**Choose local** for personal preferences and notifications.
+**Choose user** for global behaviors across all projects.
+
+## Configuration Format
+
+```jsonc
+{
+  "hooks": {
+    "<EventName>": [
+      {
+        "matcher": "<regex>",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${QODER_CONFIG_DIR}/hooks/my-hook.sh",
+            "name": "my-hook",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Each event maps to an array of **hook definitions**. Each definition has:
+
+| Field        | Required | Description                                         |
+| ------------ | -------- | --------------------------------------------------- |
+| `matcher`    | No       | Regex filter (matches tool name for tool events)    |
+| `hooks`      | Yes      | Array of hook handlers                              |
+| `sequential` | No       | Run hooks in order instead of parallel              |
+| `async`      | No       | Fire-and-forget, don't block the operation          |
+
+### Hook Handler Fields
+
+| Field           | Required     | Description                                           |
+| --------------- | ------------ | ----------------------------------------------------- |
+| `type`          | Yes          | `command`, `http`, `prompt`, or `agent`                |
+| `command`       | command type | Shell command to execute                               |
+| `url`           | http type    | Webhook URL to POST to                                 |
+| `prompt`        | prompt/agent | LLM prompt text                                        |
+| `if`            | No           | Per-hook condition: `"ToolName(glob)"` or `"ToolName"` |
+| `name`          | No           | Display name                                           |
+| `description`   | No           | Human-readable description                             |
+| `timeout`       | No           | Seconds before timeout                                 |
+| `statusMessage` | No           | Text shown in UI during execution                      |
+| `async`         | No           | Run in background without blocking                     |
+| `asyncRewake`   | No           | Background hook; exit code 2 wakes model               |
+
+## Hook Events
+
+### Tool Events (matcher = tool name regex)
+
+| Event                | When                            |
+| -------------------- | ------------------------------- |
+| `PreToolUse`         | Before tool execution           |
+| `PostToolUse`        | After successful tool execution |
+| `PostToolUseFailure` | After tool execution fails      |
+| `PermissionRequest`  | Tool requests user permission   |
+
+### Session & Agent Lifecycle
+
+| Event           | When                                 |
+| --------------- | ------------------------------------ |
+| `SessionStart`  | Session initializes                  |
+| `SessionEnd`    | Session tears down                   |
+| `SubagentStart` | Sub-agent session begins             |
+| `SubagentStop`  | Sub-agent session ends               |
+| `Stop`          | Agent decides to stop                |
+| `StopFailure`   | Stop process fails (error, timeout)  |
+| `PreCompact`    | Before context compaction            |
+| `PostCompact`   | After context compaction             |
+
+### User, Config & Notification Events
+
+| Event                | When                            |
+| -------------------- | ------------------------------- |
+| `UserPromptSubmit`   | User submits a prompt           |
+| `ConfigChange`       | Settings change at runtime      |
+| `Notification`       | External notification arrives   |
+| `InstructionsLoaded` | System instructions loaded      |
+
+### File & Workspace Events
+
+| Event            | When                       |
+| ---------------- | -------------------------- |
+| `CwdChanged`     | Working directory changes  |
+| `FileChanged`    | Watched file changes       |
+| `WorktreeCreate` | Git worktree created       |
+| `WorktreeRemove` | Git worktree removed       |
+
+### Task Events
+
+| Event           | When                          |
+| --------------- | ----------------------------- |
+| `TaskCreated`   | Background task created       |
+| `TaskCompleted` | Background task completes     |
+
+## Handler Types
+
+### Command (`type: "command"`)
+
+Executes a shell command. Hook input arrives as JSON on **stdin**.
+Output is parsed from **stdout** as JSON.
+
+**Exit code semantics:**
+
+| Exit Code | Meaning                          |
+| --------- | -------------------------------- |
+| 0         | Success — parse stdout as JSON   |
+| 2         | Blocking deny — stderr is reason |
+| Other     | Non-blocking warning             |
+
+**Stdin** receives the full hook input as JSON (fields vary by event):
+
+```json
+{
+  "session_id": "abc-123",
+  "cwd": "/path/to/project",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Edit",
+  "tool_input": { "file_path": "src/app.ts", "old_string": "...", "new_string": "..." }
+}
+```
+
+**Stdout** JSON output (all fields optional):
+
+```json
+{
+  "decision": "allow",
+  "reason": "Checks passed",
+  "hookSpecificOutput": {
+    "additionalContext": "Message injected into conversation"
+  }
+}
+```
+
+Best for: scripts, linters, formatters, external CLI tools.
+
+### HTTP (`type: "http"`)
+
+POSTs hook input as JSON to the URL. Response parsed as JSON hook
+output. Headers support `${ENV_VAR}` interpolation.
+
+```jsonc
+{
+  "type": "http",
+  "url": "https://api.example.com/hooks",
+  "headers": { "Authorization": "Bearer ${API_TOKEN}" }
+}
+```
+
+Best for: webhooks, external integrations, CI/CD triggers.
+
+### Prompt (`type: "prompt"`)
+
+Single-turn LLM evaluation. The prompt plus hook input go to the model,
+which returns a structured JSON decision.
+
+```jsonc
+{
+  "type": "prompt",
+  "prompt": "Review this edit for security issues. Return {\"decision\": \"allow\"} or {\"decision\": \"deny\", \"reason\": \"...\"}"
+}
+```
+
+Best for: AI-powered review gates, semantic validation.
+
+### Agent (`type: "agent"`)
+
+Spawns a sub-agent with tool access.
+
+```jsonc
+{
+  "type": "agent",
+  "prompt": "Verify the edited file passes type checking. $ARGUMENTS",
+  "tools": ["Bash", "Read"],
+  "maxTurns": 10,
+  "timeout": 120
+}
+```
+
+Best for: complex verification needing tool use (run tests, read files,
+check types).
+
+## The `if` Condition
+
+Narrow when a hook fires within a matched definition:
+
+```jsonc
+{ "if": "Edit(*.ts)" }       // Only Edit calls on .ts files
+{ "if": "Write(src/**)" }    // Only Write calls under src/
+{ "if": "Bash" }             // Any Bash call
+```
+
+Format: `"ToolName(glob_pattern)"` or `"ToolName"`.
+The glob matches the tool's primary argument (typically a file path).
+
+## Hook Creation Workflow
+
+### Step 1: Determine the Behavior
+
+Understand what the user wants:
+
+- What should happen automatically?
+- When should it trigger? (before/after tool use, session event, etc.)
+- Should it block operations or just observe?
+- Who needs it? (team or personal)
+
+**Avoid interrogation loops.** Propose a concrete hook config based on
+initial understanding and ask the user to refine.
+
+### Step 2: Choose Event, Matcher, and Handler
+
+Map the behavior:
+
+| Behavior               | Event         | Matcher        | Handler |
+| ---------------------- | ------------- | -------------- | ------- |
+| Auto-format after edits| `PostToolUse` | `Edit\|Write`  | command |
+| Block protected files  | `PreToolUse`  | `Edit\|Write`  | command |
+| Secret detection       | `PreToolUse`  | `Edit\|Write`  | command |
+| Desktop notifications  | `Notification`| —              | command |
+| Run tests after changes| `PostToolUse` | `Edit\|Write`  | command |
+| AI code review gate    | `PreToolUse`  | `Edit`         | prompt  |
+| Type-check verification| `PostToolUse` | `Edit\|Write`  | agent   |
+| Webhook to CI/CD       | `PostToolUse` | `Edit\|Write`  | http    |
+| Dependency guard       | `PreToolUse`  | `Edit`         | command |
+
+### Step 3: Choose Scope
+
+- **Project** (`${QODER_CONFIG_DIR}/settings.json`): Team standards, check in
+- **Local** (`${QODER_CONFIG_DIR}/settings.local.json`): Personal, not committed
+- **User** (`~/${QODER_CONFIG_DIR}/settings.json`): Global, all projects
+
+### Step 4: Create the Configuration
+
+1. Read the target settings.json (if it exists)
+2. Merge the new hook into the existing `hooks` object
+3. Write back the file
+
+If no hooks exist yet, create the full structure.
+
+### Step 5: Create Script Files (command type)
+
+For command hooks with non-trivial logic, create scripts in
+`${QODER_CONFIG_DIR}/hooks/`:
+
+```bash
+mkdir -p ${QODER_CONFIG_DIR}/hooks
+```
+
+Script requirements:
+- Read JSON from stdin
+- Write JSON to stdout (or nothing for simple success)
+- Exit 0 for success, 2 for blocking deny, other for warning
+- Use stderr for error messages and debug output
+- Make executable: `chmod +x ${QODER_CONFIG_DIR}/hooks/my-hook.sh`
+
+Test independently:
+
+```bash
+echo '{"tool_name":"Edit","tool_input":{"file_path":"test.ts"}}' | \
+  ${QODER_CONFIG_DIR}/hooks/my-hook.sh
+```
+
+### Step 6: Verify
+
+Tell the user to verify:
+
+1. Restart the session or trigger the relevant event
+2. Check the hook fires and produces expected output
+3. Test the blocking path (for PreToolUse guards)
+4. Confirm `async` hooks don't block the session
+
+## Best Practices
+
+1. **Keep hooks fast** — Target <5s for synchronous hooks
+2. **Test scripts independently** — Pipe sample JSON stdin, verify output
+3. **Use `async: true`** for non-blocking side effects (notifications, logging)
+4. **Scope matchers narrowly** — Don't fire on every tool invocation
+5. **Prefer `if` conditions** for file-type filtering
+6. **Log to stderr** — stdout is parsed as JSON; debug output goes to stderr
+7. **Handle edge cases** — Exit 0 if the condition doesn't apply
+8. **Use `statusMessage`** for meaningful UI feedback during execution
+
+## Anti-Patterns to Avoid
+
+- **Overly broad matchers** — `".*"` on PreToolUse fires on every single tool call
+- **Long synchronous hooks** — Block the entire interactive session
+- **Stdout pollution** — Non-JSON stdout causes parse errors
+- **Missing shebang** — Scripts without `#!/bin/bash` may fail silently
+
+## Examples
+
+### Auto-Format TypeScript
+
+Runs Prettier on TypeScript files after every Edit or Write.
+
+**`${QODER_CONFIG_DIR}/settings.json`:**
+
+```jsonc
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [{
+        "type": "command",
+        "command": "${QODER_CONFIG_DIR}/hooks/auto-format.sh",
+        "if": "Edit(*.{ts,tsx,js,jsx})",
+        "name": "auto-format",
+        "statusMessage": "Formatting..."
+      }]
+    }]
+  }
+}
+```
+
+**`${QODER_CONFIG_DIR}/hooks/auto-format.sh`:**
+
+```bash
+#!/bin/bash
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+[ -z "$FILE" ] && exit 0
+[ -f "$FILE" ] || exit 0
+npx prettier --write "$FILE" >/dev/null 2>&1
+exit 0
+```
+
+### Protected File Guard
+
+Blocks edits to lock files and CI configuration.
+
+**`${QODER_CONFIG_DIR}/settings.json`:**
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [{
+        "type": "command",
+        "command": "${QODER_CONFIG_DIR}/hooks/protected-files.sh",
+        "name": "protected-file-guard",
+        "statusMessage": "Checking file permissions..."
+      }]
+    }]
+  }
+}
+```
+
+**`${QODER_CONFIG_DIR}/hooks/protected-files.sh`:**
+
+```bash
+#!/bin/bash
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+[ -z "$FILE" ] && exit 0
+
+PROTECTED_PATTERNS=(
+  "package-lock.json"
+  "yarn.lock"
+  "pnpm-lock.yaml"
+  ".github/workflows/*"
+  ".gitlab-ci.yml"
+)
+
+for PATTERN in "${PROTECTED_PATTERNS[@]}"; do
+  if [[ "$FILE" == $PATTERN ]]; then
+    echo "Blocked: $FILE is a protected file" >&2
+    exit 2
+  fi
+done
+
+exit 0
+```
+
+### Desktop Notification
+
+Sends a macOS notification when Qoder CLI needs attention.
+
+**`${QODER_CONFIG_DIR}/settings.local.json`:**
+
+```jsonc
+{
+  "hooks": {
+    "Notification": [{
+      "hooks": [{
+        "type": "command",
+        "command": "${QODER_CONFIG_DIR}/hooks/notify.sh",
+        "name": "desktop-notify",
+        "async": true
+      }]
+    }]
+  }
+}
+```
+
+**`${QODER_CONFIG_DIR}/hooks/notify.sh`:**
+
+```bash
+#!/bin/bash
+INPUT=$(cat)
+TITLE=$(echo "$INPUT" | jq -r '.title // "Qoder CLI"')
+MSG=$(echo "$INPUT" | jq -r '.message // "Notification"')
+
+if command -v osascript &>/dev/null; then
+  osascript -e "display notification \"$MSG\" with title \"$TITLE\""
+elif command -v notify-send &>/dev/null; then
+  notify-send "$TITLE" "$MSG"
+fi
+exit 0
+```
+
+### Type-Check Gate
+
+Uses an agent to verify TypeScript compiles after edits.
+
+**`${QODER_CONFIG_DIR}/settings.json`:**
+
+```jsonc
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [{
+        "type": "agent",
+        "prompt": "Run `npx tsc --noEmit` and check for type errors in the edited file. If there are errors, report them. $ARGUMENTS",
+        "tools": ["Bash", "Read"],
+        "if": "Edit(*.{ts,tsx})",
+        "name": "type-check",
+        "statusMessage": "Type checking...",
+        "maxTurns": 5,
+        "timeout": 60
+      }]
+    }]
+  }
+}
+```

package/bundle/builtin/mcp-config/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: mcp-config
+description: Interactively add, update, or remove MCP (Model Context Protocol) servers in QoderCLI config files. Use this skill whenever the user pastes an MCP server config snippet, asks to "add an MCP", "配置 MCP", "install this MCP server", "register an MCP", wants to move an MCP between project/user/local scope, or asks why a newly pasted MCP isn't showing up. Handles stdio, http, sse, and ws transports, merges safely into the right target file (`<repo>/.qoder/settings.json`, `~/.qoder/settings.json`, or `<repo>/.qoder/settings.local.json`), and tells the user exactly how to reload so the server actually connects.
+allowed-tools: Bash, Edit, Read, Write
+---
+
+# MCP Config Helper (QoderCLI)
+
+Help the user land an MCP server config into the right QoderCLI config file, merge it cleanly with what's already there, and reload it so it actually takes effect.
+
+## When this skill fires
+
+Typical user inputs:
+
+- Pastes a JSON blob that looks like an MCP server definition (has `command`, `args`, or `url` + `type`)
+- "帮我把这个 MCP 加到项目里"
+- "Add this MCP server to user scope"
+- "Why isn't my new MCP showing up in `/mcp`?"
+- "Move the filesystem MCP from project to user scope"
+- "Remove the old foo MCP"
+
+If the user's request doesn't involve MCP server registration, don't invoke this skill.
+
+## Prefer the built-in CLI when possible
+
+QoderCLI ships first-class commands for MCP CRUD:
+
+- `qodercli mcp add <name> <commandOrUrl> [args...] --scope <user|local|project> --transport <stdio|sse|http|ws>`
+- `qodercli mcp add-json <name> <json> --scope <user|local|project>` — ideal when the user pasted a full server body, just wrap it and pass through.
+- `qodercli mcp list`, `qodercli mcp get <name>`, `qodercli mcp remove <name> --scope ...`
+
+If the user's ask maps cleanly onto one of these, run the command via Bash instead of hand-editing JSON — the CLI handles collision detection, OAuth setup, scope validation, and writes to the right file. Fall back to direct file editing only when: (a) the user is doing a cross-scope move (read from one, write to another), (b) the user wants a surgical edit to an env var or header on an existing entry, or (c) the CLI rejects the input and you need to diagnose why.
+
+## What the user pastes
+
+MCP configs come in several shapes. Normalize them before writing. Common inputs:
+
+**Full server block (most common — from docs/README):**
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
+    }
+  }
+}
+```
+
+**Single server entry (name + body):**
+```json
+"filesystem": {
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
+}
+```
+
+**Just the body (user will supply the name):**
+```json
+{ "command": "npx", "args": ["-y", "..."] }
+```
+
+**HTTP / SSE transport:**
+```json
+{
+  "type": "http",
+  "url": "https://example.com/mcp",
+  "headers": { "Authorization": "Bearer ..." }
+}
+```
+
+If the name is missing from the snippet, ask the user what to call the server. Don't invent one.
+
+## Target files (scopes)
+
+QoderCLI supports three MCP scopes. Pick the right file — the difference matters:
+
+| Scope     | File                                       | `mcpServers` lives at          | When to use                                                           |
+| --------- | ------------------------------------------ | ------------------------------ | --------------------------------------------------------------------- |
+| `project` | `<repo>/.qoder/settings.json`              | top-level `mcpServers`         | Shared with the team via git. Use for project-wide, committed config. |
+| `user`    | `~/.qoder/settings.json`                   | top-level `mcpServers`         | Available across all projects for this user. Use for personal tools. |
+| `local`   | `<repo>/.qoder/settings.local.json`        | top-level `mcpServers`         | Project-specific, user-only, **gitignored**. This is the CLI default. |
+
+**Do NOT write to any of these — they are wrong targets that look plausible but the CLI does not read:**
+- `<repo>/.mcp.json` or `~/.mcp.json` (Claude Code convention, not QoderCLI)
+- `~/.qoder/mcp.json` (no such file — user MCPs go inside `~/.qoder/settings.json` under `mcpServers`)
+- `~/Library/Application Support/Qoder/User/mcp.json` or any VS Code extension path
+- `~/.claude.json` or `~/.claude/settings.json` (those are Claude Code, not QoderCLI)
+
+The only three valid targets are the three rows in the table above. If you find yourself about to write somewhere else, stop.
+
+**Scope selection — don't default silently.** If the user hasn't specified a scope, ask before writing. A one-liner is enough: "Add this to **project** (`<repo>/.qoder/settings.json`, committed), **user** (`~/.qoder/settings.json`, global), or **local** (`<repo>/.qoder/settings.local.json`, gitignored)?"
+
+Don't guess "probably local scope just because it's the CLI default" — the difference between project (checked into git, teammates see it) and user/local (personal) is significant, and picking wrong can leak secrets or clutter a teammate's config. Users routinely paste MCP configs from docs that don't mention scope; they need the prompt.
+
+Exception: proceed without asking only when phrasing makes it genuinely unambiguous — "add to this project", "push this to the team", "only for me globally", "just for this repo". Vague signals like "装一下" / "加进去" do not qualify.
+
+## Workflow
+
+1. **Parse the pasted config.** Extract: server name, transport (`stdio` if `command` present, else `http`/`sse`/`ws` based on `type`/`url`), and the server body. Normalize so the write step only deals with a clean `(name, body)` pair.
+
+2. **Confirm scope** if not obvious from the user's message (see table above).
+
+3. **Decide: CLI or direct edit?** For a plain add with a clean body, `qodercli mcp add-json <name> '<json>' --scope <scope>` is the shortest path and handles collision errors for you. For cross-scope moves, surgical field edits, or removals from multiple scopes at once, go direct.
+
+4. **If direct-editing, read the target file.** Use the Read tool. If the file doesn't exist, plan to create it with `{ "mcpServers": { ... } }`. If it exists, add/update a top-level `mcpServers` key and preserve every other setting already in the file.
+
+5. **Detect collisions — but don't be precious.** Two sub-cases:
+   - **User explicitly asked to update/replace/move an existing entry** (e.g. "把 filesystem 路径改成...", "update the github token", "replace example-api"): just do it. Don't ask for reconfirmation. A one-line "found existing filesystem at /old/path → updating to /new/path" is plenty; the user already decided.
+   - **User pasted a new config that happens to collide** (no mention of the existing entry, likely unaware it's there): stop and show them the existing entry vs. the new one, ask replace/rename/cancel. Silent overwrite here loses hand-edited fields (env vars, auth headers) and surprises the user.
+
+   The distinguishing signal: did the user's wording acknowledge that the server already exists? If yes, proceed. If no and there's a collision, surface it. Note that `qodercli mcp add`/`add-json` *refuses* to overwrite by default — if the user wants a replace, either remove-then-add via CLI, or fall back to a direct Edit.
+
+6. **Merge and write.** For direct edits, use the Edit tool for surgical changes when the file exists (especially `~/.qoder/settings.json`, which holds unrelated settings and shouldn't be rewritten wholesale). Only rewrite the whole file with Write when creating it fresh. Preserve formatting — match the existing indentation.
+
+7. **Validate.** After writing, read the relevant slice back and confirm the JSON parses and the server is present. All three targets are real settings files — a corrupted write breaks settings on the next start, so validation isn't optional.
+
+8. **Tell the user how to reload.** See below.
+
+## Reload instructions
+
+MCP servers are loaded at startup and on explicit reconnect. After editing config, the user must reload. Tell them the shortest path:
+
+- **Added or changed a server (running session)**: run `/mcp reload` inside QoderCLI — it restarts all MCP clients and refreshes the tool surface. This is the one you want 95% of the time.
+- **Inspect what's loaded**: `/mcp` lists current servers and their status.
+- **Project-scope first-time add**: QoderCLI prompts for approval before running project-level MCP servers (this is enforced via the project-MCP approval flow). The user will see a trust prompt the first time `/mcp reload` picks up the new entry — mention this so they're not surprised.
+- **Removed a server**: `/mcp reload` drops the connection. If you only removed it from one of multiple scopes, it may still show up from another — `qodercli mcp list` confirms where it still lives.
+
+Keep the reload instruction to one or two sentences — don't lecture.
+
+## Gotchas worth flagging
+
+- **Env vars with secrets**: if the pasted config has `"env": { "API_KEY": "sk-..." }` with a real-looking secret, flag it: "This config has what looks like a real API key — do you want to move it to an env var reference or keep it inline?" Don't refuse; just surface the choice.
+- **Settings files hold unrelated keys**: all three targets also store user preferences, keybinding toggles, auth hints, etc. Never rewrite a settings file whole — Edit the specific `mcpServers` slice.
+- **Shared `.qoder` directory name**: user settings live in `~/.qoder/settings.json`; project shared settings in `<repo>/.qoder/settings.json`; project-local (gitignored) in `<repo>/.qoder/settings.local.json`. Keep the scope clear before writing.
+- **Relative paths**: stdio `command`/`args` often reference local scripts. If the user pastes `./server.js`, ask whether they want it resolved to an absolute path — relative paths break when the CLI starts from a different cwd.
+- **Project-scope is committed**: `<repo>/.qoder/settings.json` ends up in git. Remind the user not to include secrets there — for secret-bearing configs prefer `user` or `local`.
+- **Plugin-provided MCPs**: servers whose names start with `mcp__plugin_` come from installed extensions, not user config. Don't try to edit them via this skill — point the user to the extension's own config.
+
+## Output style
+
+Length should match what's actually at stake — not a fixed rule.
+
+**Default (simple add, no concerns):** one or two sentences. What was written where, how to reload. The user pasted config and wants it landed.
+
+> Added `filesystem` (stdio) to `~/.qoder/settings.json` (user scope). Run `/mcp reload` to pick it up.
+
+**When there's something worth flagging, don't suppress it to stay terse.** Brief matters less than "the user understood what just happened and what to do next." Specifically, add a short follow-up paragraph (2-4 sentences) when:
+
+- **The pasted config contained a real-looking secret** (Bearer token, API key, password). Tell them it's now sitting in plaintext in the config file, that project-scope `<repo>/.qoder/settings.json` is committed to git and `~/.qoder/settings.json` is often synced via dotfiles, and offer to switch to env-var reference or rotation if exposed. Don't assume they've thought this through — many people paste from copy-paste without realizing.
+- **The operation has a non-obvious side effect** the user probably didn't anticipate. E.g., for `@modelcontextprotocol/server-filesystem`, changing the path replaces — it doesn't merge, so the old dir loses access. Mention it in one line.
+- **The collision was silent** (user didn't mention the existing entry). Surface what was there before the change.
+- **Scope crossed trust boundary** (e.g. moved from `local` → `project`). Remind them it's now committed and teammates will pick it up on next pull.
+
+Don't pad. Don't add headers (`## 生效方式`, `## 安全提醒`) for a 2-sentence response — just write the sentences. Headers only earn their keep when the response is long enough that scanning matters.