nikou-cli 0.1.16 → 0.1.18

package/README.md

@@ -162,6 +162,30 @@ Hook 支持三种启动模式：
 
 主节点负责连接聊天平台、接收消息、维护 Worker 列表并分发任务。从节点负责连接主节点，收到任务后调用 Codex、Claude、Gemini、API Agent 或知识库客户端执行。
 
+### 部署角色与知识库节点
+
+部署前先按角色选择目标宿主机：
+
+| 角色 | 运行内容 | 部署边界 |
+| --- | --- | --- |
+| 知识库宿主机主节点 | 飞书接入、任务路由、Worker 注册 | 与知识库 Worker 部署在同一台知识库宿主机，不按树莓派处理 |
+| 知识库宿主机 Worker | Claude Worker、知识库群聊任务 | 唯一的知识库 Claude Worker，关闭单聊路由 |
+| 个人节点 | Kiro/Codex 等个人 Worker | 仅处理对应宿主的单聊和绑定任务 |
+
+当前知识库宿主机同时托管主节点和唯一的知识库 Worker，两个 systemd 服务均配置为开机自启。发布新版本后，在同一台知识库宿主机安装对应版本，并按顺序重启两个服务：
+
+```bash
+npm install -g nikou-cli@<version> --force --registry=https://registry.npmjs.org/
+nikou-cli --version
+systemctl restart com.vangelis.agent-block.hook.master.service
+systemctl restart ai-hook-claude.service
+systemctl is-enabled com.vangelis.agent-block.hook.master.service ai-hook-claude.service
+systemctl is-active com.vangelis.agent-block.hook.master.service ai-hook-claude.service
+node -e 'const s=require("/root/.nikou-block/state/worker.json"); console.log({pid:s.pid,status:s.status,engine:s.engine,slaveConnectionStatus:s.slaveConnectionStatus})'
+```
+
+验收时应确认两个服务均为 `enabled/active`，主节点监听端口和状态文件正常，Worker 使用目标版本、`engine=claude`、`slaveConnectionStatus=online`，并在主节点日志中确认该 Worker 的 `p2p_enabled=false`。同时确认不存在旧的 `ai-hook-knowledge.service`，以及主节点上只有这一个知识库 Claude Worker。FastGPT/知识库平台容器按各自仓库与服务说明单独部署。
+
 群聊发送 `@机器人 绑定: <目录>` 时，主节点会先检查当前用户是否已经绑定该目录；已有绑定会直接返回当前绑定状态卡片。当前用户已有其他目录时，会通过卡片确认“覆盖原绑定”或“新增绑定目录”；覆盖操作会在新目录校验成功后再撤销旧绑定。一个群可以保留多个用户、多个目录的 Agent 绑定，绑定指令不会广播给其他 Worker 抢占。
 
 绑定成功后会返回绿色状态卡片，展示本次绑定、当前群的全部普通目录绑定、完整路径、对应 Agent，以及知识库固定绑定（如有）。卡片底部同时给出省略盘符路径、完整路径和无路径选择三种解绑方式，便于确认当前真实绑定状态。
@@ -203,7 +227,7 @@ nikou-cli hook binding remove \
 }
 ```
 
-关闭后，该 Worker 仍可承接群聊知识库固定路由，但不会成为宿主的单聊候选。启动通知会显示“公司知识库妮蔻已启动，群聊知识库任务已可用”。未配置时 `p2p_enabled` 默认为 `true`，保持旧 Worker 行为。
+关闭后，该 Worker 仍可承接群聊知识库固定路由，但不会成为宿主的单聊候选。启动通知使用交互卡片展示从节点名称、运行引擎、当前模型和服务范围。未配置时 `p2p_enabled` 默认为 `true`，保持旧 Worker 行为。
 
 知识库 Worker 可以使用 `knowledge` 引擎直接连接 FastGPT 应用。此模式不会启动 Claude，也不会在 Worker 内重复连接知识库或代码 MCP；FastGPT 应用负责完成知识检索、内部工具调用和回答生成，Worker 只负责会话、流式事件与飞书卡片适配：
 
@@ -338,6 +362,48 @@ nikou-cli hook master \
   --shared-secret CHANGE_ME
 ```
 
