xitto-kernel 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.3.2
+
+- **沒設定就啟動 → 直接進導引**：偵測到沒有 providers.json 且在真實終端時，
+  不再只印提示，而是直接帶進 `init` 設定流程，完成後接續啟動該 pack（非 TTY 仍只給提示）。
+
+## 0.3.1
+
+首次使用導引 —— 不再假設使用者已有 xitto-code。
+
+### 新增
+
+- **`xitto-kernel init`**：互動式設定導引，產生 `~/.xitto-code/providers.json`
+  - 內建 provider 範本（MiniMax / Anthropic / OpenAI / DeepSeek / 自訂）
+  - 引導選 provider → 填 model → 處理 API key（環境變數參照 `${NAME}` 不落地，或內嵌）
+  - 既有設定不覆寫；`--force` 合併新 provider
+  - pipe-safe 逐行讀取（可 `echo answers | xitto-kernel init` 腳本化）
+- **沒設定就啟動**：改丟明確提示，引導跑 `xitto-kernel init`（不再叫人去找 xitto-code 的範例檔）
+- README 快速開始改為 安裝 → `init` → 啟動 三步
+
 ## 0.3.0
 
 把底座的「能力」與「體驗」補到接近 Claude Code，並擴充領域 pack 與評測。

package/README.md

@@ -23,20 +23,26 @@ xitto-code 經掃描後，約 **8 成已是領域無關的 kernel**；真正跟
 
 ## 快速開始
 
-**前置需求**
-- Node.js ≥ 20
-- `~/.xitto-code/providers.json` —— LLM provider 設定（與 xitto-code 共用，內含 API key）。
-  沒有的話，複製一份填入 key 即可（格式見 xitto-code 的 `providers.example.json`）。
+**前置需求**：Node.js ≥ 20
 
-**安裝**（已發佈 npm）
+**1. 安裝**（已發佈 npm）
 ```bash
 npm install -g xitto-kernel    # 全域命令 xitto-kernel
 ```
 > 開發本倉庫：`cd xitto-kernel && npm install && npm link`。
 
