@starlens-app/cli 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlens-app/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Starlens CLI — manage your GitHub starred repositories from the terminal",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "src/index.mjs",
+    "skills/",
     "README.md"
   ],
   "engines": {

package/skills/starlens/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: starlens
+description: Use when an agent runtime such as Hermes, OpenClaw, custom HTTP agents, or coding assistants needs to search, inspect, organize, tag, sync, or ask questions over a user's GitHub starred repositories stored in StarLens. Prefer this skill for agent-side StarLens integration through HTTP APIs with STARLENS_API_BASE_URL and STARLENS_TOKEN.
+---
+
+# StarLens
+
+## Purpose
+
+Use StarLens as the user's searchable memory of GitHub starred repositories. This skill tells an agent when and how to call StarLens over HTTP.
+
+Prefer HTTP API access for Hermes, OpenClaw, server-side agents, remote workers, and containerized runtimes. Use MCP only for IDE or terminal clients that natively support MCP.
+
+## Required Configuration
+
+Read these values from the agent runtime environment, secret store, or project config:
+
+```bash
+STARLENS_API_BASE_URL="https://starlens.example.com"
+STARLENS_TOKEN="stl_xxx"
+```
+
+Send every API request with:
+
+```http
+Authorization: Bearer ${STARLENS_TOKEN}
+Accept: application/json
+```
+
+For JSON request bodies, also send:
+
+```http
+Content-Type: application/json
+```
+
+Never print, log, summarize, or store `STARLENS_TOKEN` in model-visible output.
+
+## Workflow
+
+1. Normalize the user's intent into one of these operations: search, inspect, sync, favorite, note, tag, or ask.
+2. Use `GET /api/search` first when the user gives a repository topic, keyword, language, tag, owner, or partial repository name.
+3. Use `GET /api/repos/{idOrFullName}` when the user gives a concrete repository id or `owner/repo`.
+4. Use write endpoints only when the user clearly asks to modify StarLens state, such as adding a note, tagging a repo, or marking a favorite.
+5. Use `POST /api/ai/ask` when the user asks for synthesis across starred repositories.
+6. Return concise answers with repository names, URLs when available, and the reason each result is relevant.
+
+Read `references/http-api.md` when you need exact endpoint parameters, request bodies, or response handling.
+
+## Behavior Rules
+
+- Treat StarLens as private user data. Do not expose results beyond the current task.
+- Prefer specific queries over broad scans. Ask a follow-up only when the request cannot be mapped to a safe query.
+- If a repository lookup by id or `owner/repo` returns 404, search by that same text before reporting failure.
+- If the API returns 401, tell the user the StarLens token is missing, expired, or revoked.
+- If the API returns 429 or 5xx, retry at most once with a short delay, then report the service issue.
+- Do not create API tokens. Token management is browser-session only.
+- Do not use MCP for Hermes/OpenClaw-style runtimes unless the user explicitly says that runtime supports MCP and wants it.
+
+## Common Examples
+
+Search vector database stars:
+
+```bash
+curl "$STARLENS_API_BASE_URL/api/search?q=vector%20database&page=1&pageSize=10&sort=relevance" \
+  -H "Authorization: Bearer $STARLENS_TOKEN" \
+  -H "Accept: application/json"
+```
+
+Ask across starred repositories:
+
+```bash
+curl -X POST "$STARLENS_API_BASE_URL/api/ai/ask" \
+  -H "Authorization: Bearer $STARLENS_TOKEN" \
+  -H "Accept: application/json" \
+  -H "Content-Type: application/json" \
+  -d '{"question":"哪些 starred repos 适合做本地 RAG 原型？"}'
+```

package/skills/starlens/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "StarLens Agent"
+  short_description: "Use StarLens HTTP APIs from agent runtimes."
+  default_prompt: "Use the StarLens skill to search, inspect, organize, and ask questions over GitHub starred repositories through the configured HTTP API."

package/skills/starlens/references/http-api.md

@@ -0,0 +1,100 @@
+# StarLens HTTP API
+
+All endpoints are relative to `STARLENS_API_BASE_URL`.
+
+## Response Envelope
+
+Successful responses use:
+
+```json
+{ "ok": true, "data": {} }
+```
+
+Failed responses use:
+
+```json
+{ "ok": false, "error": { "code": "string", "message": "string" } }
+```
+
+If `ok` is not `true`, treat the request as failed even when the HTTP status is unexpected.
+
+## Authentication
+
+Use a personal StarLens API token:
+
+```http
+Authorization: Bearer stl_xxx
+Accept: application/json
+```
+
+## Search Stars
+
+`GET /api/search`
+
+Query parameters:
+
+| Name | Type | Notes |
+| --- | --- | --- |
+| `q` | string | Keyword, topic, repo name, owner, or natural query. |
+| `page` | integer | Defaults to `1`. |
+| `pageSize` | integer | Use `10` to `20` for agent answers. |
+| `sort` | string | `relevance`, `recent`, `stars`, or `updated`. |
+| `language` | string | Filter by repository language. |
+| `owner` | string | Filter by GitHub owner. |
+| `tag` | string | Filter by StarLens tag. |
+| `favorite` | boolean | Filter favorites. |
+
+Use this endpoint before detail lookup when the user provides a topic, partial name, or ambiguous repository reference.
+
+## Repository Detail
+
+`GET /api/repos/{idOrFullName}`
+
+`idOrFullName` can be a StarLens repository id or `owner/repo`. If it returns 404, search the same text with `/api/search` before giving up.
+
+## Sync Stars
+
+`POST /api/sync`
+
+Trigger GitHub Stars sync for the authenticated StarLens user. Use only when the user asks to refresh or sync.
+
+## Update Repository State
+
+`PATCH /api/repos/{idOrFullName}`
+
+Body fields:
+
+```json
+{
+  "isFavorite": true,
+  "note": "Short user note"
+}
+```
+
+Send only fields that should change. Use an empty `note` string only when the user asks to clear a note.
+
+## Tags
+
+Add a tag:
+
+`POST /api/repos/{idOrFullName}/tags`
+
+```json
+{ "tag": "rag" }
+```
+
+Remove a tag:
+
+`DELETE /api/repos/{idOrFullName}/tags/{tag}`
+
+## AI Ask
+
+`POST /api/ai/ask`
+
+```json
+{ "question": "哪些 starred repos 适合做本地 RAG 原型？" }
+```
+
+Use this endpoint for synthesis, comparison, recommendations, and natural-language questions over the user's starred repositories.
+
+The server chooses the user's default AI Provider first and falls back to the system default AI configuration when no user default is available.

package/src/index.mjs

@@ -31,7 +31,7 @@ const helpText = [
   "  stars note <repo-id|owner/repo> (--set <text>|--clear) [--api-base-url <url>] [--token-path <path>] [--format table|json]",
   "  stars tag add <repo-id|owner/repo> <tag> [--api-base-url <url>] [--token-path <path>] [--format table|json]",
   "  stars tag remove <repo-id|owner/repo> <tag> [--api-base-url <url>] [--token-path <path>] [--format table|json]",
-  "  stars install-skill [--api-base-url <url>] [--token <token>] [--client claude|cursor|codex|opencode|other]",
+  "  stars install-skill [--api-base-url <url>] [--token <token>] [--client claude,cursor,...]  (多客户端逗号分隔)",
   "  stars version",
   "",
   "Configuration:",
@@ -715,6 +715,97 @@ function detectProjectRoot() {
   return new URL("../../..", import.meta.url).pathname.replace(/\/$/, "");
 }
 
+// Skill 源目录（npm 包内的 skills/ 目录）
+function getSkillSourceDir() {
+  return new URL("../../skills/starlens", import.meta.url).pathname;
+}
+
+// 各客户端全局 skill 目标路径
+const SKILL_TARGETS = {
+  claude:    { path: join(homedir(), ".claude", "skills", "starlens"),    label: "Claude Code" },
+  opencode:  { path: join(homedir(), ".opencode", "skills", "starlens"),  label: "OpenCode" },
+  codex:     { path: join(homedir(), ".codex", "skills", "starlens"),     label: "Codex CLI" },
+  openclaw:  { path: join(homedir(), ".openclaw", "skills", "starlens"),  label: "OpenClaw" },
+  hermes:    { path: join(homedir(), ".hermes", "skills", "starlens"),    label: "Hermes" },
+};
+
+async function copyDir(src, dest) {
+  const { readdir, copyFile } = await import("node:fs/promises");
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await copyFile(srcPath, destPath);
+    }
+  }
+}
+
+async function installSkillFiles(client, projectPath) {
+  const skillSrc = getSkillSourceDir();
+
+  // 检查 skill 源是否存在（全局安装时应该存在）
+  try {
+    await access(skillSrc);
+  } catch {
+    return { ok: false, reason: "skill 文件未找到（可能是旧版本，请更新：npm i -g @starlens-app/cli）" };
+  }
+
+  const results = [];
+
+  // 1. 全局路径（对应当前客户端）
+  const globalTarget = SKILL_TARGETS[client];
+  if (globalTarget) {
+    try {
+      await copyDir(skillSrc, globalTarget.path);
+      results.push({ path: globalTarget.path, ok: true });
+    } catch (e) {
+      results.push({ path: globalTarget.path, ok: false, reason: e.message });
+    }
+  }
+
+  // 2. Cursor 项目级：.cursor/rules/starlens.mdc
+  if (client === "cursor" && projectPath) {
+    const cursorRulesDir = join(projectPath, ".cursor", "rules");
+    const cursorTarget = join(cursorRulesDir, "starlens.mdc");
+    try {
+      await mkdir(cursorRulesDir, { recursive: true });
+      const skillContent = await readFile(join(skillSrc, "SKILL.md"), "utf8");
+      // 转换 SKILL.md → .mdc（保持内容不变，Cursor 兼容 markdown frontmatter）
+      await writeFile(cursorTarget, skillContent);
+      results.push({ path: cursorTarget, ok: true });
+    } catch (e) {
+      results.push({ path: cursorTarget, ok: false, reason: e.message });
+    }
+  }
+
+  // 3. VS Code 项目级：.github/copilot-instructions.md（追加）
+  if (client === "vscode" && projectPath) {
+    const githubDir = join(projectPath, ".github");
+    const vscodeTarget = join(githubDir, "copilot-instructions.md");
+    try {
+      await mkdir(githubDir, { recursive: true });
+      const skillContent = await readFile(join(skillSrc, "SKILL.md"), "utf8");
+      // 去掉 frontmatter，只保留正文
+      const body = skillContent.replace(/^---[\s\S]*?---\n/, "").trim();
+      let existing = "";
+      try { existing = await readFile(vscodeTarget, "utf8"); } catch { /* 不存在则新建 */ }
+      const marker = "<!-- starlens-skill -->";
+      if (!existing.includes(marker)) {
+        await writeFile(vscodeTarget, existing + (existing ? "\n\n" : "") + marker + "\n" + body + "\n" + marker);
+      }
+      results.push({ path: vscodeTarget, ok: true });
+    } catch (e) {
+      results.push({ path: vscodeTarget, ok: false, reason: e.message });
+    }
+  }
+
+  return { ok: results.some(r => r.ok), results };
+}
+
 function createReadlineInterface() {
   return createInterface({ input: process.stdin, output: process.stdout, terminal: false });
 }
