aranea-sdk-cli 0.3.2 → 0.3.3

package/README.md

@@ -38,6 +38,29 @@ aranea-sdk metatron chat
 2. **新知見発見時**: `knowledge add` でナレッジベースに追加
 3. **デバイス登録時**: `register --dry-run` で検証後、実登録
 
+### 🔴 特に貴重なナレッジ（必ず追加すべき）
+
+以下の情報は一般ドキュメントでは得られない**実践的知見**です。
+発見次第、CLIでナレッジベースに追加してください：
+
+| カテゴリ | 追加すべき情報 | 例 |
+|---------|--------------|-----|
+| `incident` | ハードウェア固有の問題・解決策 | メモリ不足でクラッシュ、タイムアウトエラー |
+| `tip` | テスト・デバッグで追い込んだパラメータ | HTTPSタイムアウト15秒必要 |
+| `tip` | ESP32メモリ関連設定 | SSL接続に50KB必要 |
+| `tip` | SBC (OrangePi等) のサービス起動・権限問題 | systemd設定、sudoers設定 |
+| `incident` | ハードウェア相性問題 | 特定WiFiモジュールとの非互換 |
+
+```bash
+# 例: インシデント対応で発見した設定値を追加
+aranea-sdk knowledge add \
+  --title "ESP32 HTTPSタイムアウト 15秒必要" \
+  --category tip \
+  --content "ESP32でHTTPS接続する場合、最低15秒のタイムアウトが必要。初回SSL handshakeは特に時間がかかる。-11 READ_TIMEOUTエラーの原因。" \
+  --keywords "esp32,https,timeout,ssl,handshake" \
+  --device-types "aranea_ar-is04a,aranea_ar-is05a"
+```
+
 ---
 
 ## 概要

package/dist/commands/knowledge.js

