opc-agent 4.1.0 → 4.1.2

package/dist/cli.js

@@ -124,7 +124,7 @@ async function select(question, options) {
 program
     .name('opc')
     .description('OPC Agent - Open Agent Framework for business workstations')
-    .version('2.0.0');
+    .version(require('../package.json').version);
 // ── Init command ─────────────────────────────────────────────
 program
     .command('init')
@@ -186,7 +186,7 @@ program
         }
         const roleDisplayName = roleMeta.name || matched.role;
         const roleDescription = roleMeta.name_zh ? `${roleMeta.name} (${roleMeta.name_zh})` : (roleMeta.name || matched.role);
-        console.log(`  ${icon.info} Matched role: ${color.cyan(matched.category + '/' + matched.role)} — ${roleDisplayName}`);
+        console.log(`  ${icon.info} Matched role: ${color.cyan(matched.category + '/' + matched.role)} - ${roleDisplayName}`);
         // Create directories
         fs.mkdirSync(dir, { recursive: true });
         fs.mkdirSync(path.join(dir, 'src', 'skills'), { recursive: true });
@@ -205,9 +205,9 @@ program
         // Company-specific knowledge belongs to Desk (closed-source), not here.
         const workstationSeedFromRole = workstationMatch?.[0]?.trim() || '';
         fs.writeFileSync(path.join(dir, 'brain-seeds', 'workstation.md'), workstationSeedFromRole || `# Workstation Knowledge\n\n## Tools & Environment\n\nCommon tools and setup for this workstation role.\n\n## Workflows\n\nStandard operating procedures and workflows.\n\n## Best Practices\n\nIndustry best practices for this role.\n`);
-        // agent.yaml with role system prompt and brain seeds
+        // oad.yaml with role system prompt and brain seeds（不再生成 agent.yaml）
         const firstLine = systemPromptContent.split('\n').find((l) => l.trim() && !l.startsWith('#'))?.trim() || 'You are a helpful AI assistant.';