@@ -770,6 +861,109 @@ async function wizardPromptSecret(question) {
   });
 }
 
+function maskToken(token) {
+  if (!token || token.length < 8) return "***";
+  return token.slice(0, 4) + "..." + token.slice(-3);
+}
+
+async function readExistingToken() {
+  const agentEnvPath = join(homedir(), ".starlens", "agent.env");
+  try {
+    const content = await readFile(agentEnvPath, "utf8");
+    const match = content.match(/^export STARLENS_TOKEN="([^"]+)"/m);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+async function wizardCheckbox(items) {
+  const isTTY = typeof process.stdin.setRawMode === "function";
+
+  if (!isTTY) {
+    // Non-TTY fallback: comma-separated input
+    const labels = items.map((it, i) => `  ${i + 1}) ${it.label}${it.skillOnly ? " [仅 Skill]" : ""}`).join("\n");
+    console.log(labels);
+    const rl = createReadlineInterface();
+    return new Promise((resolve) => {
+      rl.question("输入序号（逗号分隔，如 1,2）: ", (answer) => {
+        rl.close();
+        const selected = answer.trim().split(",").map(s => {
+          const n = parseInt(s.trim(), 10);
+          return items[n - 1]?.value ?? null;
+        }).filter(Boolean);
+        resolve(selected.length > 0 ? selected : [items[0].value]);
+      });
+    });
+  }
+
+  return new Promise((resolve) => {
+    let cursor = 0;
+    const selected = new Set([items[0].value]); // 默认选中第一项
+
+    const RESET = "\x1b[0m";
+    const BOLD = "\x1b[1m";
+    const CYAN = "\x1b[36m";
+    const DIM = "\x1b[2m";
+
+    function render() {
+      // 清除之前的输出行
+      process.stdout.write("\x1b[" + items.length + "A\x1b[0J");
+      for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        const isActive = i === cursor;
+        const isSelected = selected.has(item.value);
+        const icon = isSelected ? "◉" : "◯";
+        const label = item.label + (item.skillOnly ? `  ${DIM}[仅 Skill]${RESET}` : "");
+        const line = isActive
+          ? `${BOLD}${CYAN}> ${icon} ${label}${RESET}`
+          : `  ${icon} ${label}`;
+        process.stdout.write(line + "\n");
+      }
+    }
+
+    // 初次渲染
+    console.log(`请选择 AI 客户端（${BOLD}↑↓${RESET} 移动，${BOLD}空格${RESET} 选中/取消，${BOLD}回车${RESET} 确认）：\n`);
+    for (let i = 0; i < items.length; i++) {
+      process.stdout.write("\n");
+    }
+    render();
+
+    const stdin = process.stdin;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+
+    const onData = (chunk) => {
+      if (chunk === "\x1b[A") { // 上箭头
+        cursor = (cursor - 1 + items.length) % items.length;
+        render();
+      } else if (chunk === "\x1b[B") { // 下箭头
+        cursor = (cursor + 1) % items.length;
+        render();
+      } else if (chunk === " ") { // 空格
+        const val = items[cursor].value;
+        if (selected.has(val)) selected.delete(val);
+        else selected.add(val);
+        render();
+      } else if (chunk === "\r" || chunk === "\n") { // 回车
+        stdin.setRawMode(false);
+        stdin.removeListener("data", onData);
+        stdin.pause();
+        process.stdout.write("\n");
+        const result = items.map(it => it.value).filter(v => selected.has(v));
+        resolve(result.length > 0 ? result : [items[0].value]);
+      } else if (chunk === "\x03") { // Ctrl+C
+        stdin.setRawMode(false);
+        process.stdout.write("\n");
+        process.exit(1);
+      }
+    };
+
+    stdin.on("data", onData);
+  });
+}
+
 function buildMcpArgs(projectRoot) {
   return ["-lc", `source "$HOME/.starlens/agent.env" && cd "${projectRoot}" && corepack pnpm mcp:start`];
 }