-**跑內建 pack（互動 CLI）**
+**2. 首次設定**（互動導引，產生 `~/.xitto-code/providers.json`）
+```bash
+xitto-kernel init
+```
+引導你選 provider（MiniMax / Anthropic / OpenAI / DeepSeek / 自訂）→ 填 model →
+設定 API key（建議用環境變數參照 `${NAME}`，金鑰不落地）。已是 xitto-code 使用者可直接共用既有設定、跳過此步。
+（沒設定就啟動會提示你跑 `init`；既有設定不會被覆寫，`--force` 才會合併新 provider。）
+
+**3. 跑內建 pack（互動 CLI）**
 ```bash
 xitto-kernel                  # coding agent（讀寫檔案、跑命令）
+xitto-kernel --tui            # 完整 Ink TUI（持久狀態列、串流、Esc 中斷；需真實終端）
 xitto-kernel --pack notes     # 筆記 / 知識庫 agent
 xitto-kernel --pack data-query
 xitto-kernel --sandbox        # 啟動就開 Seatbelt 沙箱

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xitto-kernel",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "description": "領域無關的 agent 底座（kernel + 可插拔 DomainPack），從 xitto-code 抽象而來",
   "keywords": [

package/src/app/init.js

@@ -0,0 +1,134 @@
+// 首次啟動導引：互動式產生 ~/.xitto-code/providers.json。
+// 內建常見 provider 範本（MiniMax / Anthropic / OpenAI / DeepSeek / 自訂），
+// 引導選 provider → 填 model → 處理 API key（環境變數或內嵌），寫檔不覆寫既有設定。
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+
+const e = (n) => (s) => `\x1b[${n}m${s}\x1b[0m`;
+const green = e(32); const gray = e(90); const cyan = e(36); const yellow = e(33); const bold = e(1); const red = e(31);
+
+// provider 範本（沿用實測可用的格式；baseUrl/api/model 皆可在引導中改）
+const PRESETS = {
+  minimax: { label: 'MiniMax（M2.7，anthropic 相容）', api: 'anthropic-messages', baseUrl: 'https://api.minimaxi.com/anthropic', env: 'MINIMAX_API_KEY', model: { id: 'MiniMax-M2.7', name: 'MiniMax M2.7', contextWindow: 1000192, maxTokens: 131072 } },
+  anthropic: { label: 'Anthropic Claude', api: 'anthropic-messages', baseUrl: 'https://api.anthropic.com', env: 'ANTHROPIC_API_KEY', model: { id: 'claude-sonnet-4-6', name: 'Claude Sonnet 4.6', contextWindow: 200000, maxTokens: 64000 } },
+  openai: { label: 'OpenAI', api: 'openai-completions', baseUrl: 'https://api.openai.com/v1', env: 'OPENAI_API_KEY', model: { id: 'gpt-4o', name: 'GPT-4o', contextWindow: 128000, maxTokens: 16384 } },
+  deepseek: { label: 'DeepSeek', api: 'openai-completions', baseUrl: 'https://api.deepseek.com', env: 'DEEPSEEK_API_KEY', model: { id: 'deepseek-chat', name: 'DeepSeek Chat', contextWindow: 64000, maxTokens: 8192 } },
+  custom: { label: '自訂（手動填全部）', api: 'openai-completions', baseUrl: '', env: 'LLM_API_KEY', model: { id: '', name: '', contextWindow: 32000, maxTokens: 4096 } },
+};
+
+const PATH = () => process.env.XITTO_CODE_CONFIG || join(homedir(), '.xitto-code', 'providers.json');
+
+export { PRESETS };
+
+// 純函數：把答案組成 providers.json 結構（合併既有 providers）。互動殼與測試共用。
+export function buildConfig(a, existing) {
+  const cfg = existing && existing.providers ? existing : { defaultModel: a.modelId, providers: {} };
+  cfg.providers = cfg.providers || {};
+  cfg.providers[a.providerName] = {
+    baseUrl: a.baseUrl, apiKey: a.apiKey, api: a.api,
+    models: [{ id: a.modelId, name: a.modelName || a.modelId, contextWindow: a.contextWindow, maxTokens: a.maxTokens }],
+  };
+  cfg.defaultModel = a.modelId;
+  return cfg;
+}
+
+// pipe-safe 逐行讀取：把 'line' 事件排入佇列，即使管線一次送進整批輸入也能依序消費
+// （readline/promises 的 question() 在非 TTY 管線下會丟失已緩衝的行）。
+function makeAsker() {
+  const rl = createInterface({ input: process.stdin });
+  const queue = []; const waiters = []; let closed = false;
+  rl.on('line', (l) => { const w = waiters.shift(); if (w) w(l); else queue.push(l); });
+  rl.on('close', () => { closed = true; while (waiters.length) waiters.shift()(null); });
+  const nextLine = () => new Promise((res) => { if (queue.length) res(queue.shift()); else if (closed) res(null); else waiters.push(res); });
+  return {
+    close: () => rl.close(),
+    ask: async (q, def) => {
+      process.stdout.write(gray(q + (def ? ` [${def}]` : '') + ' '));
+      const line = await nextLine();
+      return ((line == null ? '' : line).trim()) || def || '';
+    },
+  };
+}
+
+export async function runInit(argv = []) {
+  const force = argv.includes('--force');
+  const path = PATH();
+  const io = makeAsker();
+  const rl = { close: io.close };
+  const ask = io.ask;
+
+  try {
+    console.log('\n' + bold('🚀 xitto-kernel 首次設定') + gray('  —— 建立 LLM provider 設定'));
+    console.log(gray(`設定檔：${path}\n`));
+
+    // 既有檔保護
+    if (existsSync(path) && !force) {
+      console.log(yellow(`已存在設定檔。`) + gray(' 用 `xitto-kernel init --force` 覆寫，或直接編輯該檔。'));
+      let cfg; try { cfg = JSON.parse(readFileSync(path, 'utf8')); } catch { /* 壞檔忽略 */ }
+      if (cfg) {
+        const names = Object.keys(cfg.providers || {});
+        console.log(gray(`  目前 provider：${names.join(', ') || '(無)'}　預設 model：${cfg.defaultModel || '(未設)'}`));
+      }
+      rl.close();
+      return;
+    }
+
+    // 1) 選 provider
+    const keys = Object.keys(PRESETS);
+    console.log(bold('1) 選 LLM provider：'));
+    keys.forEach((k, i) => console.log(`   ${cyan(String(i + 1))}. ${PRESETS[k].label}`));
+    const pick = await ask('輸入編號', '1');
+    const presetKey = keys[(parseInt(pick, 10) || 1) - 1] || 'minimax';
+    const preset = PRESETS[presetKey];
+    console.log(green(`   → ${preset.label}\n`));
+
+    // 2) 連線 / model
+    console.log(bold('2) 連線與 model：'));
+    const providerName = await ask('provider 名稱（providers.json 的鍵）', presetKey);
+    const baseUrl = await ask('baseUrl', preset.baseUrl);
+    const api = await ask('api 型別（anthropic-messages | openai-completions）', preset.api);
+    const modelId = await ask('model id', preset.model.id);
+    const modelName = await ask('model 顯示名', preset.model.name || modelId);
+    const contextWindow = parseInt(await ask('contextWindow', String(preset.model.contextWindow)), 10) || preset.model.contextWindow;
+    const maxTokens = parseInt(await ask('maxTokens', String(preset.model.maxTokens)), 10) || preset.model.maxTokens;
+    if (!modelId) { console.log(red('\nmodel id 不可空，已取消。')); rl.close(); return; }
+
+    // 3) API key：環境變數（建議）或內嵌
+    console.log('\n' + bold('3) API key：'));
+    console.log(gray('   a) 用環境變數參照（建議，金鑰不落地在設定檔）'));
+    console.log(gray('   b) 現在貼上金鑰（直接存進設定檔，檔案在你家目錄）'));
+    const mode = (await ask('選 a 或 b', 'a')).toLowerCase();
+    let apiKey; let envHint = '';
+    if (mode === 'b') {
+      const k = await ask('貼上 API key', '');
+      apiKey = k;
+      if (!k) console.log(yellow('   （未填，稍後請手動補上 apiKey）'));
+    } else {
+      const envName = await ask('環境變數名', preset.env);
+      apiKey = '${' + envName + '}';
+      envHint = envName;
+    }
+
+    // 組設定（保留既有 providers，--force 時合併）
+    let existing; if (existsSync(path)) { try { existing = JSON.parse(readFileSync(path, 'utf8')); } catch { /* 壞檔重建 */ } }
+    const cfg = buildConfig({ providerName, baseUrl, api, modelId, modelName, contextWindow, maxTokens, apiKey }, existing);
+
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+
+    console.log('\n' + green('✓ 已寫入 ') + path);
+    if (envHint) {
+      console.log('\n' + bold('下一步：設定環境變數（金鑰）'));
+      console.log(gray(`  export ${envHint}="你的金鑰"   # 加進 ~/.zshrc 永久生效`));
+    }
+    console.log('\n' + bold('啟動：'));
+    console.log(green('  xitto-kernel') + gray('               # coding pack，互動對話'));
+    console.log(green('  xitto-kernel --tui') + gray('         # 完整 Ink TUI（真實終端）'));
+    console.log(green('  xitto-kernel --pack general') + gray(' # 通用 agent'));
+    console.log('');
+  } finally {
+    rl.close();
+  }
+}

