better-dsh 0.2.5 → 0.3.0

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/health/health-fitness-nutrition.md

@@ -1,255 +0,0 @@
----
-title: "健身营养 — 健身房训练计划与营养追踪"
-sidebar_label: "健身营养"
-description: "健身房训练计划与营养追踪"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# 健身营养
-
-健身房训练计划与营养追踪。通过 wger 按肌肉、器械或类别搜索 690+ 个动作。通过 USDA FoodData Central 查询 380,000+ 种食物的宏量营养素和热量。纯 Python 计算 BMI、TDEE、单次最大重量（one-rep max）、宏量分配和体脂率——无需 pip 安装。适合增肌、减脂或只是想吃得更健康的用户。
-
-## Skill 元数据
-
-| | |
-|---|---|
-| 来源 | 可选 — 通过 `hermes skills install official/health/fitness-nutrition` 安装 |
-| 路径 | `optional-skills/health/fitness-nutrition` |
-| 版本 | `1.0.0` |
-| 许可证 | MIT |
-| 平台 | linux, macos, windows |
-| 标签 | `health`, `fitness`, `nutrition`, `gym`, `workout`, `diet`, `exercise` |
-
-## 参考：完整 SKILL.md
-
-:::info
-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
-:::
-
-# 健身与营养
-
-专业健身教练与运动营养师 skill。两个数据源加上离线计算器——健身者所需的一切尽在其中。
-
-**数据源（全部免费，无 pip 依赖）：**
-
-- **wger** (https://wger.de/api/v2/) — 开放动作数据库，690+ 个动作，含肌肉、器械、图片信息。公开端点无需任何认证。
-- **USDA FoodData Central** (https://api.nal.usda.gov/fdc/v1/) — 美国政府营养数据库，380,000+ 种食物。`DEMO_KEY` 可立即使用；免费注册可获得更高请求限额。
-
-**离线计算器（纯标准库 Python）：**
-
-- BMI、TDEE（Mifflin-St Jeor 公式）、单次最大重量（Epley/Brzycki/Lombardi 公式）、宏量分配、体脂率（美国海军方法）
-
----
-
-## 使用时机
-
-当用户询问以下内容时触发此 skill：
-- 动作、训练、健身计划、肌肉群、训练分化
-- 食物宏量、热量、蛋白质含量、饮食计划、热量计算
-- 身体成分：BMI、体脂率、TDEE、热量盈余/赤字
-- 单次最大重量估算、训练百分比、渐进超负荷
-- 减脂、增肌或维持期的宏量比例
-
----
-
-## 操作流程
-
-### 动作查询（wger API）
-
-所有 wger 公开端点返回 JSON，无需认证。动作查询始终添加 `format=json` 和 `language=2`（英语）。
-
-**第一步 — 确认用户需求：**
-
-- 按肌肉 → 使用 `/api/v2/exercise/?muscles={id}&language=2&status=2&format=json`
-- 按类别 → 使用 `/api/v2/exercise/?category={id}&language=2&status=2&format=json`
-- 按器械 → 使用 `/api/v2/exercise/?equipment={id}&language=2&status=2&format=json`
-- 按名称 → 使用 `/api/v2/exercise/search/?term={query}&language=english&format=json`
-- 完整详情 → 使用 `/api/v2/exerciseinfo/{exercise_id}/?format=json`
-
-**第二步 — 参考 ID（避免额外 API 调用）：**
-
-动作类别：
-
-| ID | 类别        |
-|----|-------------|
-| 8  | Arms        |
-| 9  | Legs        |
-| 10 | Abs         |
-| 11 | Chest       |
-| 12 | Back        |
-| 13 | Shoulders   |
-| 14 | Calves      |
-| 15 | Cardio      |
-
-肌肉：
-
-| ID | 肌肉                      | ID | 肌肉                    |
-|----|---------------------------|----|-------------------------|
-| 1  | Biceps brachii            | 2  | Anterior deltoid        |
-| 3  | Serratus anterior         | 4  | Pectoralis major        |
-| 5  | Obliquus externus         | 6  | Gastrocnemius           |
-| 7  | Rectus abdominis          | 8  | Gluteus maximus         |
-| 9  | Trapezius                 | 10 | Quadriceps femoris      |
-| 11 | Biceps femoris            | 12 | Latissimus dorsi        |
-| 13 | Brachialis                | 14 | Triceps brachii         |
-| 15 | Soleus                    |    |                         |
-
-器械：
-
-| ID | 器械           |
-|----|----------------|
-| 1  | Barbell        |
-| 3  | Dumbbell       |
-| 4  | Gym mat        |
-| 5  | Swiss Ball     |
-| 6  | Pull-up bar    |
-| 7  | none (bodyweight) |
-| 8  | Bench          |
-| 9  | Incline bench  |
-| 10 | Kettlebell     |
-
-**第三步 — 获取并展示结果：**
-
-```bash
-# Search exercises by name
-QUERY="$1"
-ENCODED=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$QUERY")
-curl -s "https://wger.de/api/v2/exercise/search/?term=${ENCODED}&language=english&format=json" \
-  | python3 -c "
-import json,sys
-data=json.load(sys.stdin)
-for s in data.get('suggestions',[])[:10]:
-    d=s.get('data',{})
-    print(f\"  ID {d.get('id','?'):>4} | {d.get('name','N/A'):<35} | Category: {d.get('category','N/A')}\")
-"
-```
-
-```bash
-# Get full details for a specific exercise
-EXERCISE_ID="$1"
-curl -s "https://wger.de/api/v2/exerciseinfo/${EXERCISE_ID}/?format=json" \
-  | python3 -c "
-import json,sys,html,re
-data=json.load(sys.stdin)
-trans=[t for t in data.get('translations',[]) if t.get('language')==2]
-t=trans[0] if trans else data.get('translations',[{}])[0]
-desc=re.sub('<[^>]+>','',html.unescape(t.get('description','N/A')))
-print(f\"Exercise  : {t.get('name','N/A')}\")
-print(f\"Category  : {data.get('category',{}).get('name','N/A')}\")
-print(f\"Primary   : {', '.join(m.get('name_en','') for m in data.get('muscles',[])) or 'N/A'}\")
-print(f\"Secondary : {', '.join(m.get('name_en','') for m in data.get('muscles_secondary',[])) or 'none'}\")
-print(f\"Equipment : {', '.join(e.get('name','') for e in data.get('equipment',[])) or 'bodyweight'}\")
-print(f\"How to    : {desc[:500]}\")
-imgs=data.get('images',[])
-if imgs: print(f\"Image     : {imgs[0].get('image','')}\")
-"
-```
-
-```bash
-# List exercises filtering by muscle, category, or equipment
-# Combine filters as needed: ?muscles=4&equipment=1&language=2&status=2
-FILTER="$1"  # e.g. "muscles=4" or "category=11" or "equipment=3"
-curl -s "https://wger.de/api/v2/exercise/?${FILTER}&language=2&status=2&limit=20&format=json" \
-  | python3 -c "
-import json,sys
-data=json.load(sys.stdin)
-print(f'Found {data.get(\"count\",0)} exercises.')
-for ex in data.get('results',[]):
-    print(f\"  ID {ex['id']:>4} | muscles: {ex.get('muscles',[])} | equipment: {ex.get('equipment',[])}\")
-"
-```
-
-### 营养查询（USDA FoodData Central）
-
-优先使用 `USDA_API_KEY` 环境变量，否则回退到 `DEMO_KEY`。
-DEMO_KEY = 每小时 30 次请求。免费注册密钥 = 每小时 1,000 次请求。
-
-```bash
-# Search foods by name
-FOOD="$1"
-API_KEY="${USDA_API_KEY:-DEMO_KEY}"
-ENCODED=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$FOOD")
-curl -s "https://api.nal.usda.gov/fdc/v1/foods/search?api_key=${API_KEY}&query=${ENCODED}&pageSize=5&dataType=Foundation,SR%20Legacy" \
-  | python3 -c "
-import json,sys
-data=json.load(sys.stdin)
-foods=data.get('foods',[])
-if not foods: print('No foods found.'); sys.exit()
-for f in foods:
-    n={x['nutrientName']:x.get('value','?') for x in f.get('foodNutrients',[])}
-    cal=n.get('Energy','?'); prot=n.get('Protein','?')
-    fat=n.get('Total lipid (fat)','?'); carb=n.get('Carbohydrate, by difference','?')
-    print(f\"{f.get('description','N/A')}\")
-    print(f\"  Per 100g: {cal} kcal | {prot}g protein | {fat}g fat | {carb}g carbs\")
-    print(f\"  FDC ID: {f.get('fdcId','N/A')}\")
-    print()
-"
-```
-
-```bash
-# Detailed nutrient profile by FDC ID
-FDC_ID="$1"
-API_KEY="${USDA_API_KEY:-DEMO_KEY}"
-curl -s "https://api.nal.usda.gov/fdc/v1/food/${FDC_ID}?api_key=${API_KEY}" \
-  | python3 -c "
-import json,sys
-d=json.load(sys.stdin)
-print(f\"Food: {d.get('description','N/A')}\")
-print(f\"{'Nutrient':<40} {'Amount':>8} {'Unit'}\")
-print('-'*56)
-for x in sorted(d.get('foodNutrients',[]),key=lambda x:x.get('nutrient',{}).get('rank',9999)):
-    nut=x.get('nutrient',{}); amt=x.get('amount',0)
-    if amt and float(amt)>0:
-        print(f\"  {nut.get('name',''):<38} {amt:>8} {nut.get('unitName','')}\")
-"
-```
-
-### 离线计算器
-
-对批量操作使用 `scripts/` 中的辅助脚本，或内联运行单次计算：
-
-- `python3 scripts/body_calc.py bmi <weight_kg> <height_cm>`
-- `python3 scripts/body_calc.py tdee <weight_kg> <height_cm> <age> <M|F> <activity 1-5>`
-- `python3 scripts/body_calc.py 1rm <weight> <reps>`
-- `python3 scripts/body_calc.py macros <tdee_kcal> <cut|maintain|bulk>`
-- `python3 scripts/body_calc.py bodyfat <M|F> <neck_cm> <waist_cm> [hip_cm] <height_cm>`
-
-各公式的科学依据详见 `references/FORMULAS.md`。
-
----
-
-## 注意事项
-
-- wger 动作端点默认返回**所有语言**——始终添加 `language=2` 以获取英语内容
-- wger 包含**未经验证的用户提交内容**——添加 `status=2` 仅获取已审核动作
-- USDA `DEMO_KEY` 限制**每小时 30 次请求**——批量请求之间添加 `sleep 2`，或申请免费密钥
-- USDA 数据基于 **每 100g**——提醒用户按实际份量换算
-- BMI 无法区分肌肉与脂肪——肌肉量大的人 BMI 偏高不一定不健康
-- 体脂率公式为**估算值**（误差 ±3-5%）——精确测量建议使用 DEXA 扫描
-- 单次最大重量公式在超过 10 次重复时准确性下降——建议使用 3-5 次重复组进行估算
-- wger 的 `exercise/search` 端点参数名为 `term` 而非 `query`
-
----
-
-## 验证
-
-运行动作搜索后：确认结果包含动作名称、肌肉群和器械信息。
-营养查询后：确认返回每 100g 的宏量数据，包含 kcal、蛋白质、脂肪、碳水化合物。
-计算器运行后：对输出进行合理性检查（例如，大多数成年人的 TDEE 应在 1500-3500 之间）。
-
----
-
-## 快速参考
-
-| 任务 | 数据源 | 端点 |
-|------|--------|----------|
-| 按名称搜索动作 | wger | `GET /api/v2/exercise/search/?term=&language=english` |
-| 动作详情 | wger | `GET /api/v2/exerciseinfo/{id}/` |
-| 按肌肉筛选 | wger | `GET /api/v2/exercise/?muscles={id}&language=2&status=2` |
-| 按器械筛选 | wger | `GET /api/v2/exercise/?equipment={id}&language=2&status=2` |
-| 列出类别 | wger | `GET /api/v2/exercisecategory/` |
-| 列出肌肉 | wger | `GET /api/v2/muscle/` |
-| 搜索食物 | USDA | `GET /fdc/v1/foods/search?query=&dataType=Foundation,SR Legacy` |
-| 食物详情 | USDA | `GET /fdc/v1/food/{fdcId}` |
-| BMI / TDEE / 单次最大重量 / 宏量 | 离线 | `python3 scripts/body_calc.py` |

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/health/health-neuroskill-bci.md

@@ -1,431 +0,0 @@
----
-title: "Neuroskill Bci"
-sidebar_label: "Neuroskill Bci"
-description: "连接到运行中的 NeuroSkill 实例，将用户的实时认知与情绪状态（专注度、放松度、情绪、认知负荷、困倦度、心率、HRV、睡眠分期及 40+ 项衍生 EXG 评分）融入响应中..."
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Neuroskill Bci
-
-连接到运行中的 NeuroSkill 实例，将用户的实时认知与情绪状态（专注度、放松度、情绪、认知负荷、困倦度、心率、HRV、睡眠分期及 40+ 项衍生 EXG 评分）融入响应中。需要 BCI 可穿戴设备（Muse 2/S 或 OpenBCI）以及在本地运行的 NeuroSkill 桌面应用。
-
-## Skill 元数据
-
-| | |
-|---|---|
-| 来源 | 可选 — 通过 `hermes skills install official/health/neuroskill-bci` 安装 |
-| 路径 | `optional-skills/health/neuroskill-bci` |
-| 版本 | `1.0.0` |
-| 作者 | Hermes Agent + Nous Research |
-| 许可证 | MIT |
-| 平台 | linux, macos, windows |
-| 标签 | `BCI`, `neurofeedback`, `health`, `focus`, `EEG`, `cognitive-state`, `biometrics`, `neuroskill` |
-
-## 参考：完整 SKILL.md
-
-:::info
-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
-:::
-
-# NeuroSkill BCI 集成
-
-将 Hermes 连接到运行中的 [NeuroSkill](https://neuroskill.com/) 实例，从 BCI 可穿戴设备读取实时脑部与身体指标。用于提供具有认知感知能力的响应、建议干预措施，并随时间追踪心理表现。
-
-> **⚠️ 仅供研究使用** — NeuroSkill 是一款开源研究工具。它**不是**医疗设备，**未**经 FDA、CE 或任何监管机构批准。切勿将这些指标用于临床诊断或治疗。
-
-完整指标参考见 `references/metrics.md`，干预协议见 `references/protocols.md`，WebSocket/HTTP API 见 `references/api.md`。
-
----
-
-## 前提条件
-
-- 已安装 **Node.js 20+**（`node --version`）
-- **NeuroSkill 桌面应用**正在运行，且已连接 BCI 设备
-- **BCI 硬件**：Muse 2、Muse S 或 OpenBCI（通过 BLE 连接的 4 通道 EEG + PPG + IMU）
-- `npx neuroskill status` 无错误返回数据
-
-### 验证设置
-```bash
-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]` | 睡眠分期分类（Wake/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. 检查当前状态
-
-### 获取实时指标
-```bash
-npx neuroskill status --json
-```
-
-**始终使用 `--json`** 以确保可靠解析。默认输出为带颜色的人类可读文本。
-
-### 响应中的关键字段
-
-`scores` 对象包含所有实时指标（除特别说明外，均为 0–1 范围）：
-
-```jsonc
-{
-  "scores": {
-    "focus": 0.70,           // β / (α + θ) — 持续注意力
-    "relaxation": 0.40,      // α / (β + θ) — 平静清醒状态
-    "engagement": 0.60,      // 主动心理投入
-    "meditation": 0.52,      // alpha + 静止 + HRV 相干性
-    "mood": 0.55,            // 由 FAA、TAR、BAR 综合计算
-    "cognitive_load": 0.33,  // 额叶 θ / 颞叶 α · f(FAA, TBR)
-    "drowsiness": 0.10,      // TAR + TBR + 频谱质心下降
-    "hr": 68.2,              // 心率（bpm，来自 PPG）
-    "snr": 14.3,             // 信噪比（dB）
-    "stillness": 0.88,       // 0–1；1 = 完全静止
-    "faa": 0.042,            // 额叶 Alpha 不对称性（正值 = 趋近动机）
-    "tar": 0.56,             // Theta/Alpha 比率
-    "bar": 0.53,             // Beta/Alpha 比率
-    "tbr": 1.06,             // Theta/Beta 比率（ADHD 代理指标）
-    "apf": 10.1,             // Alpha 峰值频率（Hz）
-    "coherence": 0.614,      // 半球间相干性
-    "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`（时长、epoch 数）、`embeddings`、`labels`、`sleep` 摘要及 `history`。
-
-### 解读输出
-
-解析 JSON 并将指标转化为自然语言。切勿单独报告原始数字 — 始终赋予其含义：
-
-**应该这样做：**
-> "您目前的专注度相当不错，达到 0.70 — 这已进入心流状态区间。心率稳定在 68 bpm，FAA 为正值，表明趋近动机良好。现在是处理复杂任务的好时机。"
-
-**不应该这样做：**
-> "专注度：0.70，放松度：0.40，心率：68"
-
-关键解读阈值（完整指南见 `references/metrics.md`）：
-- **专注度 > 0.70** → 心流状态区间，注意保护
-- **专注度 &lt; 0.40** → 建议休息或执行协议
-- **困倦度 > 0.60** → 疲劳警告，存在微睡眠风险
-- **放松度 &lt; 0.30** → 需要压力干预
-- **认知负荷 > 0.70 持续** → 建议思维倾倒或休息
-- **TBR > 1.5** → theta 主导，执行控制减弱
-- **FAA &lt; 0** → 回避/负面情绪 — 考虑 FAA 再平衡
-- **SNR &lt; 3 dB** → 信号不可靠，建议重新定位电极
-
----
-
-## 2. 会话分析
-
-### 单次会话详情
-```bash
-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，表明随着您逐渐进入状态，任务变得更加自动化。"
-
-### 列出所有会话
-```bash
-npx neuroskill sessions --json
-npx neuroskill sessions --trends      # show per-session metric trends
-```
-
----
-
-## 3. 历史搜索
-
-### 神经相似性搜索
-```bash
-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 近似最近邻搜索，在历史记录中查找神经状态相似的时刻。返回距离统计、时间分布（一天中的小时）及最匹配的日期。
-
-在用户提问以下问题时使用：
-- "我上次处于这种状态是什么时候？"
-- "找出我最佳的专注会话"
-- "我通常在下午什么时候状态下滑？"
-
-### 语义标签搜索
-```bash
-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 指标。
-
-### 跨模态图搜索
-```bash
-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. 会话对比
-```bash
-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 更频繁地出现负值。"
-
-```bash
-# Sort metrics by improvement percentage
-npx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'
-```
-
----
-
-## 5. 睡眠数据
-```bash
-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、bout 计数
-- **健康目标**：N3 占 15–25%，REM 占 20–25%，效率 >85%，入睡潜伏期 &lt;20 分钟
-
-```bash
-npx neuroskill sleep --json | jq '.summary | {n3: .n3_epochs, rem: .rem_epochs}'
-npx neuroskill sleep --json | jq '.analysis.efficiency_pct'
-```
-
-当用户提及睡眠、疲倦或恢复时使用此命令。
-
----
-
-## 6. 标注时刻
-```bash
-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. 实时流式传输
-```bash
-npx neuroskill listen --seconds 30 --json
-npx neuroskill listen --seconds 5 --json | jq '[.[] | select(.event == "scores")]'
-```
-
-在指定时长内流式传输实时 WebSocket 事件（EXG、PPG、IMU、评分、标签）。需要 WebSocket 连接（`--http` 模式下不可用）。
-
-适用于持续监控场景，或在协议执行期间实时观察指标变化。
-
----
-
-## 8. UMAP 可视化
-```bash
-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** → 会话在神经层面存在显著差异（不同脑状态）
-- **&lt; 0.5** → 两次会话的脑状态相似
-
----
-
-## 9. 主动状态感知
-
-### 会话开始检查
-在会话开始时，如果用户提到正在佩戴设备或询问自身状态，可选择性地执行状态检查：
-```bash
-npx neuroskill status --json
-```
-
-注入简短的状态摘要：
-> "快速检查：专注度正在上升至 0.62，放松度良好为 0.55，FAA 为正值 — 趋近动机已激活。看起来是个不错的开始。"
-
-### 何时主动提及状态
-
-**仅在以下情况下**提及认知状态：
-- 用户明确询问（"我状态怎么样？"、"检查一下我的专注度"）
-- 用户反映难以集中注意力、感到压力或疲劳
-- 超过关键阈值（困倦度 > 0.70，专注度 &lt; 0.30 持续）
-- 用户即将进行认知要求较高的任务并询问准备情况
-
-**切勿**打断心流状态来报告指标。如果专注度 > 0.75，请保护该会话 — 沉默是正确的响应。
-
----
-
-## 10. 建议协议
-
-当指标表明有需要时，从 `references/protocols.md` 中建议相应协议。始终在开始前征得同意 — 切勿打断心流状态：
-
-> "您的专注度在过去 15 分钟持续下降，TBR 已超过 1.5 — 这是 theta 主导和心理疲劳的迹象。需要我带您做一个 Theta-Beta 神经反馈锚定练习吗？这是一个 90 秒的练习，通过有节奏的计数和呼吸来抑制 theta 并提升 beta。"
-
-关键触发条件：
-- **专注度 &lt; 0.40，TBR > 1.5** → Theta-Beta 神经反馈锚定或箱式呼吸
-- **放松度 &lt; 0.30，stress_index 高** → 心脏相干性或 4-7-8 呼吸法
-- **认知负荷 > 0.70 持续** → 认知负荷卸载（思维倾倒）
-- **困倦度 > 0.60** → 超日节律重置或清醒重置
-- **FAA &lt; 0（负值）** → FAA 再平衡
-- **心流状态（专注度 > 0.75，投入度 > 0.70）** → 切勿打断
-- **高静止度 + headache_index** → 颈部放松序列
-- **低 RMSSD（&lt; 25ms）** → 迷走神经调节
-
----
-
-## 11. 附加工具
-
-### 专注计时器
-```bash
-npx neuroskill timer --json
-```
-启动专注计时器窗口，提供 Pomodoro（25/5）、深度工作（50/10）或短时专注（15/5）预设。
-
-### 校准
-```bash
-npx neuroskill calibrate
-npx neuroskill calibrate --profile "Eyes Open"
-```
-打开校准窗口。适用于信号质量较差或用户希望建立个性化基线时。
-
-### 系统通知
-```bash
-npx neuroskill notify "Break Time" "Your focus has been declining for 20 minutes"
-```
-
-### 原始 JSON 直通
-```bash
-npx neuroskill raw '{"command":"status"}' --json
-```
-用于尚未映射到 CLI 子命令的任何服务器命令。
-
----
-
-## 错误处理
-
-| 错误 | 可能原因 | 解决方法 |
-|-------|-------------|-----|
-| `npx neuroskill status` 挂起 | NeuroSkill 应用未运行 | 打开 NeuroSkill 桌面应用 |
-| `device.state: "disconnected"` | BCI 设备未连接 | 检查蓝牙及设备电量 |
-| 所有评分返回 0 | 电极接触不良 | 重新定位头带，润湿电极 |
-| `signal_quality` 值 &lt; 0.7 | 电极松动 | 调整佩戴位置，清洁电极触点 |
-| SNR &lt; 3 dB | 信号噪声过大 | 减少头部移动，检查环境干扰 |
-| `command not found: npx` | 未安装 Node.js | 安装 Node.js 20+ |
-
----
-
-## 交互示例
-
-**"我现在状态怎么样？"**
-```bash
-npx neuroskill status --json
-```
-→ 自然地解读评分，提及专注度、放松度、情绪及任何值得关注的比率（FAA、TBR）。仅在指标表明有需要时才建议采取行动。
-
-**"我无法集中注意力"**
-```bash
-npx neuroskill status --json
-```
-→ 检查指标是否印证（高 theta、低 beta、TBR 上升、困倦度高）。
-→ 如果得到印证，从 `references/protocols.md` 中建议适当的协议。
-→ 如果指标看起来正常，问题可能是动机层面而非神经层面。
-
-**"对比我今天和昨天的专注度"**
-```bash
-npx neuroskill compare --json
-```
-→ 解读趋势而非单纯数字。提及哪些方面有所改善、哪些有所下降，以及可能的原因。
-
-**"我上次处于心流状态是什么时候？"**
-```bash
-npx neuroskill search-labels "flow" --json
-npx neuroskill search --json
-```
-→ 报告时间戳、关联指标及用户当时正在做的事情（来自标签）。
-
-**"我睡得怎么样？"**
-```bash
-npx neuroskill sleep --json
-```
-→ 报告睡眠结构（N3%、REM%、效率），与健康目标对比，并指出任何问题（清醒 epoch 过多、REM 不足）。
-
-**"标记这个时刻 — 我刚有了一个突破"**
-```bash
-npx neuroskill label "breakthrough"
-```
-→ 确认标签已保存。可选择性地记录当前指标以留存该状态的记忆。
-
----
-
-## 参考资料
-
-- [NeuroSkill 论文 — arXiv:2603.03212](https://arxiv.org/abs/2603.03212)（Kosmyna & Hauptmann，MIT Media Lab）
-- [NeuroSkill 桌面应用](https://github.com/NeuroSkill-com/skill)（GPLv3）
-- [NeuroLoop CLI 伴侣](https://github.com/NeuroSkill-com/neuroloop)（GPLv3）
-- [MIT Media Lab 项目](https://www.media.mit.edu/projects/neuroskill/overview/)