-        fs.writeFileSync(path.join(dir, 'agent.yaml'), `apiVersion: opc/v1
+        fs.writeFileSync(path.join(dir, 'oad.yaml'), `apiVersion: opc/v1
 kind: Agent
 metadata:
   name: ${name}
@@ -251,14 +251,14 @@ spec:
         if (roleData.files['oad.yaml']) {
             fs.writeFileSync(path.join(dir, 'oad.yaml'), roleData.files['oad.yaml']);
         }
-        // src/index.ts — entry point (same as generic)
+        // src/index.ts - entry point (same as generic)
         fs.writeFileSync(path.join(dir, 'src', 'index.ts'), `import { AgentRuntime } from 'opc-agent';
 import { EchoSkill } from './skills/echo';
 import { readFileSync, existsSync } from 'fs';
 
 async function main() {
   const runtime = new AgentRuntime();
-  const config = await runtime.loadConfig('./agent.yaml');
+  const config = await runtime.loadConfig('./oad.yaml');
 
   const soul = existsSync('./SOUL.md') ? readFileSync('./SOUL.md', 'utf-8') : '';
   const context = existsSync('./CONTEXT.md') ? readFileSync('./CONTEXT.md', 'utf-8') : '';
@@ -305,15 +305,15 @@ export class EchoSkill extends BaseSkill {
         fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name, version: '1.0.0', private: true, scripts: { start: 'opc run', dev: 'opc dev', chat: 'opc chat', build: 'tsc' }, dependencies: { 'opc-agent': '^1.3.0' }, devDependencies: { typescript: '^5.5.0', tsx: '^4.0.0' } }, null, 2));
         // .gitignore, .env.example, .env
         fs.writeFileSync(path.join(dir, '.gitignore'), 'node_modules\ndist\n.env\n.opc-knowledge.json\ndata/\n');
-        fs.writeFileSync(path.join(dir, '.env.example'), `# LLM API Configuration\nOPC_LLM_API_KEY=your-api-key-here\nOPC_LLM_BASE_URL=https://api.openai.com/v1\nOPC_LLM_MODEL=gpt-4o-mini\n`);
-        fs.writeFileSync(path.join(dir, '.env'), `OPC_LLM_API_KEY=your-api-key-here\nOPC_LLM_BASE_URL=https://api.openai.com/v1\nOPC_LLM_MODEL=gpt-4o-mini\n`);
+        fs.writeFileSync(path.join(dir, '.env.example'), `# LLM API Configuration\n# Ollama (免费本地，默认，无需 API key):\nOPC_LLM_BASE_URL=http://localhost:11434/v1\nOPC_LLM_MODEL=qwen2.5\n\n# 如需使用商业模型，取消以下注释:\n# OPC_LLM_API_KEY=your-api-key-here\n# OPC_LLM_BASE_URL=https://api.deepseek.com/v1\n# OPC_LLM_MODEL=deepseek-chat\n`);
+        fs.writeFileSync(path.join(dir, '.env'), `# Ollama (免费本地) - 无需 API key\nOPC_LLM_BASE_URL=http://localhost:11434/v1\nOPC_LLM_MODEL=qwen2.5\n`);
         // README.md
         fs.writeFileSync(path.join(dir, 'README.md'), `# ${name}\n\nCreated with [OPC Agent](https://github.com/Deepleaper/opc-agent) using the \`${matched.category}/${matched.role}\` workstation role.\n\n## Quick Start\n\n\`\`\`bash\nnpm install\nollama pull qwen2.5\nnpx tsx src/index.ts\n\`\`\`\n\nOpen [http://localhost:3000](http://localhost:3000)\n`);
         // Dockerfile + docker-compose
-        fs.writeFileSync(path.join(dir, 'Dockerfile'), `FROM node:22-alpine\nWORKDIR /app\nCOPY package.json package-lock.json* ./\nRUN npm ci --production 2>/dev/null || npm install --production\nCOPY oad.yaml agent.yaml .env* ./\nCOPY src/ ./src/\nCOPY prompts/ ./prompts/ 2>/dev/null || true\nEXPOSE 3000\nCMD ["npx", "opc", "run"]\n`);
-        fs.writeFileSync(path.join(dir, 'docker-compose.yml'), `version: '3.8'\nservices:\n  agent:\n    build: .\n    ports:\n      - "3000:3000"\n    env_file:\n      - .env\n    volumes:\n      - ./agent.yaml:/app/agent.yaml:ro\n    restart: unless-stopped\n`);
+        fs.writeFileSync(path.join(dir, 'Dockerfile'), `FROM node:22-alpine\nWORKDIR /app\nCOPY package.json package-lock.json* ./\nRUN npm ci --production 2>/dev/null || npm install --production\nCOPY oad.yaml .env* ./\nCOPY src/ ./src/\nCOPY prompts/ ./prompts/ 2>/dev/null || true\nEXPOSE 3000\nCMD ["npx", "opc", "run"]\n`);
+        fs.writeFileSync(path.join(dir, 'docker-compose.yml'), `version: '3.8'\nservices:\n  agent:\n    build: .\n    ports:\n      - "3000:3000"\n    env_file:\n      - .env\n    volumes:\n      - ./oad.yaml:/app/oad.yaml:ro\n    restart: unless-stopped\n`);
         console.log(`\n${icon.success} Created agent project: ${color.bold(name + '/')} from role ${color.cyan(matched.category + '/' + matched.role)}`);
-        console.log(`   ${icon.file} agent.yaml       - Agent definition with role system prompt`);
+        console.log(`   ${icon.file} oad.yaml         - Agent definition with role system prompt`);
         console.log(`   ${icon.file} SOUL.md          - Role personality (${systemPromptContent.split('\n').length} lines)`);
         console.log(`   ${icon.file} CONTEXT.md       - Role context & documentation`);
         console.log(`   ${icon.file} brain-seeds/     - 3-tier brain seed knowledge`);
@@ -344,7 +344,7 @@ export class EchoSkill extends BaseSkill {
         }
     }
     catch {
-        // Hub unreachable — fall back to bundled templates
+        // Hub unreachable - fall back to bundled templates
     }
     let template;
     let selectedHubTemplate;
@@ -364,6 +364,116 @@ export class EchoSkill extends BaseSkill {
     else {
         template = await select('Select a template:', Object.entries(TEMPLATES).map(([value, { label }]) => ({ value, label })));
     }
+    // ── LLM Provider 选择（Ollama-first）──
+    let llmProvider = 'ollama';
+    let llmModel = 'qwen2.5';
+    let llmBaseUrl = 'http://localhost:11434/v1';
+    let llmApiKey = '';
+    let ollamaRunning = false;
+    let modelNames = [];
+    // 无论 --yes 还是交互式，都先检测 Ollama
+    try {
+        const controller = new AbortController();
+        const ollamaTimeout = setTimeout(() => controller.abort(), 3000);
+        const ollamaRes = await fetch('http://localhost:11434/api/tags', { signal: controller.signal });
+        clearTimeout(ollamaTimeout);
+        const ollamaData = await ollamaRes.json();
+        modelNames = (ollamaData.models || []).map((m) => m.name || m.model);
+        ollamaRunning = true;
+        if (opts.yes && modelNames.length > 0) {
+            // --yes 模式：自动选第一个已有模型
+            llmModel = modelNames[0];
+        }
+    }
+    catch {
+        ollamaRunning = false;
+    }
+    if (!opts.yes) {
+        if (ollamaRunning) {
+            console.log(`\n  ${icon.info} ${color.dim('正在检测 Ollama...')}`);
+            console.log(`  ${icon.success} Ollama 已运行，发现 ${modelNames.length} 个模型`);
+            // 选择 provider
+            llmProvider = await select('选择 LLM 引擎:', [
+                { value: 'ollama', label: '🟢 Ollama (免费本地，推荐) - 已检测到运行中' },
+                { value: 'deepseek', label: '🔵 DeepSeek - 高性价比国产模型' },
+                { value: 'openai', label: '⚪ OpenAI (GPT-4o)' },
+                { value: 'anthropic', label: '🟣 Anthropic (Claude)' },
+                { value: 'custom', label: '⚙️  自定义 (手动输入 Base URL)' },
+            ]);
+            if (llmProvider === 'ollama') {
+                // 选择本地模型
+                const defaultModel = modelNames.includes('qwen2.5') ? 'qwen2.5' : (modelNames.includes('llama3') ? 'llama3' : (modelNames[0] || 'qwen2.5'));
+                if (modelNames.length > 0) {
+                    llmModel = await select('选择 Ollama 模型:', modelNames.map((m) => ({ value: m, label: m + (m === defaultModel ? ' (推荐)' : '') })));
+                }
+                else {
+                    console.log(`  ${color.yellow('⚠️')}  没有发现已下载的模型，将使用默认 qwen2.5`);
+                    console.log(`     运行 ${color.cyan('ollama pull qwen2.5')} 下载模型`);
+                    llmModel = 'qwen2.5';
+                }
+            }
+        }
+        else {
+            // Ollama not running
+            console.log(`\n  ${icon.info} ${color.dim('正在检测 Ollama...')}`);
+            console.log(`  ${color.yellow('⚠️')}  Ollama 未运行或未安装`);
+            llmProvider = await select('选择 LLM 引擎:', [
+                { value: 'ollama', label: '🟢 Ollama (免费本地，推荐) - 需先安装: https://ollama.ai' },
+                { value: 'deepseek', label: '🔵 DeepSeek - 高性价比国产模型' },
+                { value: 'openai', label: '⚪ OpenAI (GPT-4o)' },
+                { value: 'anthropic', label: '🟣 Anthropic (Claude)' },
+                { value: 'custom', label: '⚙️  自定义 (手动输入 Base URL)' },
+            ]);
+            if (llmProvider === 'ollama') {
+                console.log(`\n  ${icon.info} Ollama 安装指南:`);
+                console.log(`     1. 访问 ${color.cyan('https://ollama.ai')} 下载并安装`);
+                console.log(`     2. 运行 ${color.cyan('ollama pull qwen2.5')} 下载推荐模型`);
+                console.log(`     3. 然后 ${color.cyan('opc run')} 即可开始对话\n`);
+                llmModel = 'qwen2.5';
+            }
+        }
+        // 商业模型需要 API key
+        if (llmProvider === 'deepseek') {
+            llmBaseUrl = 'https://api.deepseek.com/v1';
+            llmModel = 'deepseek-chat';
+            llmApiKey = await promptUser('输入 DeepSeek API Key (可稍后在 .env 中配置，直接回车跳过)');
+            if (!llmApiKey) {
+                console.log(`  ${icon.info} 稍后在 ${color.cyan('.env')} 文件中设置 ${color.bold('OPC_LLM_API_KEY')}`);
+            }
+        }
+        else if (llmProvider === 'openai') {
+            llmBaseUrl = 'https://api.openai.com/v1';
+            llmModel = 'gpt-4o-mini';
+            llmApiKey = await promptUser('输入 OpenAI API Key (可稍后在 .env 中配置，直接回车跳过)');
+            if (!llmApiKey) {
+                console.log(`  ${icon.info} 稍后在 ${color.cyan('.env')} 文件中设置 ${color.bold('OPC_LLM_API_KEY')}`);
+            }
+        }
+        else if (llmProvider === 'anthropic') {
+            llmBaseUrl = 'https://api.anthropic.com/v1';
+            llmModel = 'claude-sonnet-4-20250514';
+            llmApiKey = await promptUser('输入 Anthropic API Key (可稍后在 .env 中配置，直接回车跳过)');
+            if (!llmApiKey) {
+                console.log(`  ${icon.info} 稍后在 ${color.cyan('.env')} 文件中设置 ${color.bold('OPC_LLM_API_KEY')}`);
+            }
+        }
+        else if (llmProvider === 'custom') {
+            llmBaseUrl = await promptUser('输入 Base URL', 'http://localhost:11434/v1');
+            llmModel = await promptUser('输入模型名称', 'qwen2.5');
+            llmApiKey = await promptUser('输入 API Key (可选，直接回车跳过)');
+            // 尝试推断 provider
+            if (llmBaseUrl.includes('deepseek.com'))
+                llmProvider = 'deepseek';
+            else if (llmBaseUrl.includes('openai.com'))
+                llmProvider = 'openai';
+            else if (llmBaseUrl.includes('anthropic.com'))
+                llmProvider = 'anthropic';
+            else if (llmBaseUrl.includes('localhost:11434'))
+                llmProvider = 'ollama';
+            else
+                llmProvider = 'openai'; // OpenAI-compatible fallback
+        }
+    }
     const dir = path.resolve(name);
     if (fs.existsSync(dir)) {
         console.error(`\n${icon.error} Directory ${color.bold(name)} already exists.`);
@@ -374,37 +484,16 @@ export class EchoSkill extends BaseSkill {
     const factory = TEMPLATES[template]?.factory ?? customer_service_1.createCustomerServiceConfig;
     const config = factory();
     config.metadata.name = name;
+    // 用用户选择的 provider 和 model 覆盖模板默认值
+    config.spec.model = llmModel;
+    config.spec.provider = { default: llmProvider };
     // Ensure web channel exists
     if (!config.spec.channels.some((c) => c.type === 'web')) {
         config.spec.channels.push({ type: 'web', port: 3000 });
     }
+    // 只生成 oad.yaml，不生成 agent.yaml
     fs.writeFileSync(path.join(dir, 'oad.yaml'), yaml.dump(config, { lineWidth: 120 }));
-    // agent.yaml — standalone OAD config for runtime usage
-    fs.writeFileSync(path.join(dir, 'agent.yaml'), `apiVersion: opc/v1
-kind: Agent
-metadata:
-  name: ${name}
-  version: 1.0.0
-  description: My AI Agent
-spec:
-  model: qwen2.5
-  provider:
-    default: ollama
-  systemPrompt: |
-    You are a helpful AI assistant named ${name}.
-    Be concise, helpful, and friendly.
-  channels:
-    - type: web
-      port: 3000
-  memory:
-    shortTerm: true
-    longTerm:
-      provider: deepbrain
-  skills:
-    - name: echo
-      description: Echo test skill
-`);
-    // src/index.ts — entry point
+    // src/index.ts - entry point
     fs.writeFileSync(path.join(dir, 'src', 'index.ts'), `import { AgentRuntime } from 'opc-agent';
 import { EchoSkill } from './skills/echo';
 import { readFileSync, existsSync } from 'fs';
@@ -413,7 +502,7 @@ async function main() {
   const runtime = new AgentRuntime();
 
   // Load OAD config
-  const config = await runtime.loadConfig('./agent.yaml');
+  const config = await runtime.loadConfig('./oad.yaml');
 
   // Load personality and context files
   const soul = existsSync('./SOUL.md') ? readFileSync('./SOUL.md', 'utf-8') : '';
@@ -439,7 +528,7 @@ async function main() {
 
 main().catch(console.error);
 `);
-    // src/skills/echo.ts — example skill
+    // src/skills/echo.ts - example skill
     fs.writeFileSync(path.join(dir, 'src', 'skills', 'echo.ts'), `import { BaseSkill } from 'opc-agent';
 import type { AgentContext, Message, SkillResult } from 'opc-agent';
 
@@ -477,23 +566,39 @@ export class EchoSkill extends BaseSkill {
     }, null, 2));
     // .env.example
     fs.writeFileSync(path.join(dir, '.env.example'), `# LLM API Configuration
-OPC_LLM_API_KEY=your-api-key-here
-OPC_LLM_BASE_URL=https://api.openai.com/v1
-OPC_LLM_MODEL=gpt-4o-mini
+# Ollama (免费本地，默认):
+# OPC_LLM_BASE_URL=http://localhost:11434/v1
+# OPC_LLM_MODEL=qwen2.5
+# (Ollama 无需 API key)
 
-# For DeepSeek:
+# DeepSeek:
+# OPC_LLM_API_KEY=your-deepseek-key
 # OPC_LLM_BASE_URL=https://api.deepseek.com/v1
 # OPC_LLM_MODEL=deepseek-chat
 
-# For local Ollama (default in agent.yaml):
-# OPC_LLM_BASE_URL=http://localhost:11434/v1
-# OPC_LLM_MODEL=qwen2.5
-`);
-    // .env (copy of example)
-    fs.writeFileSync(path.join(dir, '.env'), `OPC_LLM_API_KEY=your-api-key-here
-OPC_LLM_BASE_URL=https://api.openai.com/v1
-OPC_LLM_MODEL=gpt-4o-mini
+# OpenAI:
+# OPC_LLM_API_KEY=your-openai-key
+# OPC_LLM_BASE_URL=https://api.openai.com/v1
+# OPC_LLM_MODEL=gpt-4o-mini
+
+# Anthropic:
+# OPC_LLM_API_KEY=your-anthropic-key
+# OPC_LLM_BASE_URL=https://api.anthropic.com/v1
+# OPC_LLM_MODEL=claude-sonnet-4-20250514
 `);
+    // .env - 根据用户选择生成正确的配置
+    const envLines = [];
+    if (llmProvider === 'ollama') {
+        envLines.push('# Ollama (免费本地) - 无需 API key');
+        envLines.push(`OPC_LLM_BASE_URL=${llmBaseUrl}`);
+        envLines.push(`OPC_LLM_MODEL=${llmModel}`);
+    }
+    else {
+        envLines.push(`OPC_LLM_API_KEY=${llmApiKey || 'your-api-key-here'}`);
+        envLines.push(`OPC_LLM_BASE_URL=${llmBaseUrl}`);
+        envLines.push(`OPC_LLM_MODEL=${llmModel}`);
+    }
+    fs.writeFileSync(path.join(dir, '.env'), envLines.join('\n') + '\n');
     // package.json
     fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({
         name,
@@ -520,7 +625,7 @@ OPC_LLM_MODEL=gpt-4o-mini
 WORKDIR /app
 COPY package.json package-lock.json* ./
 RUN npm ci --production 2>/dev/null || npm install --production
-COPY oad.yaml agent.yaml .env* ./
+COPY oad.yaml .env* ./
 COPY src/ ./src/
 COPY prompts/ ./prompts/ 2>/dev/null || true
 EXPOSE 3000
@@ -536,7 +641,7 @@ services:
     env_file:
       - .env
     volumes:
-      - ./agent.yaml:/app/agent.yaml:ro
+      - ./oad.yaml:/app/oad.yaml:ro
     restart: unless-stopped
 `);
     // README.md
@@ -577,8 +682,7 @@ npx opc chat   # CLI chat
 
 \`\`\`
 ${name}/
-├── agent.yaml          # OAD agent config (used by src/index.ts)
-├── oad.yaml            # OAD config (used by opc CLI)
+├── oad.yaml            # Agent 配置 (唯一配置文件)
 ├── src/
 │   ├── index.ts        # Entry point
 │   └── skills/
@@ -589,9 +693,9 @@ ${name}/
 
 ## Configuration
 
-Edit \`agent.yaml\` to customize your agent's personality, skills, and behavior.
+Edit \`oad.yaml\` to customize your agent's personality, skills, and behavior.
 `);
-    // SOUL.md — agent personality
+    // SOUL.md - agent personality
     const createdDate = new Date().toISOString().split('T')[0];
     fs.writeFileSync(path.join(dir, 'SOUL.md'), `# ${name} Personality
 
@@ -607,7 +711,7 @@ Edit \`agent.yaml\` to customize your agent's personality, skills, and behavior.
 
 ## Communication Style
 - Use clear, simple language
-- Be direct — answer the question first, then explain
+- Be direct - answer the question first, then explain
 - Use markdown formatting when helpful
 
 ## Rules
@@ -615,7 +719,7 @@ Edit \`agent.yaml\` to customize your agent's personality, skills, and behavior.
 - Ask for clarification when the request is ambiguous
 - Never make up information
 `);
-    // CONTEXT.md — project context
+    // CONTEXT.md - project context
     fs.writeFileSync(path.join(dir, 'CONTEXT.md'), `# Project Context
 
 ## About This Agent
@@ -631,7 +735,8 @@ on startup to understand the project context.
 - Add company policies here
 `);
     console.log(`\n${icon.success} Created agent project: ${color.bold(name + '/')}`);
-    console.log(`   ${icon.file} agent.yaml       - Agent definition (OAD)`);
+    console.log(`   ${icon.file} oad.yaml         - Agent 配置 (${llmProvider}/${llmModel})`);
+    console.log(`   ${icon.file} .env             - 环境变量${llmProvider === 'ollama' ? '' : ' (API Key)'}`);
     console.log(`   ${icon.file} src/index.ts     - Entry point`);
     console.log(`   ${icon.file} src/skills/echo.ts - Example skill`);
     console.log(`   ${icon.file} SOUL.md          - Agent personality`);
@@ -656,14 +761,24 @@ on startup to understand the project context.
             }
         }
         catch {
-            // Brain-seed download failed — non-fatal, project still usable
+            // Brain-seed download failed - non-fatal, project still usable
         }
     }
     console.log(`\n${color.bold('Next steps:')}`);
     console.log(`   1. cd ${name}`);
     console.log(`   2. npm install`);
