nikou-cli 0.1.15 → 0.1.17

package/README.md

@@ -160,13 +160,35 @@ Hook 支持三种启动模式：
 - 单独从节点：只启动 Worker，连接已有主节点。
 - 一主多从：单独启动一个主节点，再让多台机器的从节点接入。
 
-主节点负责连接聊天平台、接收消息、维护 Worker 列表并分发任务。从节点负责连接主节点，收到任务后调用 Codex、Claude、Gemini 或 API Agent 执行。
+主节点负责连接聊天平台、接收消息、维护 Worker 列表并分发任务。从节点负责连接主节点，收到任务后调用 Codex、Claude、Gemini、API Agent 或知识库客户端执行。
+
+### 部署角色与知识库节点
+
+部署前先按角色选择目标宿主机：
+
+| 角色 | 运行内容 | 部署边界 |
+| --- | --- | --- |
+| 主节点 | 飞书接入、任务路由、Worker 注册 | 只在主节点代码或主从协议变化时部署 |
+| 知识库节点 | Claude Worker、知识库群聊任务 | 当前公司知识库妮蔻的默认部署对象，不按树莓派主节点处理 |
+| 个人节点 | Kiro/Codex 等个人 Worker | 仅处理对应宿主的单聊和绑定任务 |
+
+知识库节点使用已有的 `ai-hook-claude.service` 托管 Worker。发布新版本后，在知识库宿主机安装对应版本并重启该服务：
+
+```bash
+npm install -g nikou-cli@<version> --force --registry=https://registry.npmjs.org/
+nikou-cli --version
+systemctl restart ai-hook-claude.service
+systemctl is-active 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})'
+```
+
+验收时应确认 Worker 使用目标版本、服务为 `active`、`engine=claude` 且 `slaveConnectionStatus=online`，并在主节点日志中确认该 Worker 的 `p2p_enabled=false`。以上步骤只更新知识库 Worker；主节点和 FastGPT/知识库平台容器按各自仓库与服务说明单独部署。
 
 群聊发送 `@机器人 绑定: <目录>` 时，主节点会先检查当前用户是否已经绑定该目录；已有绑定会直接返回当前绑定状态卡片。当前用户已有其他目录时，会通过卡片确认“覆盖原绑定”或“新增绑定目录”；覆盖操作会在新目录校验成功后再撤销旧绑定。一个群可以保留多个用户、多个目录的 Agent 绑定，绑定指令不会广播给其他 Worker 抢占。
 
 绑定成功后会返回绿色状态卡片，展示本次绑定、当前群的全部普通目录绑定、完整路径、对应 Agent，以及知识库固定绑定（如有）。卡片底部同时给出省略盘符路径、完整路径和无路径选择三种解绑方式，便于确认当前真实绑定状态。
 
-群聊内任何成员都可以发送解绑指令。路径既支持完整路径，也支持省略盘符后的末两级路径；不带路径时会显示卡片供用户选择。Agent 选择卡片会展示省略盘符路径，并在底部提示解绑方式。
+群聊内任何成员都可以发送解绑指令。路径既支持完整路径，也支持省略盘符后的末两级路径；不带路径时会显示卡片供用户选择。Agent 选择卡片会展示省略盘符路径、在线状态：在线 Agent 带绿色状态标识且可选择，离线 Agent 会置灰禁用；选择超时后会发送置灰的超时状态卡片。卡片底部同时提示解绑方式。
 
 ```text
 @妮蔻 解绑 D:\project\hst\report
@@ -190,7 +212,7 @@ nikou-cli hook binding remove \
 
 不传 `--dir` 时，会移除该 Agent 在群内的全部目录；如只需移除一条目录绑定，可追加 `--dir /srv/project-a`。群名匹配到多个 `chat_id` 时，命令会停止并要求改用 `--chat-id`，避免误删。
 
-群聊发送 `绑定知识库` 后，任务会定向到配置的知识库 Worker 和固定目录，执行结果卡片不展示宿主信息。知识库绑定只作用于群聊；单聊仍按发送人的飞书 `user_id` 选择其归属 Worker，同一用户多台 Worker 在线时优先使用最近接入的一台。
+群聊发送 `绑定知识库` 后，任务会定向到配置的知识库 Worker 和固定目录，并返回不暴露知识库目录、IP 或宿主的红色绑定状态卡片。卡片同时展示当前群其他 Agent 目录绑定和解绑指令。发送 `解绑知识库` 可移除当前群的知识库固定绑定。知识库绑定只作用于群聊；单聊仍按发送人的飞书 `user_id` 选择其归属 Worker，同一用户多台 Worker 在线时优先使用最近接入的一台。
 
 专用知识库 Worker 建议在从节点配置中关闭单聊，并设置可区分的启动通知名称：
 
@@ -203,7 +225,27 @@ nikou-cli hook binding remove \
 }
 ```
 
