Neuroskill Bci

連接到正在運行的 NeuroSkill 實例，並將用戶的實時認知和情緒狀態（專注度、放鬆度、情緒、認知負荷、睏倦度、心率、HRV、睡眠階段以及 40+ 項衍生的 EXG 評分）納入響應中。需要佩戴 BCI 可穿戴設備（Muse 2/S 或 OpenBCI）並在本地運行 NeuroSkill 桌面應用程序。

技能元數據


來源	可選 — 使用 `hermes skills install official/health/neuroskill-bci` 安裝
路徑	`optional-skills/health/neuroskill-bci`
版本	`1.0.0`
作者	Hermes Agent + Nous Research
許可證	MIT
標籤	`BCI`, `neurofeedback`, `health`, `focus`, `EEG`, `cognitive-state`, `biometrics`, `neuroskill`

參考：完整 SKILL.md

信息

以下是 Hermes 在觸發此技能時加載的完整技能定義。這是技能激活時代理所看到的指令。

NeuroSkill BCI 集成

將 Hermes 連接到正在運行的 NeuroSkill 實例，以從 BCI 可穿戴設備讀取實時大腦和身體指標。利用這些數據提供具有認知意識的響應、建議干預措施，並跟蹤長期的心理表現。

⚠️ 僅限研究用途 — NeuroSkill 是一款開源研究工具。它不是醫療設備，也未獲得 FDA、CE 或任何監管機構的批准。切勿將這些指標用於臨床診斷或治療。

有關完整的指標參考，請參閱 references/metrics.md；有關干預協議，請參閱 references/protocols.md；有關 WebSocket/HTTP API，請參閱 references/api.md。

前提條件

已安裝 Node.js 20+ (node --version)
正在運行已連接 BCI 設備的 NeuroSkill 桌面應用程序
BCI 硬件：Muse 2、Muse S 或 OpenBCI（通過 BLE 連接的 4 通道 EEG + PPG + IMU）
npx neuroskill status 返回數據且無錯誤

驗證設置

node --version                    # Must be 20+
npx neuroskill status             # Full system snapshot
npx neuroskill status --json      # Machine-parseable JSON

如果 npx neuroskill status 返回錯誤，請告知用戶：

確保 NeuroSkill 桌面應用程序已打開
確保 BCI 設備已通電並通過藍牙連接
檢查信號質量 — NeuroSkill 中的綠色指示器（每個電極 ≥0.7）
如果顯示 command not found，請安裝 Node.js 20+

CLI 參考：`npx neuroskill <command>`

所有命令均支持 --json（原始 JSON，適合管道傳輸）和 --full（人類可讀摘要 + JSON）。

命令	描述
`status`	完整系統快照：設備、評分、頻段、比率、睡眠、歷史記錄
`session [N]`	單次會話細分，包含前半段/後半段趨勢（0=最近一次）
`sessions`	列出所有天數中記錄的所有會話
`search`	用於查找神經相似歷史時刻的 ANN 相似度搜索
`compare`	A/B 會話比較，包含指標差異和趨勢分析
`sleep [N]`	睡眠階段分類（清醒/N1/N2/N3/REM）及分析
`label "text"`	在當前時刻創建帶時間戳的註釋
`search-labels "query"`	對過去標籤進行語義向量搜索
`interactive "query"`	跨模態 4 層圖搜索（文本 → EXG → 標籤）
`listen`	實時事件流式傳輸（默認 5 秒，設置 `--seconds N`）
`umap`	會話嵌入的 3D UMAP 投影
`calibrate`	打開校準窗口並啟動配置文件
`timer`	啟動專注計時器（Pomodoro/深度工作/短時專注預設）
`notify "title" "body"`	通過 NeuroSkill 應用程序發送操作系統通知
`raw '{json}'`	向服務器透傳原始 JSON

全局標誌

標誌	描述
`--json`	原始 JSON 輸出（無 ANSI，適合管道傳輸）
`--full`	人類可讀摘要 + 彩色 JSON
`--port <N>`	覆蓋服務器端口（默認：自動發現，通常為 8375）
`--ws`	強制使用 WebSocket 傳輸
`--http`	強制使用 HTTP 傳輸
`--k <N>`	最近鄰居數量（search, search-labels）
`--seconds <N>`	listen 的持續時間（默認：5）
`--trends`	顯示每個會話的指標趨勢（sessions）
`--dot`	Graphviz DOT 輸出（interactive）

1. 檢查當前狀態

獲取實時指標

npx neuroskill status --json

始終使用 --json 以確保可靠解析。默認輸出為彩色的人類可讀文本。

響應中的關鍵字段