package/src/app/main.js

@@ -5,6 +5,7 @@ import { loadModel } from './providers.js';
 import { runCli } from './cli.js';
 import { runTui } from './tui-run.js';
 import { newAgent } from './scaffold.js';
+import { runInit } from './init.js';
 import { createKernel } from '../kernel/index.js';
 import { loadMcpTools } from '../kernel/mcp.js';
 import { createCodingPack } from '../packs/coding/index.js';
@@ -27,6 +28,9 @@ const PACKS = {
 };
 
 export async function main(argv = process.argv.slice(2)) {
+  // 子指令：init —— 首次設定導引，產生 providers.json
+  if (argv[0] === 'init') { await runInit(argv.slice(1)); return; }
+
   // 子指令：new-agent <name> —— 產出獨立 agent 專案（不碰 kernel）
   if (argv[0] === 'new-agent') {
     const name = argv.find((a, i) => i >= 1 && !a.startsWith('--'));
@@ -50,7 +54,26 @@ export async function main(argv = process.argv.slice(2)) {
 
   let model, getApiKey;
   try { ({ model, getApiKey } = loadModel(opts.model)); }
-  catch (err) { console.error('\x1b[31m' + err.message + '\x1b[0m'); process.exit(1); }
+  catch (err) {
+    // 沒設定 + 真實終端：直接帶進設定導引，完成後續跑；非 TTY 才只給提示
+    if (err.noConfig && process.stdin.isTTY) {
+      console.log(cyan('首次使用，沒找到 providers.json —— 進入設定導引。') + gray('（按 Ctrl+C 取消）'));
+      await runInit([]);
+      try { ({ model, getApiKey } = loadModel(opts.model)); }
+      catch (err2) {
+        console.error(red(err2.message));
+        console.error(gray(err2.noConfig ? '（未完成設定，已取消）' : '（設定好像缺東西，可編輯該檔或重跑 `xitto-kernel init`）'));
+        process.exit(1);
+      }
+    } else {
+      console.error(red(err.message));
+      if (err.noConfig) {
+        console.error('\n' + cyan('首次使用？') + ' 跑一次設定導引：');
+        console.error(green('  xitto-kernel init') + gray('   # 選 provider、填 model、設定 API key'));
+      }
+      process.exit(1);
+    }
+  }
 
   // MCP：啟動時連 .xitto-kernel/<pack>/mcp.json 的 server，工具以 extraTools 注入
   const cwd = process.cwd();
@@ -112,6 +135,7 @@ function printHelp() {
     'xitto-kernel — 領域無關 agent 底座',
     '',
     '用法:',
+    '  xitto-kernel init                                        首次設定導引（產生 providers.json）',
     '  xitto-kernel [--pack <name>] [--model <id>] [--sandbox] [--resume [id]] [--yes]   互動跑內建 pack',
     '  xitto-kernel --pack general --goal "..." [--yes]         目標驅動自主循環（headless）',
     '  xitto-kernel new-agent <name>                            產出依賴 kernel 的獨立 agent 專案',
@@ -125,7 +149,7 @@ function printHelp() {
     '  --yes, -y       自動核准 mutating 工具（headless / 自主循環常用）',
     '  --help          顯示說明',
     '',
-    '需要 ~/.xitto-code/providers.json（與 xitto-code 共用）。',
+    '首次使用先跑 `xitto-kernel init` 建立 ~/.xitto-code/providers.json（已是 xitto-code 使用者可直接共用）。',
     'new-agent 產出的是獨立專案，import xitto-kernel 而非修改它——升級不固化。',
   ].join('\n'));
 }

package/src/app/providers.js

@@ -7,7 +7,7 @@ import { join } from 'node:path';
 const DEFAULT_PATH = () => process.env.XITTO_CODE_CONFIG || join(homedir(), '.xitto-code', 'providers.json');
 
 export function loadProvidersConfig(path = DEFAULT_PATH()) {
-  if (!existsSync(path)) throw new Error(`找不到 providers.json：${path}\n（可複用 xitto-code 的 ~/.xitto-code/providers.json）`);
+  if (!existsSync(path)) { const err = new Error(`找不到 providers.json：${path}`); err.noConfig = true; throw err; }
   return { ...JSON.parse(readFileSync(path, 'utf8')), path };
 }