+### 主节点管理接口
+
+主节点可以额外开一个 HTTP 管理接口，供 CC Switch 的「妮蔻 · 主节点」模块远程
+查看运行状态、翻页读日志、看任务统计和触发重启。默认不启用，只有在主节点配置
+`~/.nikou-block/master/config.json` 写入了 `hook.admin_key` 时才会监听。
+
+生成管理密钥（在主节点机器上执行）：
+
+```bash
+nikou-cli hook admin-key --rotate
+```
+
+查看当前配置与密钥指纹：
+
+```bash
+nikou-cli hook admin-key
+nikou-cli hook admin-key --show   # 打印完整密钥，注意不要外发
+```
+
+对应配置项：
+
+| 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `hook.admin_key` | 空 | 管理密钥，至少 24 位；为空时不启动管理接口 |
+| `hook.admin_port` | `19733` | 管理接口监听端口 |
+| `hook.admin_host` | `0.0.0.0` | 管理接口监听地址 |
+| `hook.admin_enabled` | `true` | 配置了密钥后是否启用 |
+
+接口清单（除 `/admin/ping` 外都需要 `X-Nikou-Admin-Key` 头，或 `Authorization: Bearer <key>`）：
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET | `/admin/ping` | 连通性探测，只返回服务名与版本 |
+| GET | `/admin/status` | 运行态：PID、启动时间、在线 Worker 摘要、群聊绑定数、白名单人数 |
+| GET | `/admin/log?page=1&pageSize=200&keyword=` | 主节点日志分页，`page=1` 为最新一页 |
+| GET | `/admin/stats?days=7` | 按天任务统计，读本机 `usage-events.sqlite` |
+| POST | `/admin/restart` | 主节点自行退出，由 systemd `Restart=always` 拉起 |
+
+安全边界：密钥只做常量时间比较，鉴权失败按来源 IP 限流（5 分钟内 8 次后返回
+429），日志不打印密钥；返回体只含运行态与脱敏 Worker 摘要，不含飞书凭据、
+`shared_secret` 或统计库账号。重启依赖 systemd 托管，未托管时接口直接拒绝。
+
 ### 启动从节点
 
 Codex：
@@ -425,6 +491,24 @@ ai-hook api --api kiro
 ai-hook knowledge
 ```
 
+从节点连接主节点成功后，会向宿主发送启动卡片。卡片包含当前运行引擎、实际启动模型和单聊/群聊可用范围；通过飞书菜单切换模型并重启后，新卡片同时作为切换成功确认。
+
+### 飞书机器人菜单事件
+
+主节点支持以下菜单事件：
+
+| 事件 | 行为 |
+| --- | --- |
+| `chat_new` | 标记下一条单聊消息强制创建新会话，不复用旧消息引用或最近会话 |
+| `stop_chat` | 终止当前宿主 Worker 正在执行的全部单聊和绑定群聊任务 |
+| `switch_codex` | 切换到 Codex 并重启当前宿主 Worker |
+| `switch_opus` | 切换到 Claude Opus 并重启当前宿主 Worker |
+| `switch_kiro_Opus5` | 切换到 Kiro 原生 `claude-opus-5` 并重启当前宿主 Worker |
+| `switch_kiro_auto` | 切换到 Kiro 原生 `auto` 并重启当前宿主 Worker |
+| `bind_chat` | 发送群聊名、目录简写和解绑操作组成的交互卡片 |
+
+`my_info` 已不再处理。`bind_chat` 卡片以主节点持久绑定表为准；点击某行“解绑”后会持久撤销对应绑定并刷新卡片，旧 Worker 快照不能恢复已解绑记录。
+
 也可以通过 `--` 传递底层工具参数：
 
 ```bash
@@ -569,7 +653,7 @@ nikou-cli hook log --follow
 
 ## 统计上报
 
-统计上报默认关闭，只允许由主节点本机私有配置 `~/.nikou-block/master/config.json` 开启。连接信息不会从环境变量读取，也不会写入公开仓库或日志：
+统计事件默认由主节点写入本地 SQLite。旧的 MySQL 日汇总为可选兼容能力，只允许通过主节点本机私有配置 `~/.nikou-block/master/config.json` 开启；连接信息不会从环境变量读取，也不会写入公开仓库或日志：
 
 ```json
 {
@@ -580,7 +664,8 @@ nikou-cli hook log --follow
     "user": "YOUR_DB_USER",
     "password": "CHANGE_ME",
     "database": "YOUR_DB_NAME",
-    "table": "nikou_usage_daily_stat"
+    "table": "nikou_usage_daily_stat",
+    "event_db_path": "~/.nikou-block/master/usage-events.sqlite"
   }
 }
 ```
@@ -591,6 +676,8 @@ nikou-cli hook log --follow
 nikou-cli hook usage-report --start 2026-07-13 --end 2026-07-19
 ```
 
+主节点会把任务生命周期事件异步写入本机 SQLite 文件，默认路径为 `~/.nikou-block/master/usage-events.sqlite`，首次启动自动建表并通过 `event_id` 幂等。事件只包含统计维度，不包含问题正文、回答正文或思考过程；不需要额外建表、数据库账号或远程网络。旧的 MySQL 日汇总仍作为兼容字段读取，但不再是周报事件统计的前置条件。详见 [统计事件存储说明](docs/usage-stat-event-schema.md)。
+
 ### Kiro 会话管理
 
 `nikou-cli` 会从 `KIRO_HOME/sessions/cli` 读取 Kiro 官方会话文件，并与妮蔻绑定、Worker 实时阶段和锁状态合并。只读输出不会包含隐藏思考、系统前置或工具敏感参数。