@@ -833,6 +1027,70 @@ function renderOpencodeSnippet(projectRoot) {
   );
 }
 
+async function mergeJson(filePath, mergeFn) {
+  let existing = {};
+  try {
+    const raw = await readFile(filePath, "utf8");
+    existing = JSON.parse(raw);
+  } catch { /* 文件不存在或格式错误则从空对象开始 */ }
+  const merged = mergeFn(existing);
+  await mkdir(filePath.replace(/\/[^/]+$/, ""), { recursive: true });
+  await writeFile(filePath, JSON.stringify(merged, null, 2) + "\n");
+}
+
+async function appendTomlSection(filePath, sectionKey, content) {
+  let existing = "";
+  try { existing = await readFile(filePath, "utf8"); } catch { /* 新建 */ }
+  if (existing.includes(`[${sectionKey}]`)) {
+    return { ok: false, reason: `[${sectionKey}] 节点已存在，跳过写入` };
+  }
+  await mkdir(filePath.replace(/\/[^/]+$/, ""), { recursive: true });
+  await writeFile(filePath, existing + (existing && !existing.endsWith("\n") ? "\n" : "") + "\n" + content + "\n");
+  return { ok: true };
+}
+
+async function writeMcpConfig(client, { apiBaseUrl, token, projectRoot, hosted }) {
+  const home = homedir();
+  try {
+    if (client === "cursor") {
+      const cursorMcpPath = join(home, ".cursor", "mcp.json");
+      const starlensEntry = hosted
+        ? { url: `${apiBaseUrl}/mcp`, headers: { Authorization: `Bearer ${token || "stl_xxx"}` } }
+        : { command: "corepack", args: ["pnpm", "mcp:start"], cwd: projectRoot, env: { STARLENS_TOKEN: "（从 ~/.starlens/agent.env 读取）", STARLENS_API_BASE_URL: "（从 ~/.starlens/agent.env 读取）" } };
+      await mergeJson(cursorMcpPath, (obj) => ({
+        ...obj,
+        mcpServers: { ...(obj.mcpServers ?? {}), starlens: starlensEntry },
+      }));
+      return { ok: true, path: cursorMcpPath };
+    }
+
+    if (client === "opencode") {
+      const opencodePath = join(home, ".config", "opencode", "opencode.json");
+      const starlensEntry = hosted
+        ? { type: "http", url: `${apiBaseUrl}/mcp`, headers: { Authorization: `Bearer ${token || "stl_xxx"}` }, enabled: true }
+        : { type: "local", command: ["zsh", "-lc", `source "$HOME/.starlens/agent.env" && cd "${projectRoot}" && corepack pnpm mcp:start`], enabled: true, timeout: 10000 };
+      await mergeJson(opencodePath, (obj) => ({
+        ...obj,
+        mcp: { ...(obj.mcp ?? {}), starlens: starlensEntry },
+      }));
+      return { ok: true, path: opencodePath };
+    }
+
+    if (client === "codex") {
+      const codexPath = join(home, ".codex", "config.toml");
+      const content = hosted
+        ? `[mcp_servers.starlens]\ntype = "http"\nurl = "${apiBaseUrl}/mcp"\n\n[mcp_servers.starlens.headers]\nAuthorization = "Bearer ${token || "stl_xxx"}"\nstartup_timeout_sec = 30\ndefault_tools_approval_mode = "approve"`
+        : `[mcp_servers.starlens]\ntype = "stdio"\ncommand = "zsh"\nargs = ["-lc", "source \\"$HOME/.starlens/agent.env\\" && cd \\"${projectRoot}\\" && corepack pnpm mcp:start"]\nstartup_timeout_sec = 30\ndefault_tools_approval_mode = "approve"`;
+      const result = await appendTomlSection(codexPath, "mcp_servers.starlens", content);
+      return result.ok ? { ok: true, path: codexPath } : { ok: false, reason: result.reason };
+    }
+
+    return { ok: false, reason: `${client} 不支持自动写入，请手动配置` };
+  } catch (e) {
+    return { ok: false, reason: e.message };
+  }
+}
+
 async function spawnCommand(command, args) {
   return new Promise((resolve) => {
     const child = spawn(command, args, { stdio: "inherit" });
@@ -913,237 +1171,221 @@ async function runInstallSkillWizard(args, env) {
   const clientArg = readOption(rest, "--client");
   rest = clientArg.rest;
 
+  const clientLabels = {
+    claude: "Claude Code", cursor: "Cursor", vscode: "VS Code (Copilot)",
+    codex: "Codex CLI", opencode: "OpenCode", openclaw: "OpenClaw", hermes: "Hermes", other: "其他",
+  };
+  const MCP_SUPPORTED = new Set(["claude", "cursor", "codex", "opencode"]);
+
+  const CLIENT_ITEMS = [
+    { value: "claude",   label: "Claude Code" },
+    { value: "cursor",   label: "Cursor" },
+    { value: "vscode",   label: "VS Code (Copilot)",  skillOnly: true },
+    { value: "codex",    label: "Codex CLI" },
+    { value: "opencode", label: "OpenCode" },
+    { value: "openclaw", label: "OpenClaw",            skillOnly: true },
+    { value: "hermes",   label: "Hermes",              skillOnly: true },
+    { value: "other",    label: "其他（仅输出配置片段）", skillOnly: true },
+  ];
+
   console.log("");
-  console.log("Starlens MCP 安装向导");
+  console.log("Starlens 安装向导");
   console.log("═".repeat(40));
-  console.log("本向导将引导你完成 MCP Server 接入配置。");
+  console.log("本向导将引导你完成 Skill 安装及可选的 MCP Server 配置。");
   console.log("");
 
   // Step 0: check global install
   const isGlobalInstall = !process.argv[1]?.includes("apps/cli");
   if (!isGlobalInstall) {
     console.log("提示：你正在从源码运行。如需让其他工具通过 `stars` 命令使用，");
-    console.log("      请先全局安装：npm install -g starlens");
+    console.log("      请先全局安装：npm install -g @starlens-app/cli");
     console.log("");
   }
 
   const rl = createReadlineInterface();
 
   try {
-    // Step 1: select deployment mode
-    const defaultUrl = apiBaseUrlArg.value ?? env.STARLENS_API_BASE_URL ?? HOSTED_MCP_BASE_URL;
-    console.log("部署模式：");
-    console.log("  1) 托管服务（推荐）— 使用 starlens.520ai.xin，无需本地启动服务");
-    console.log("  2) 自部署 — 使用你自己的服务器或本地开发环境");
-    const modeChoice = await wizardPrompt(rl, "选择模式", "1");
-    const isSelfHosted = modeChoice.trim() === "2";
-
-    let apiBaseUrl;
-    let projectRoot;
-
-    if (isSelfHosted) {
-      console.log("");
-      apiBaseUrl = (await wizardPrompt(rl, "Starlens API base URL", defaultUrl === HOSTED_MCP_BASE_URL ? DEFAULT_API_BASE_URL : defaultUrl)).replace(/\/+$/, "");
-      // only ask for project root in self-hosted stdio mode
-      if (!isHostedUrl(apiBaseUrl)) {
-        const detectedRoot = detectProjectRoot();
-        console.log(`检测到项目根目录：${detectedRoot}`);
-        projectRoot = (await wizardPrompt(rl, "项目路径（回车确认）", detectedRoot)).replace(/\/$/, "");
-      }
+    // Step 1: 多选客户端
+    let clients;
+    const clientArgRaw = clientArg.value?.toLowerCase();
+    if (clientArgRaw) {
+      // --client 参数：逗号分隔
+      const nameMap = Object.fromEntries(CLIENT_ITEMS.map(it => [it.value, it.value]));
+      clients = clientArgRaw.split(",").map(s => nameMap[s.trim()]).filter(Boolean);
+      if (clients.length === 0) clients = ["claude"];
+      console.log(`已选择客户端：${clients.map(c => clientLabels[c]).join("、")}`);
     } else {
-      apiBaseUrl = HOSTED_MCP_BASE_URL;
-      console.log(`✓ 使用托管服务：${HOSTED_MCP_BASE_URL}`);
+      console.log("");
+      clients = await wizardCheckbox(CLIENT_ITEMS);
+      console.log(`已选择：${clients.map(c => clientLabels[c]).join("、")}`);
     }
 
-    const hosted = isHostedUrl(apiBaseUrl);
-
-    // Step 2: select client
-    const clientMap = {
-      "1": "claude", "2": "cursor", "3": "codex", "4": "opencode", "5": "other",
-      "claude": "claude", "cursor": "cursor", "codex": "codex", "opencode": "opencode", "other": "other",
-    };
+    const cwd = process.cwd();
 
-    let client = clientArg.value?.toLowerCase();
-    if (!clientMap[client]) {
+    // Step 2: 安装 Skill（默认是）
+    console.log("");
+    console.log("─".repeat(40));
+    const installSkill = await wizardPrompt(rl, "是否安装 Starlens Skill 文件？(Y/n)", "Y");
+    if (!/^n$/i.test(installSkill)) {
       console.log("");
-      console.log("请选择你的 AI 客户端：");
-      console.log("  1) Claude Code");
-      console.log("  2) Cursor");
-      console.log("  3) Codex");
-      console.log("  4) opencode");
-      console.log("  5) 其他（仅输出配置片段）");
-      const clientChoice = await wizardPrompt(rl, "输入序号或名称", "1");
-      client = clientMap[clientChoice.toLowerCase()] ?? "other";
+      console.log("安装 Starlens Agent Skill...");
+      for (const client of clients) {
+        const skillResult = await installSkillFiles(client, cwd);
+        if (skillResult.results) {
+          for (const r of skillResult.results) {
+            if (r.ok) {
+              console.log(`✓ Skill 已安装：${r.path}`);
+            } else {
+              console.log(`⚠  Skill 安装失败：${r.path}（${r.reason}）`);
+            }
+          }
+        } else if (!skillResult.ok) {
+          console.log(`⚠  ${clientLabels[client]}：${skillResult.reason}`);
+        }
+      }
     } else {
-      client = clientMap[client];
+      console.log("跳过 Skill 安装。");
     }
 
-    const clientLabels = { claude: "Claude Code", cursor: "Cursor", codex: "Codex", opencode: "opencode", other: "其他" };
-    console.log(`已选择客户端：${clientLabels[client]}`);
-
-    // Step 3: token
+    // Step 3: 配置 MCP（可选，默认否）
     console.log("");
-    console.log("在 Starlens 设置页创建 API Token（stl_xxx），然后粘贴到这里。");
+    console.log("─".repeat(40));
+    const mcpClients = clients.filter(c => MCP_SUPPORTED.has(c));
     let token = tokenArg.value ?? "";
-    if (!token) {
-      token = await wizardPromptSecret("API Token（输入不可见）");
-    }
-    if (!token) {
-      console.log("⚠  未输入 Token，配置片段中将显示占位符 stl_xxx，请事后手动替换。");
-    }
+    let apiBaseUrl = "";
 
-    // Step 4: for self-hosted + non-hosted URL, write ~/.starlens/agent.env
-    if (!hosted && token) {
-      const agentEnvDir = join(homedir(), ".starlens");
-      const agentEnvPath = join(agentEnvDir, "agent.env");
-      let skipEnvWrite = false;
+    if (mcpClients.length === 0) {
+      console.log("所选客户端均不支持 MCP，跳过 MCP 配置。");
+    } else {
+      const doMcp = await wizardPrompt(rl, `是否配置 MCP Server？（支持：${mcpClients.map(c => clientLabels[c]).join("、")}）(y/N)`, "N");
+      if (/^y$/i.test(doMcp)) {
+        // 部署模式
+        console.log("");
+        const defaultUrl = apiBaseUrlArg.value ?? env.STARLENS_API_BASE_URL ?? HOSTED_MCP_BASE_URL;
+        console.log("部署模式：");
+        console.log("  1) 托管服务（推荐）— 使用 starlens.520ai.xin，无需本地启动服务");
+        console.log("  2) 自部署 — 使用你自己的服务器或本地开发环境");
+        const modeChoice = await wizardPrompt(rl, "选择模式", "1");
+        const isSelfHosted = modeChoice.trim() === "2";
+
+        let projectRoot;
+        if (isSelfHosted) {
+          console.log("");
+          apiBaseUrl = (await wizardPrompt(rl, "Starlens API base URL", defaultUrl === HOSTED_MCP_BASE_URL ? DEFAULT_API_BASE_URL : defaultUrl)).replace(/\/+$/, "");
+          if (!isHostedUrl(apiBaseUrl)) {
+            const detectedRoot = detectProjectRoot();
+            console.log(`检测到项目根目录：${detectedRoot}`);
+            projectRoot = (await wizardPrompt(rl, "项目路径（回车确认）", detectedRoot)).replace(/\/$/, "");
+          }
+        } else {
+          apiBaseUrl = HOSTED_MCP_BASE_URL;
+          console.log(`✓ 使用托管服务：${HOSTED_MCP_BASE_URL}`);
+        }
 
-      let envExists = false;
-      try {
-        await access(agentEnvPath);
-        envExists = true;
-      } catch {
-        // doesn't exist
-      }
+        const hosted = isHostedUrl(apiBaseUrl);
 
-      if (envExists) {
+        // Token（支持历史复用，脱敏展示）
         console.log("");
-        const overwrite = await wizardPrompt(rl, "~/.starlens/agent.env 已存在，是否覆盖？(y/N)", "N");
-        skipEnvWrite = !/^y$/i.test(overwrite);
-      }
-
-      if (!skipEnvWrite) {
-        await mkdir(agentEnvDir, { recursive: true });
-        await chmod(agentEnvDir, 0o700);
-        const envContent = [
-          `export STARLENS_TOKEN="${token}"`,
-          `export STARLENS_API_BASE_URL="${apiBaseUrl}"`,
-          "",
-        ].join("\n");
-        await writeFile(agentEnvPath, envContent, { mode: 0o600 });
-        console.log(`✓ 已写入 ${agentEnvPath}`);
-      } else {
-        console.log("跳过写入 agent.env。");
-      }
-    }
+        console.log("在 Starlens 设置页创建 API Token（stl_xxx），然后粘贴到这里。");
+        if (!token) {
+          const existingToken = await readExistingToken();
+          const tokenHint = existingToken ? `回车复用已有 token: ${maskToken(existingToken)}，或输入新值` : "输入不可见";
+          const inputToken = await wizardPromptSecret(`API Token（${tokenHint}）`);
+          token = inputToken || existingToken || "";
+        }
+        if (!token) {
+          console.log("⚠  未输入 Token，配置片段中将显示占位符 stl_xxx，请事后手动替换。");
+        }
 
-    // Step 5: output config snippet
-    console.log("");
-    console.log("─".repeat(40));
+        // 写入 agent.env（自部署非托管模式）
+        if (!hosted && token) {
+          const agentEnvDir = join(homedir(), ".starlens");
+          const agentEnvPath = join(agentEnvDir, "agent.env");
+          let envExists = false;
+          try { await access(agentEnvPath); envExists = true; } catch { /* 不存在 */ }
+
+          let skipEnvWrite = false;
+          if (envExists) {
+            console.log("");
+            const overwrite = await wizardPrompt(rl, "~/.starlens/agent.env 已存在，是否覆盖？(y/N)", "N");
+            skipEnvWrite = !/^y$/i.test(overwrite);
+          }
 
-    if (hosted) {
-      // ── Hosted mode: HTTP MCP ──
-      if (client === "claude") {
-        const snippet = renderHostedClaudeSnippet(apiBaseUrl, token);
-        console.log("Claude Code 配置命令：");
-        console.log("");
-        console.log(snippet);
-        console.log("");
-        const autoRun = await wizardPrompt(rl, "是否立即执行上述命令？(y/N)", "N");
-        if (/^y$/i.test(autoRun)) {
-          const mcpJson = JSON.stringify({
-            type: "http",
-            url: `${apiBaseUrl}/mcp`,
-            headers: { Authorization: `Bearer ${token}` },
-          });
-          console.log("正在注册 MCP server...");
-          const ok = await spawnCommand("claude", ["mcp", "add-json", "starlens", mcpJson]);
-          if (ok) {
-            console.log("✓ MCP server 已注册到 Claude Code。");
+          if (!skipEnvWrite) {
+            await mkdir(agentEnvDir, { recursive: true });
+            await chmod(agentEnvDir, 0o700);
+            const envContent = [`export STARLENS_TOKEN="${token}"`, `export STARLENS_API_BASE_URL="${apiBaseUrl}"`, ""].join("\n");
+            await writeFile(agentEnvPath, envContent, { mode: 0o600 });
+            console.log(`✓ 已写入 ${agentEnvPath}`);
           } else {
-            console.log("✗ 注册失败，请手动执行上方命令。");
+            console.log("跳过写入 agent.env。");
           }
         }
-      } else if (client === "cursor") {
-        console.log("将以下内容写入 .cursor/mcp.json（合并到 mcpServers 节点）：");
-        console.log("");
-        console.log(renderHostedCursorSnippet(apiBaseUrl, token));
-      } else if (client === "codex") {
-        console.log("将以下内容追加到 ~/.codex/config.toml：");
-        console.log("");
-        console.log(renderHostedCodexSnippet(apiBaseUrl, token));
-      } else if (client === "opencode") {
-        console.log("将以下内容合并到 ~/.config/opencode/opencode.json：");
-        console.log("");
-        console.log(renderHostedOpencodeSnippet(apiBaseUrl, token));
-      } else {
-        console.log("HTTP MCP 端点信息：");
-        console.log("");
-        console.log(`  URL:           ${apiBaseUrl}/mcp`);
-        console.log(`  Authorization: Bearer ${token || "stl_xxx"}`);
-      }
-    } else {
-      // ── Self-hosted mode: stdio MCP ──
-      if (client === "claude") {
-        const snippet = renderClaudeCodeSnippet(projectRoot);
-        console.log("Claude Code 配置命令：");
-        console.log("");
-        console.log(snippet);
+
+        // 对每个支持 MCP 的客户端自动写入配置
         console.log("");
-        const autoRun = await wizardPrompt(rl, "是否立即执行上述命令？(y/N)", "N");
-        if (/^y$/i.test(autoRun)) {
-          const mcpJson = JSON.stringify({ type: "stdio", command: "zsh", args: buildMcpArgs(projectRoot) });
-          console.log("正在注册 MCP server...");
-          const ok = await spawnCommand("claude", ["mcp", "add-json", "starlens", mcpJson]);
-          if (ok) {
-            console.log("✓ MCP server 已注册到 Claude Code。");
+        console.log("─".repeat(40));
+        console.log("配置 MCP Server...");
+        for (const client of mcpClients) {
+          if (client === "claude") {
+            const mcpJson = hosted
+              ? JSON.stringify({ type: "http", url: `${apiBaseUrl}/mcp`, headers: { Authorization: `Bearer ${token || "stl_xxx"}` } })
+              : JSON.stringify({ type: "stdio", command: "zsh", args: buildMcpArgs(projectRoot) });
+            console.log(`\n  ${clientLabels.claude} 配置命令：`);
+            console.log(`  claude mcp add-json starlens '${mcpJson}'`);
+            console.log("");
+            const autoRun = await wizardPrompt(rl, "  是否立即执行？(y/N)", "N");
+            if (/^y$/i.test(autoRun)) {
+              const ok = await spawnCommand("claude", ["mcp", "add-json", "starlens", mcpJson]);
+              console.log(ok ? "  ✓ MCP server 已注册到 Claude Code。" : "  ✗ 注册失败，请手动执行上方命令。");
+            }
           } else {
-            console.log("✗ 注册失败，请手动执行上方命令。");
+            const result = await writeMcpConfig(client, { apiBaseUrl, token, projectRoot, hosted });
+            if (result.ok) {
+              console.log(`✓ MCP 配置已写入：${result.path}`);
+            } else {
+              console.log(`⚠  ${clientLabels[client]}：${result.reason}`);
+            }
           }
         }
-      } else if (client === "cursor") {
-        console.log("将以下内容写入 .cursor/mcp.json（合并到 mcpServers 节点）：");
-        console.log("");
-        console.log(renderCursorSnippet(projectRoot));
-      } else if (client === "codex") {
-        console.log("将以下内容追加到 ~/.codex/config.toml：");
-        console.log("");
-        console.log(renderCodexSnippet(projectRoot));
-      } else if (client === "opencode") {
-        console.log("将以下内容合并到 ~/.config/opencode/opencode.json：");
-        console.log("");
-        console.log(renderOpencodeSnippet(projectRoot));
-      } else {
-        console.log("通用 Agent Skill 环境变量配置：");
-        console.log("");
-        console.log(`  STARLENS_TOKEN="${token || "stl_xxx"}"`);
-        console.log(`  STARLENS_API_BASE_URL="${apiBaseUrl}"`);
-      }
-    }
 
-    // Step 6: verify token (optional)
-    if (token) {
-      console.log("");
-      const doVerify = await wizardPrompt(rl, "是否验证 Token 可用性？(y/N)", "N");
-      if (/^y$/i.test(doVerify)) {
-        console.log("验证中...");
-        try {
-          const res = await fetchWithTimeout(
-            `${apiBaseUrl}/api/search?q=test&pageSize=1`,
-            { headers: { Accept: "application/json", Authorization: `Bearer ${token}` } },
-            8_000,
-          );
-          if (res.ok) {
-            console.log("✓ Token 验证成功，API 连接正常。");
-          } else if (res.status === 401 || res.status === 403) {
-            console.log(`✗ Token 无效（HTTP ${res.status}）。请检查 Token 是否正确。`);
-          } else {
-            console.log(`⚠  服务器返回 HTTP ${res.status}，请检查 API base URL 是否正确。`);
+        // 验证 Token（可选）
+        if (token) {
+          console.log("");
+          const doVerify = await wizardPrompt(rl, "是否验证 Token 可用性？(y/N)", "N");
+          if (/^y$/i.test(doVerify)) {
+            console.log("验证中...");
+            try {
+              const res = await fetchWithTimeout(
+                `${apiBaseUrl}/api/search?q=test&pageSize=1`,
+                { headers: { Accept: "application/json", Authorization: `Bearer ${token}` } },
+                8_000,
+              );
+              if (res.ok) {
+                console.log("✓ Token 验证成功，API 连接正常。");
+              } else if (res.status === 401 || res.status === 403) {
+                console.log(`✗ Token 无效（HTTP ${res.status}）。请检查 Token 是否正确。`);
+              } else {
+                console.log(`⚠  服务器返回 HTTP ${res.status}，请检查 API base URL 是否正确。`);
+              }
+            } catch {
+              console.log(`✗ 无法连接到 ${apiBaseUrl}，请检查服务是否启动。`);
+            }
           }
-        } catch {
-          console.log(`✗ 无法连接到 ${apiBaseUrl}，请检查服务是否启动。`);
         }
+      } else {
+        console.log("跳过 MCP 配置。");
       }
     }
 
-    // Step 7: done
+    // 完成
     console.log("");
     console.log("─".repeat(40));
     console.log("✓ 配置完成！");
     console.log("");
     console.log("下一步：");
-    console.log("  1. 重启你的 AI 客户端，使 MCP server 生效。");
-    console.log("  2. 在客户端中输入「搜索我收藏的关于 React 的仓库」测试工具是否可用。");
+    console.log("  1. 重启你的 AI 客户端，使配置生效。");
+    console.log("  2. 在客户端中输入「搜索我收藏的关于 React 的仓库」测试是否可用。");
     console.log(`  3. 完整文档：${HOSTED_MCP_BASE_URL}/docs/integrations`);
     console.log("");
   } finally {