-    console.log(`   3. npx tsx src/index.ts   ${color.dim('# or: npx opc run')}`);
-    console.log(`   4. Open http://localhost:3000\n`);
+    if (llmProvider === 'ollama' && !ollamaRunning) {
+        console.log(`   3. ollama pull ${llmModel}   ${color.dim('# 下载模型')}`);
+        console.log(`   4. npx opc run              ${color.dim('# 启动 Agent')}`);
+    }
+    else if (llmProvider !== 'ollama' && !llmApiKey) {
+        console.log(`   3. 编辑 .env 设置 OPC_LLM_API_KEY`);
+        console.log(`   4. npx opc run`);
+    }
+    else {
+        console.log(`   3. npx opc run              ${color.dim('# 启动 Agent')}`);
+    }
+    console.log(`   Open http://localhost:3000\n`);
     console.log(`${color.dim('💡 Tip: Use --role to start from a workstation template:')}`);
     console.log(`${color.dim('   opc init my-agent --role customer-service')}`);
     console.log(`${color.dim('   opc init --list-roles  (see all roles)')}\n`);
@@ -713,7 +828,7 @@ program
     // Print startup banner
     const bannerLines = [
         '╔══════════════════════════════════════╗',
-        '║  🤖 OPC Agent — Interactive Chat     ║',
+        '║  🤖 OPC Agent - Interactive Chat     ║',
         `║  Agent: ${(agentName + ' v' + agentVersion).padEnd(27)}║`,
         `║  Model: ${((providerName + '/' + (model ?? 'default')).slice(0, 27)).padEnd(27)}║`,
         `║  Skills: ${(String(skillNames.length) + ' loaded').padEnd(26)}║`,
@@ -740,12 +855,12 @@ program
         }
         if (lower === '/help') {
             console.log(`\n  ${color.bold('Available commands:')}`);
-            console.log(`  ${color.cyan('/help')}    — Show this help`);
-            console.log(`  ${color.cyan('/quit')}    — Exit chat (/exit also works)`);
-            console.log(`  ${color.cyan('/clear')}   — Clear conversation history`);
-            console.log(`  ${color.cyan('/skills')}  — List registered skills`);
-            console.log(`  ${color.cyan('/memory')}  — Show memory stats`);
-            console.log(`  ${color.cyan('/info')}    — Show agent info\n`);
+            console.log(`  ${color.cyan('/help')}    - Show this help`);
+            console.log(`  ${color.cyan('/quit')}    - Exit chat (/exit also works)`);
+            console.log(`  ${color.cyan('/clear')}   - Clear conversation history`);
+            console.log(`  ${color.cyan('/skills')}  - List registered skills`);
+            console.log(`  ${color.cyan('/memory')}  - Show memory stats`);
+            console.log(`  ${color.cyan('/info')}    - Show agent info\n`);
             return true;
         }
         if (lower === '/clear') {
@@ -1460,7 +1575,7 @@ protocolCmd.command('list')
     const protocols = config?.spec?.protocols || {};
     const items = [
         { name: 'a2a', description: 'Agent-to-Agent protocol', enabled: !!protocols.a2a?.enabled, detail: protocols.a2a?.port ? `port ${protocols.a2a.port}` : '' },
-        { name: 'agui', description: 'AG-UI — Agent-User Interaction (SSE)', enabled: !!protocols.agui?.enabled, detail: protocols.agui?.path || '/agui' },
+        { name: 'agui', description: 'AG-UI - Agent-User Interaction (SSE)', enabled: !!protocols.agui?.enabled, detail: protocols.agui?.path || '/agui' },
     ];
     console.log(`\n${icon.gear} ${color.bold('Protocols')}\n`);
     for (const p of items) {
@@ -1593,7 +1708,7 @@ brainCmd
     .description('Show brain stats (pages, tiers, last evolve)')
     .option('--url <url>', 'DeepBrain server URL', 'http://localhost:3333')
     .action(async (opts) => {
-    console.log(`\n${icon.gear} ${color.bold('DeepBrain Status')} — ${color.dim(opts.url)}\n`);
+    console.log(`\n${icon.gear} ${color.bold('DeepBrain Status')} - ${color.dim(opts.url)}\n`);
     try {
         const res = await fetch(`${opts.url}/api/stats`);
         if (!res.ok)
@@ -1626,7 +1741,7 @@ brainCmd
 brainCmd
     .command('seed')
     .description('Import brain seed files into memory')
-    .option('-f, --file <file>', 'OAD file', 'agent.yaml')
+    .option('-f, --file <file>', 'OAD file', 'oad.yaml')
     .option('--status', 'Check if seeds have been imported')
     .option('--reset', 'Re-import seeds (clear marker and re-seed)')
     .action(async (opts) => {
@@ -1696,7 +1811,7 @@ brainCmd
             console.log(`  ${color.cyan(c.slug)} → ${c.fromTier} → ${c.toTier} (confidence: ${(c.confidence * 100).toFixed(0)}%)`);
         }
         if (opts.dryRun) {
-            console.log(`\n  ${icon.info} Dry run — no changes made.\n`);
+            console.log(`\n  ${icon.info} Dry run - no changes made.\n`);
         }
         else {
             console.log(`\n  ${icon.success} Promoted ${result.promoted} knowledge entries.\n`);
@@ -2145,7 +2260,7 @@ program
         return;
     }
     // Create a minimal mock agent for eval (real usage would load from OAD)
-    const oadPath = path.resolve('agent.yaml');
+    const oadPath = path.resolve(fs.existsSync('oad.yaml') ? 'oad.yaml' : 'agent.yaml');
     let agent;
     if (fs.existsSync(oadPath)) {
         const runtime = new runtime_1.AgentRuntime();
@@ -2154,7 +2269,7 @@ program
         agent = runtime.agent;
     }
     if (!agent) {
-        console.log(`${icon.warn} No agent.yaml found — running with dry-run mock agent.`);
+        console.log(`${icon.warn} No oad.yaml or agent.yaml found - running with dry-run mock agent.`);
         agent = { chat: async (input) => `[mock response to: ${input}]` };
     }
     const evaluator = new eval_1.AgentEvaluator(agent);
@@ -2214,7 +2329,7 @@ guardrailsCmd
     console.log();
     const result = await manager.checkInput(message);
     if (result.passed) {
-        console.log(color.green('✓ PASSED — no violations'));
+        console.log(color.green('✓ PASSED - no violations'));
     }
     else {
         if (result.blocked)
@@ -2243,7 +2358,7 @@ program
     .action(async (opts) => {
     console.log(color.bold('🎤 Voice Conversation Mode'));
     console.log(`  STT: ${opts.stt} | TTS: ${opts.tts} | Voice: ${opts.voice ?? 'default'} | Language: ${opts.language}`);
-    console.log(color.dim('  (Voice conversation requires audio input integration — use as library)'));
+    console.log(color.dim('  (Voice conversation requires audio input integration - use as library)'));
     console.log();
     console.log('To use voice in your agent:');
     console.log(color.cyan(`
@@ -2307,7 +2422,7 @@ keysCmd
 });
 // ── Approve command ───────────────────────────────────────────
 const approveCmd = program.command('approve').description('Manage command approvals');
-// Singleton for CLI — in real usage this would be loaded from daemon state
+// Singleton for CLI - in real usage this would be loaded from daemon state
 const approvalManager = new approval_1.ApprovalManager();
 approveCmd
     .command('list')
@@ -2439,7 +2554,7 @@ a2aCmd
     const { oadToAgentCard } = require('./protocols/a2a');
     const oad = loadOADFile();
     if (!oad) {
-        console.log(`${icon.error} No agent.yaml found`);
+        console.log(`${icon.error} No oad.yaml or agent.yaml found`);
         return;
     }
     const card = oadToAgentCard(oad, 'http://localhost:3001');
@@ -2479,7 +2594,7 @@ a2aCmd
 function loadOADFile() {
     const fs = require('fs');
     const yaml = require('js-yaml');
-    for (const name of ['agent.yaml', 'agent.yml']) {
+    for (const name of ['oad.yaml', 'agent.yaml', 'agent.yml']) {
         if (fs.existsSync(name)) {
             return yaml.load(fs.readFileSync(name, 'utf-8'));
         }
@@ -2487,7 +2602,7 @@ function loadOADFile() {
     return null;
 }
 // ── MCP Server Commands ────────────────────────────────────
-const mcpCmd = program.command('mcp').description('MCP server commands — expose agent as MCP tools');
+const mcpCmd = program.command('mcp').description('MCP server commands - expose agent as MCP tools');
 mcpCmd
     .command('serve')
     .option('--http <port>', 'Start HTTP+SSE mode on given port')
@@ -2516,7 +2631,7 @@ mcpCmd
         console.log(`${icon.info} Tools: ${server.getToolCount()}`);
     }
     else {
-        console.error(`${icon.success} MCP server (stdio) started — ${server.getToolCount()} tools`);
+        console.error(`${icon.success} MCP server (stdio) started - ${server.getToolCount()} tools`);
         await server.serveStdio();
     }
 });
@@ -2565,7 +2680,7 @@ mcpCmd
         console.log(`${icon.info} Tools: ${server.getToolCount()}`);
     }
     else {
-        console.error(`${icon.success} MCP server ${color.cyan(name)} (stdio) — ${server.getToolCount()} tools`);
+        console.error(`${icon.success} MCP server ${color.cyan(name)} (stdio) - ${server.getToolCount()} tools`);
         await server.serveStdio();
     }
 });

package/dist/core/runtime.js

@@ -74,25 +74,39 @@ class AgentRuntime {
     evolveScheduler = null;
     async loadConfig(filePath) {
         const fs = require('fs');
+        const path = require('path');
+        // 如果指定文件不存在，尝试 fallback
         if (!fs.existsSync(filePath)) {
-            // Auto-create a minimal oad.yaml with auto-detect provider
-            const yaml = require('js-yaml');
-            const defaultOAD = {
-                apiVersion: 'opc/v1',
-                kind: 'Agent',
-                metadata: { name: 'my-agent', version: '1.0.0', description: 'OPC Agent' },
-                spec: {
-                    model: 'auto',
-                    provider: { default: 'auto' },
-                    systemPrompt: 'You are a helpful AI assistant.',
-                    channels: [{ type: 'web', config: { port: 3000 } }],
-                },
-            };
-            fs.writeFileSync(filePath, yaml.dump(defaultOAD, { lineWidth: 120 }));
-            this.logger.info('Created default oad.yaml (no config file found)');
+            // 如果发现旧的 agent.yaml，提示迁移
+            if (filePath === 'oad.yaml' && fs.existsSync('agent.yaml')) {
+                this.logger.warn('⚠️  发现 agent.yaml 但未找到 oad.yaml。建议运行 `opc migrate` 统一为 oad.yaml。');
+                this.logger.info('暂时使用 agent.yaml 加载配置...');
+                filePath = 'agent.yaml';
+            }
+            else {
+                // Auto-create a minimal oad.yaml with auto-detect provider
+                const yaml = require('js-yaml');
+                const defaultOAD = {
+                    apiVersion: 'opc/v1',
+                    kind: 'Agent',
+                    metadata: { name: 'my-agent', version: '1.0.0', description: 'OPC Agent' },
+                    spec: {
+                        model: 'auto',
+                        provider: { default: 'auto' },
+                        systemPrompt: 'You are a helpful AI assistant.',
+                        channels: [{ type: 'web', config: { port: 3000 } }],
+                    },
+                };
+                fs.writeFileSync(filePath, yaml.dump(defaultOAD, { lineWidth: 120 }));
+                this.logger.info('Created default oad.yaml (no config file found)');
+            }
         }
         this.config = (0, config_1.loadOAD)(filePath);
         this.logger.info('Config loaded', { name: this.config.metadata.name });
+        // 如果同时存在 agent.yaml 和 oad.yaml，提示用户清理
+        if (fs.existsSync('agent.yaml') && fs.existsSync('oad.yaml')) {
+            this.logger.warn('⚠️  同时存在 agent.yaml 和 oad.yaml。建议删除 agent.yaml，统一使用 oad.yaml。');
+        }
         return this.config;
     }
     setHistoryLimit(limit) {
@@ -128,6 +142,14 @@ class AgentRuntime {
         const cfg = config ?? this.config;
         if (!cfg)
             throw new Error('No config loaded. Call loadConfig() first.');
+        // 检查 API key 是否为占位符，启动时警告
+        const apiKey = process.env.OPC_LLM_API_KEY;
+        const cfgProvider = cfg.spec.provider?.default;
+        if (cfgProvider !== 'ollama' && cfgProvider !== 'auto') {
+            if (!apiKey || apiKey === 'your-api-key-here') {
+                this.logger.warn('⚠️  API Key 未配置或仍是占位符。请编辑 .env 文件设置 OPC_LLM_API_KEY。');
+            }
+        }
         let memory;
         const memCfg = cfg.spec.memory;
         if (memCfg && typeof memCfg.longTerm === 'object' && memCfg.longTerm.provider === 'deepbrain') {