-关闭后，该 Worker 仍可承接群聊知识库固定路由，但不会成为宿主的单聊候选。启动通知会显示“公司知识库妮蔻已启动，群聊知识库任务已可用”。未配置时 `p2p_enabled` 默认为 `true`，保持旧 Worker 行为。
+关闭后，该 Worker 仍可承接群聊知识库固定路由，但不会成为宿主的单聊候选。启动通知使用交互卡片展示从节点名称、运行引擎、当前模型和服务范围。未配置时 `p2p_enabled` 默认为 `true`，保持旧 Worker 行为。
+
+知识库 Worker 可以使用 `knowledge` 引擎直接连接 FastGPT 应用。此模式不会启动 Claude，也不会在 Worker 内重复连接知识库或代码 MCP；FastGPT 应用负责完成知识检索、内部工具调用和回答生成，Worker 只负责会话、流式事件与飞书卡片适配：
+
+```json
+{
+  "hook": {
+    "p2p_enabled": false,
+    "worker_name": "公司知识库妮蔻",
+    "knowledge": {
+      "provider": "fastgpt",
+      "base_url": "http://127.0.0.1:3000/api",
+      "api_key_env": "NIKOU_FASTGPT_APP_KEY",
+      "request_timeout_ms": 600000,
+      "retain_dataset_cite": true
+    }
+  }
+}
+```
+
+API Key 必须来自 `api_key_env` 指定的环境变量，不支持把真实 Key 写入命令参数、README 或默认配置。`base_url`、`api_key_env`、`request_timeout_ms` 和 `retain_dataset_cite` 同时兼容 camelCase。
 
 ### 初始化配置
 
@@ -289,6 +331,12 @@ API Agent：
 ai-hook local api --api kiro
 ```
 
+FastGPT 知识库客户端：
+
+```bash
+ai-hook local knowledge
+```
+
 完整入口也可以写成：
 
 ```bash
@@ -312,6 +360,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：
@@ -358,6 +448,18 @@ API Agent：
 nikou-cli hook worker api --api kiro
 ```
 
+FastGPT 知识库客户端：
+
+```bash
+ai-hook knowledge
+# 完整入口
+nikou-cli hook worker knowledge
+```
+
+`knowledge` 模式调用 FastGPT `/api/v1/chat/completions`，固定开启流式响应、详细事件和知识库引用。飞书话题会映射为稳定的 FastGPT `chatId`，因此同一话题可以连续追问，Worker 重启后也会恢复映射。FastGPT 返回的正文进入卡片“执行结果”，可见推理摘要进入“思考过程”，工作流节点和工具调用以脱敏状态行展示；不会展示工具参数和完整工具返回值。
+
+首版仅支持文本问答。图片消息和 FastGPT 交互节点会返回明确的不支持提示，不会静默忽略。
+
 连接远端主节点：
 
 ```bash
@@ -384,8 +486,27 @@ ai-hook claude --model sonnet
 ai-hook gemini
 ai-hook kiro
 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
@@ -530,7 +651,7 @@ nikou-cli hook log --follow
 
 ## 统计上报
 
-统计上报默认关闭，只允许由主节点本机私有配置 `~/.nikou-block/master/config.json` 开启。连接信息不会从环境变量读取，也不会写入公开仓库或日志：
+统计事件默认由主节点写入本地 SQLite。旧的 MySQL 日汇总为可选兼容能力，只允许通过主节点本机私有配置 `~/.nikou-block/master/config.json` 开启；连接信息不会从环境变量读取，也不会写入公开仓库或日志：
 
 ```json
 {
@@ -541,7 +662,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"
   }
 }
 ```
@@ -552,6 +674,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 实时阶段和锁状态合并。只读输出不会包含隐藏思考、系统前置或工具敏感参数。