scores 對象包含所有實時指標（除非另有說明，範圍為 0–1）：

{
  "scores": {
    "focus": 0.70,           // β / (α + θ) — sustained attention
    "relaxation": 0.40,      // α / (β + θ) — calm wakefulness
    "engagement": 0.60,      // active mental investment
    "meditation": 0.52,      // alpha + stillness + HRV coherence
    "mood": 0.55,            // composite from FAA, TAR, BAR
    "cognitive_load": 0.33,  // frontal θ / temporal α · f(FAA, TBR)
    "drowsiness": 0.10,      // TAR + TBR + falling spectral centroid
    "hr": 68.2,              // heart rate in bpm (from PPG)
    "snr": 14.3,             // signal-to-noise ratio in dB
    "stillness": 0.88,       // 0–1; 1 = perfectly still
    "faa": 0.042,            // Frontal Alpha Asymmetry (+ = approach)
    "tar": 0.56,             // Theta/Alpha Ratio
    "bar": 0.53,             // Beta/Alpha Ratio
    "tbr": 1.06,             // Theta/Beta Ratio (ADHD proxy)
    "apf": 10.1,             // Alpha Peak Frequency in Hz
    "coherence": 0.614,      // inter-hemispheric coherence
    "bands": {
      "rel_delta": 0.28, "rel_theta": 0.18,
      "rel_alpha": 0.32, "rel_beta": 0.17, "rel_gamma": 0.05
    }
  }
}

還包括：device（狀態、電池、固件）、signal_quality（每個電極 0–1）、session（持續時間、epochs）、embeddings、labels、sleep 摘要和 history。

解讀輸出

解析 JSON 並將指標轉化為自然語言。切勿僅報告原始數字 — 務必賦予其意義：

正確做法：

“你現在的專注度很穩固，達到 0.70 — 這屬於心流狀態領域。心率穩定在 68 bpm，你的 FAA 為正值，這表明具有良好的趨近動機。現在是處理複雜任務的好時機。”

錯誤做法：

“專注度：0.70，放鬆度：0.40，心率：68”

關鍵解讀閾值（完整指南參見 references/metrics.md）：

Focus > 0.70 → 進入心流狀態區域，請保護該狀態
Focus < 0.40 → 建議休息或執行協議
Drowsiness > 0.60 → 疲勞警告，存在微睡眠風險
Relaxation < 0.30 → 需要進行壓力干預
Cognitive Load > 0.70 sustained → 進行思維清空（mind dump）或休息
TBR > 1.5 → Theta 波主導，執行控制能力減弱
FAA < 0 → 退縮/負面情緒 — 考慮重新平衡 FAA
SNR < 3 dB → 信號不可靠，建議重新放置電極

2. 會話分析

單次會話細分

npx neuroskill session --json         # most recent session
npx neuroskill session 1 --json       # previous session
npx neuroskill session 0 --json | jq '{focus: .metrics.focus, trend: .trends.focus}'

返回完整指標，包含前半段與後半段的趨勢（"up"、"down"、"flat"）。使用此功能描述會話的演變過程：

“你的專注力起始於 0.64，並在結束時攀升至 0.76——呈現明顯的上升趨勢。認知負荷從 0.38 降至 0.28，表明隨著你逐漸進入狀態，任務變得更加自動化。”

列出所有會話

npx neuroskill sessions --json
npx neuroskill sessions --trends      # show per-session metric trends

3. 歷史搜索

神經相似性搜索

npx neuroskill search --json                    # auto: last session, k=5
npx neuroskill search --k 10 --json             # 10 nearest neighbors
npx neuroskill search --start <UTC> --end <UTC> --json

通過在 128 維 ZUNA 嵌入向量上執行 HNSW 近似最近鄰搜索，查找歷史上神經狀態相似的時刻。返回距離統計信息、時間分佈（一天中的小時）以及最匹配的日子。

當用戶提出以下問題時使用此功能：

“我上次處於類似狀態是什麼時候？”
“找出我專注力最好的會話”
“我通常在下午什麼時候狀態下滑？”

語義標籤搜索

npx neuroskill search-labels "deep focus" --k 10 --json
npx neuroskill search-labels "stress" --json | jq '[.results[].EXG_metrics.tbr]'

使用向量嵌入（Xenova/bge-small-en-v1.5）搜索標籤文本。返回匹配的標籤及其在打標時刻關聯的 EXG 指標。

npx neuroskill interactive "deep focus" --json
npx neuroskill interactive "deep focus" --dot | dot -Tsvg > graph.svg