@@ -54,10 +54,17 @@ const ora_1 = __importDefault(require("ora"));
 const axios_1 = __importDefault(require("axios"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const config_1 = require("../config");
 // ============================================================================
 // Config
 // ============================================================================
-const KNOWLEDGE_API_BASE = 'https://asia-northeast1-mobesorder.cloudfunctions.net/araneaSDK_knowledgeManagement';
+const KNOWLEDGE_API_ENDPOINTS = {
+    production: 'https://asia-northeast1-mobesorder.cloudfunctions.net/araneaKnowledgeManagement',
+    staging: 'https://asia-northeast1-mobesorder-staging.cloudfunctions.net/araneaKnowledgeManagement',
+};
+function getKnowledgeApiBase(env) {
+    return KNOWLEDGE_API_ENDPOINTS[env];
+}
 // カテゴリ定義
 const CATEGORIES = ['api', 'guide', 'code', 'reference', 'incident', 'tip'];
 // ============================================================================
@@ -72,8 +79,9 @@ function getAuthToken() {
 /**
  * API呼び出し（Callable形式）
  */
-async function callKnowledgeAPI(action, params, token) {
-    const response = await axios_1.default.post(KNOWLEDGE_API_BASE, { data: { action, ...params } }, {
+async function callKnowledgeAPI(action, params, token, env) {
+    const apiBase = getKnowledgeApiBase(env);
+    const response = await axios_1.default.post(apiBase, { data: { action, ...params } }, {
         headers: {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${token}`,
@@ -131,9 +139,12 @@ exports.knowledgeCommand
     .option('--device-types <types>', '関連デバイスタイプ (カンマ区切り)')
     .option('--status <status>', 'ステータス (draft|published)', 'draft')
     .option('--token <token>', '認証トークン')
+    .option('-e, --endpoint <env>', '環境 (staging|production)', 'production')
     .action(async (options) => {
     try {
-        console.log(chalk_1.default.bold('\n=== Knowledge Add ===\n'));
+        const env = (0, config_1.resolveEnvironment)(options.endpoint);
+        (0, config_1.warnIfProduction)(env, 'knowledge add');
+        console.log(chalk_1.default.bold(`\n=== Knowledge Add (${env}) ===\n`));
         // 認証トークン
         const token = options.token || getAuthToken();
         if (!token) {
@@ -186,7 +197,7 @@ exports.knowledgeCommand
                 relatedDeviceTypes: deviceTypes,
                 status: options.status,
             },
-        }, token);
+        }, token, env);
         spinner.stop();
         if (result.success) {
             console.log(chalk_1.default.green('✓ ナレッジエントリを追加しました'));
@@ -194,6 +205,7 @@ exports.knowledgeCommand
             console.log(`   Title: ${options.title}`);
             console.log(`   Category: ${options.category}`);
             console.log(`   Status: ${options.status}`);
+            console.log(`   Environment: ${env}`);
         }
         else {
             console.log(chalk_1.default.red(`✗ 追加失敗: ${result.error}`));
@@ -212,9 +224,11 @@ exports.knowledgeCommand
     .option('-c, --category <category>', 'カテゴリフィルタ')
     .option('-l, --limit <limit>', '結果数', '10')
     .option('--token <token>', '認証トークン')
+    .option('-e, --endpoint <env>', '環境 (staging|production)', 'production')
     .action(async (options) => {
     try {
-        console.log(chalk_1.default.bold('\n=== Knowledge Search ===\n'));
+        const env = (0, config_1.resolveEnvironment)(options.endpoint);
+        console.log(chalk_1.default.bold(`\n=== Knowledge Search (${env}) ===\n`));
         const token = options.token || getAuthToken();
         if (!token) {
             console.error(chalk_1.default.red('❌ 認証トークンが必要です'));
@@ -225,7 +239,7 @@ exports.knowledgeCommand
             query: options.query,
             category: options.category,
             limit: parseInt(options.limit, 10),
-        }, token);
+        }, token, env);
         spinner.stop();
         if (result.success && result.data) {
             const entries = Array.isArray(result.data) ? result.data : [];
@@ -254,9 +268,11 @@ exports.knowledgeCommand
     .option('-s, --status <status>', 'ステータスフィルタ (draft|published|archived)')
     .option('-l, --limit <limit>', '表示数', '20')
     .option('--token <token>', '認証トークン')
+    .option('-e, --endpoint <env>', '環境 (staging|production)', 'production')
     .action(async (options) => {
     try {
-        console.log(chalk_1.default.bold('\n=== Knowledge List ===\n'));
+        const env = (0, config_1.resolveEnvironment)(options.endpoint);
+        console.log(chalk_1.default.bold(`\n=== Knowledge List (${env}) ===\n`));
         const token = options.token || getAuthToken();
         if (!token) {
             console.error(chalk_1.default.red('❌ 認証トークンが必要です'));
@@ -267,7 +283,7 @@ exports.knowledgeCommand
             category: options.category,
             status: options.status,
             limit: parseInt(options.limit, 10),
-        }, token);
+        }, token, env);
         spinner.stop();
         if (result.success && result.data) {
             const entries = Array.isArray(result.data) ? result.data : [];
@@ -294,16 +310,18 @@ exports.knowledgeCommand
     .description('ナレッジエントリを取得')
     .requiredOption('-i, --id <id>', 'エントリID')
     .option('--token <token>', '認証トークン')
+    .option('-e, --endpoint <env>', '環境 (staging|production)', 'production')
     .action(async (options) => {
     try {
-        console.log(chalk_1.default.bold('\n=== Knowledge Get ===\n'));
+        const env = (0, config_1.resolveEnvironment)(options.endpoint);
+        console.log(chalk_1.default.bold(`\n=== Knowledge Get (${env}) ===\n`));
         const token = options.token || getAuthToken();
         if (!token) {
             console.error(chalk_1.default.red('❌ 認証トークンが必要です'));
             process.exit(1);
         }
         const spinner = (0, ora_1.default)('ナレッジを取得中...').start();
-        const result = await callKnowledgeAPI('get', { id: options.id }, token);
+        const result = await callKnowledgeAPI('get', { id: options.id }, token, env);
         spinner.stop();
         if (result.success && result.data) {
             formatEntry(result.data, true);
@@ -323,10 +341,13 @@ exports.knowledgeCommand
     .description('ナレッジエントリを削除 (アーカイブ)')
     .requiredOption('-i, --id <id>', 'エントリID')
     .option('--token <token>', '認証トークン')
+    .option('-e, --endpoint <env>', '環境 (staging|production)', 'production')
     .option('-y, --yes', '確認をスキップ')
     .action(async (options) => {
     try {
-        console.log(chalk_1.default.bold('\n=== Knowledge Delete ===\n'));
+        const env = (0, config_1.resolveEnvironment)(options.endpoint);
+        (0, config_1.warnIfProduction)(env, 'knowledge delete');
+        console.log(chalk_1.default.bold(`\n=== Knowledge Delete (${env}) ===\n`));
         const token = options.token || getAuthToken();
         if (!token) {
             console.error(chalk_1.default.red('❌ 認証トークンが必要です'));
@@ -338,7 +359,7 @@ exports.knowledgeCommand
             // Note: In a real CLI, would use inquirer for confirmation
         }
         const spinner = (0, ora_1.default)('削除中...').start();
-        const result = await callKnowledgeAPI('delete', { id: options.id }, token);
+        const result = await callKnowledgeAPI('delete', { id: options.id }, token, env);
         spinner.stop();
         if (result.success) {
             console.log(chalk_1.default.green('✓ ナレッジエントリをアーカイブしました'));
@@ -355,20 +376,74 @@ exports.knowledgeCommand
 // knowledge categories
 exports.knowledgeCommand
     .command('categories')
-    .description('利用可能なカテゴリ一覧')
+    .description('利用可能なカテゴリ一覧と追加すべきナレッジの例')
     .action(() => {
     console.log(chalk_1.default.bold('\n=== Knowledge Categories ===\n'));
-    const categoryDescriptions = {
-        api: 'API仕様・エンドポイント',
-        guide: '実装ガイド・チュートリアル',
-        code: 'コードサンプル・スニペット',
-        reference: 'リファレンス・仕様書',
-        incident: 'インシデント・トラブルシューティング',
-        tip: 'Tips・ノウハウ',
+    const categoryInfo = {
+        api: {
+            desc: 'API仕様・エンドポイント',
+            examples: [
+                'State Report API の仕様変更',
+                'エンドポイントURL・認証方式',
+            ],
+        },
+        guide: {
+            desc: '実装ガイド・チュートリアル',
+            examples: [
+                'ESP32 State Report実装手順',
+                'OrangePi サービス設定ガイド',
+            ],
+        },
+        code: {
+            desc: 'コードサンプル・スニペット',
+            examples: [
+                'Arduino HTTPS接続コード',
+                'Python MQTT受信サンプル',
+            ],
+        },
+        reference: {
+            desc: 'リファレンス・仕様書',
+            examples: [
+                'スキーマ定義一覧',
+                'エラーコード一覧',
+            ],
+        },
+        incident: {
+            desc: 'インシデント・トラブルシューティング',
+            examples: [
+                '⚠️ ハードウェア固有の問題・解決策',
+                '⚠️ メモリ不足・タイムアウト事例',
+                '⚠️ 相性問題・回避策',
+            ],
+        },
+        tip: {
+            desc: 'Tips・ノウハウ（一般情報では得られない実践知見）',
+            examples: [
+                '⚠️ ESP32 HTTPSタイムアウト 15秒必要',
+                '⚠️ OrangePi サービス起動順序',
+                '⚠️ メモリ設定・バッファサイズの追い込み値',
+                '⚠️ ハードウェア相性・非互換情報',
+            ],
+        },
     };
     for (const cat of CATEGORIES) {
-        console.log(`  ${chalk_1.default.cyan(cat.padEnd(12))} ${categoryDescriptions[cat]}`);
+        const info = categoryInfo[cat];
+        console.log(`  ${chalk_1.default.cyan(cat.padEnd(12))} ${info.desc}`);
+        for (const ex of info.examples) {
+            if (ex.startsWith('⚠️')) {
+                console.log(`                 ${chalk_1.default.yellow(ex)}`);
+            }
+            else {
+                console.log(`                 ${chalk_1.default.gray('- ' + ex)}`);
+            }
+        }
+        console.log('');
     }
-    console.log('');
+    console.log(chalk_1.default.bold('📝 AIエージェント向け: 以下のナレッジは特に貴重です\n'));
+    console.log(chalk_1.default.yellow('  • インシデント対応で発見したハードウェア固有の設定値'));
+    console.log(chalk_1.default.yellow('  • テスト・デバッグで追い込んだパラメータ（タイムアウト、バッファサイズ等）'));
+    console.log(chalk_1.default.yellow('  • ESP32のメモリ関連、SBCのサービス起動・権限問題'));
+    console.log(chalk_1.default.yellow('  • ハードウェア相性問題と回避策'));
+    console.log(chalk_1.default.yellow('  • 一般的なドキュメントには載っていない実践的知見\n'));
 });
 exports.default = exports.knowledgeCommand;

package/dist/commands/metatron.js

@@ -51,10 +51,17 @@ const chalk_1 = __importDefault(require("chalk"));
 const ora_1 = __importDefault(require("ora"));
 const axios_1 = __importDefault(require("axios"));
 const readline = __importStar(require("readline"));
+const config_1 = require("../config");
 // ============================================================================
 // Config
 // ============================================================================
-const METATRON_API_BASE = 'https://asia-northeast1-mobesorder.cloudfunctions.net/araneaSDK_metatronQuery';
+const METATRON_API_ENDPOINTS = {
+    production: 'https://asia-northeast1-mobesorder.cloudfunctions.net/araneaMetatronQuery',
+    staging: 'https://asia-northeast1-mobesorder-staging.cloudfunctions.net/araneaMetatronQuery',
+};
+function getMetatronApiBase(env) {
+    return METATRON_API_ENDPOINTS[env];
+}
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -67,8 +74,9 @@ function getAuthToken() {
 /**
  * Metatron API呼び出し
  */
-async function queryMetatron(query, context, token) {
-    const response = await axios_1.default.post(METATRON_API_BASE, { data: { query, context } }, {
+async function queryMetatron(query, context, token, env) {
+    const apiBase = getMetatronApiBase(env);
+    const response = await axios_1.default.post(apiBase, { data: { query, context } }, {
         headers: {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${token}`,
@@ -110,11 +118,13 @@ exports.metatronCommand
     .description('単発質問')
     .option('--context <context>', 'コンテキスト', 'aranea_sdk_cli')
     .option('--token <token>', '認証トークン')
+    .option('-e, --endpoint <env>', '環境 (staging|production)', 'production')
     .option('--raw', 'JSON出力')
     .action(async (question, options) => {
     try {
+        const env = (0, config_1.resolveEnvironment)(options.endpoint);
         if (!options.raw) {
-            console.log(chalk_1.default.bold('\n=== AraneaMetatron ===\n'));
+            console.log(chalk_1.default.bold(`\n=== AraneaMetatron (${env}) ===\n`));
             console.log(chalk_1.default.gray(`Q: ${question}`));
         }
         const token = options.token || getAuthToken();
@@ -123,7 +133,7 @@ exports.metatronCommand
             process.exit(1);
         }
         const spinner = options.raw ? null : (0, ora_1.default)('回答生成中...').start();
-        const result = await queryMetatron(question, options.context, token);
+        const result = await queryMetatron(question, options.context, token, env);
         spinner?.stop();
         if (options.raw) {
             console.log(JSON.stringify(result, null, 2));
@@ -143,8 +153,10 @@ exports.metatronCommand
     .description('対話モード (REPL)')
     .option('--context <context>', 'コンテキスト', 'aranea_sdk_cli')
     .option('--token <token>', '認証トークン')
+    .option('-e, --endpoint <env>', '環境 (staging|production)', 'production')
     .action(async (options) => {
-    console.log(chalk_1.default.bold('\n=== AraneaMetatron Chat ===\n'));
+    const env = (0, config_1.resolveEnvironment)(options.endpoint);
+    console.log(chalk_1.default.bold(`\n=== AraneaMetatron Chat (${env}) ===\n`));
     console.log(chalk_1.default.gray('AraneaSDKについて質問してください。'));
     console.log(chalk_1.default.gray('終了するには "exit" または Ctrl+C を入力\n'));
     const token = options.token || getAuthToken();
@@ -171,7 +183,7 @@ exports.metatronCommand
             const spinner = (0, ora_1.default)('').start();
             spinner.text = '';
             try {
-                const result = await queryMetatron(query, options.context, token);
+                const result = await queryMetatron(query, options.context, token, env);
                 spinner.stop();
                 console.log('');
                 console.log(chalk_1.default.green('Metatron:'), result.answer);

package/dist/index.js

@@ -28,7 +28,7 @@ const program = new commander_1.Command();
 program
     .name('aranea-sdk')
     .description('AraneaSDK CLI - デバイス開発支援ツール')
-    .version('0.3.2');
+    .version('0.3.3');
 // test コマンド
 program.addCommand(test_1.testCommand);
 // simulate コマンド

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aranea-sdk-cli",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "AraneaSDK CLI - ESP32 IoTデバイス開発支援ツール",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",