4 層圖結構：查詢 → 文本標籤 → EXG 數據點 → 附近標籤。使用 --k-text、--k-EXG、--reach <minutes> 進行調優。

4. 會話比較

npx neuroskill compare --json                   # auto: last 2 sessions
npx neuroskill compare --a-start <UTC> --a-end <UTC> --b-start <UTC> --b-end <UTC> --json

返回約 50 個指標的指標差值，包括絕對變化、百分比變化和方向。還包括 insights.improved[] 和 insights.declined[] 數組、兩個會話的睡眠分期以及 UMAP 任務 ID。

結合上下文解讀比較結果——提及趨勢，而不僅僅是差值：

“昨天你有兩個高強度的專注時段（上午 10 點和下午 2 點）。今天你從上午 11 點左右開始有一個專注時段，目前仍在持續。你今天的整體參與度更高，但出現了更多的壓力峰值——你的壓力指數躍升了 15%，且 FAA 更頻繁地跌至負值。”

# Sort metrics by improvement percentage
npx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'

5. 睡眠數據

npx neuroskill sleep --json                     # last 24 hours
npx neuroskill sleep 0 --json                   # most recent sleep session
npx neuroskill sleep --start <UTC> --end <UTC> --json

返回逐 epoch 的睡眠分期（5 秒窗口）及分析：

階段代碼：0=清醒, 1=N1, 2=N2, 3=N3 (深睡), 4=REM (快速眼動)
分析指標：efficiency_pct (效率百分比), onset_latency_min (入睡潛伏期分鐘數), rem_latency_min (REM 潛伏期分鐘數), bout counts (片段計數)
健康目標：N3 15–25%, REM 20–25%, 效率 >85%, 入睡潛伏期 <20 分鐘

npx neuroskill sleep --json | jq '.summary | {n3: .n3_epochs, rem: .rem_epochs}'
npx neuroskill sleep --json | jq '.analysis.efficiency_pct'

當用戶提及睡眠、疲倦或恢復時使用此功能。

6. 標記時刻

npx neuroskill label "breakthrough"
npx neuroskill label "studying algorithms"
npx neuroskill label "post-meditation"
npx neuroskill label --json "focus block start"   # returns label_id

在以下情況自動標記時刻：

用戶報告突破或洞察
用戶開始新類型的任務（例如，“切換到代碼審查”）
用戶完成重要的協議
用戶要求你標記當前時刻
發生顯著的狀態轉換（進入/離開心流）

標籤存儲在數據庫中，並建立索引以便後續通過 search-labels 和 interactive 命令檢索。

7. 實時流式傳輸

npx neuroskill listen --seconds 30 --json
npx neuroskill listen --seconds 5 --json | jq '[.[] | select(.event == "scores")]'

在指定持續時間內流式傳輸實時 WebSocket 事件（EXG、PPG、IMU、評分、標籤）。需要 WebSocket 連接（使用 --http 時不可用）。

將此用於連續監控場景，或在協議執行期間實時觀察指標變化。

8. UMAP 可視化

npx neuroskill umap --json                      # auto: last 2 sessions
npx neuroskill umap --a-start <UTC> --a-end <UTC> --b-start <UTC> --b-end <UTC> --json

ZUNA 嵌入向量的 GPU 加速 3D UMAP 投影。separation_score 指示兩個會話在神經層面的區分度：

> 1.5 → 會話在神經層面具有顯著差異（不同的腦狀態）
< 0.5 → 兩個會話的腦狀態相似

9. 主動狀態感知

會話開始檢查

在會話開始時，如果用戶提到他們佩戴了設備或詢問其狀態，可選擇運行狀態檢查：

npx neuroskill status --json

注入簡短的狀態摘要：

“快速檢查：專注力正在構建中，值為 0.62，放鬆程度良好，值為 0.55，且你的 FAA 為正——接近動機已激活。看起來開局不錯。”

何時主動提及狀態

僅在以下情況下提及認知狀態：

用戶明確詢問（“我表現如何？”，“檢查我的專注力”）
用戶報告難以集中注意力、壓力大或疲勞
跨越關鍵閾值（嗜睡 > 0.70，專注力持續 < 0.30）
用戶即將進行高認知需求的活動並詢問準備情況

不要為了報告指標而打斷心流狀態。如果專注力 > 0.75，請保護會話——沉默是正確的回應。

10. 建議協議

當指標表明有需要時，從 references/protocols.md 中建議一個協議。開始前務必詢問——切勿打斷心流狀態：

“過去 15 分鐘內，您的專注力一直在下降，且 TBR（Theta-Beta 比率）已攀升至 1.5 以上——這是 Theta 波主導和精神疲勞的跡象。需要我引導您進行 Theta-Beta 神經反饋錨定練習嗎？這是一個 90 秒的練習，通過有節奏的計數和呼吸來抑制 Theta 波並提升 Beta 波。”

關鍵觸發條件：

專注力 < 0.40，TBR > 1.5 → Theta-Beta 神經反饋錨定練習或箱式呼吸法
放鬆度 < 0.30，stress_index（壓力指數）高 → 心臟相干性或 4-7-8 呼吸法
認知負荷 > 0.70 且持續 → 認知負荷卸載（思維傾倒）
睏倦度 > 0.60 → 超日節律重置或清醒重置
FAA < 0（負值） → FAA 再平衡
心流狀態（專注力 > 0.75，參與度 > 0.70） → 請勿打斷
高靜止度 + headache_index（頭痛指數） → 頸部釋放序列
低 RMSSD（< 25ms） → 迷走神經張力訓練

11. 其他工具

專注力計時器

npx neuroskill timer --json

啟動專注力計時器窗口，提供番茄工作法（25/5）、深度工作（50/10）或短時專注（15/5）預設。

校準

npx neuroskill calibrate
npx neuroskill calibrate --profile "Eyes Open"

打開校準窗口。當信號質量較差或用戶希望建立個性化基線時非常有用。

操作系統通知

npx neuroskill notify "Break Time" "Your focus has been declining for 20 minutes"

原始 JSON 透傳

npx neuroskill raw '{"command":"status"}' --json

適用於任何尚未映射到 CLI 子命令的服務器命令。

錯誤處理

錯誤	可能原因	修復方法
`npx neuroskill status` 掛起	NeuroSkill 應用未運行	打開 NeuroSkill 桌面應用
`device.state: "disconnected"`	BCI 設備未連接	檢查藍牙和設備電池
所有評分返回 0	電極接觸不良	重新定位頭帶，溼潤電極
`signal_quality` 值 < 0.7	電極鬆動	調整佩戴，清潔電極接觸點
SNR < 3 dB	信號噪聲大	減少頭部移動，檢查環境
`command not found: npx`	未安裝 Node.js	安裝 Node.js 20+

交互示例

“我現在狀態如何？”

npx neuroskill status --json

→ 自然地解讀評分，提及專注力、放鬆度、情緒以及任何值得注意的比率（FAA、TBR）。僅在指標表明有必要時才建議採取行動。

“我無法集中注意力”

npx neuroskill status --json

→ 檢查指標是否證實這一點（高 Theta 波、低 Beta 波、上升的 TBR、高睏倦度）。 → 如果確認，建議從 references/protocols.md 中選擇適當的方案。 → 如果指標正常，問題可能源於動機而非神經生理因素。

“比較我今天和昨天的專注力”

npx neuroskill compare --json

→ 解讀趨勢，而不僅僅是數字。提及哪些方面有改善，哪些方面有所下降，以及可能的原因。

“我上一次處於心流狀態是什麼時候？”

npx neuroskill search-labels "flow" --json
npx neuroskill search --json

→ 報告時間戳、相關指標以及用戶當時正在做的事情（來自標籤）。

“我睡得怎麼樣？”

npx neuroskill sleep --json

→ 報告睡眠結構（N3%、REM%、效率），與健康目標進行比較，並注意任何問題（高覺醒時段、低 REM 睡眠）。

“標記此刻——我剛剛取得了突破”

npx neuroskill label "breakthrough"

→ 確認標籤已保存。可選地記錄當前指標以記住該狀態。

參考資料

NeuroSkill 論文 — arXiv:2603.03212 (Kosmyna & Hauptmann, MIT Media Lab)
NeuroSkill 桌面應用 (GPLv3)
NeuroLoop CLI companion (GPLv3)
MIT Media Lab 項目

技能元數據​

參考：完整 SKILL.md​

NeuroSkill BCI 集成

前提條件​

驗證設置​

CLI 參考：npx neuroskill <command>​

全局標誌​

1. 檢查當前狀態​

獲取實時指標​

響應中的關鍵字段​

解讀輸出​

2. 會話分析​

單次會話細分​

列出所有會話​

3. 歷史搜索​

神經相似性搜索​

語義標籤搜索​

跨模態圖搜索​

4. 會話比較​

5. 睡眠數據​

6. 標記時刻​

7. 實時流式傳輸​

8. UMAP 可視化​

9. 主動狀態感知​

會話開始檢查​

何時主動提及狀態​

10. 建議協議​

11. 其他工具​

專注力計時器​

校準​

操作系統通知​

原始 JSON 透傳​

錯誤處理​

交互示例​

參考資料​