kinstra-neko
Kinstra Neko —— 住在 QQ 群里的猫娘，基于 DeepSeek Harness 的 OneBot v11 社交陪伴发行版（自部署）
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:EROQIN/kinstra-neko#ef12897f4ad943e4f523764e242fad30ab39dd6fKinstra Neko 以 kinstra-neko 发布，当前版本为 1.0.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
一个自部署的社交陪伴机器人 —— 被 @ 会回，没人叫时按话题相关度自然插话，记得群友的小事，有自己的性格。
基于 DeepSeek Harness 二次开发，通过 OneBot v11 接入 QQ。
[!WARNING] 账号风险须知：QQ 非官方协议接入存在账号被限制的可能。请务必使用专门注册的小号，本项目作者不对任何账号后果负责。建议先拉小号进测试群体验，确认稳定再长期使用。
💬 低打扰的群聊存在感被 @、被引用、叫名字必回；没被叫到时，只在话题真的和她有关、群里正热闹、过了冷却期时以小概率插话；加入话题后顺着聊几句，话题走远就安静。冷却、每小时上限、静默时段、防刷屏全部可配。 |
🔒 出厂即安全默认总开关关、试运行（observe）开、白名单空 —— 不配置一句话都不会发。试运行期间她只在面板记录「我本来会说什么」，确认对味再开麦。主人私聊永远放行，陌生人会话零本地工具。 |
🧠 零依赖长期记忆自带中文二元切词 BM25 记忆库：JSONL 磁盘事实库 + 热群 LRU 内存倒排索引（冷群零驻留）+ 遗忘曲线与人物档案。无需 Redis / 数据库，2G 内存服务器也跑得动。 |
🐾 可微调的原创人格面板直接编辑 Markdown 人格卡，下一轮即时生效；系统提示词变量、记忆上下文、remember / recall 工具自动挂载。回复支持换行多气泡、引用、真 @ 群成员、拍一拍，带拟人打字延迟。 |
🖥️ 图形化首启向导浏览器内三步向导 + 七个配置页面（概览 / 连接 / 群聊与权限 / 人格 / 试运行 / 日志 / 高级），品牌化界面，零 UI 库依赖。主人还能直接在 DSH 面板里翻看每个群的长会话、随时插话。 |
📦 一条命令装完，无 DockerLinux 一键脚本：Node 22、内存不足自动加 2G swap、NapCat 自动托管、systemd 守护（开机自启、崩溃重启、700MB 内存上限）；Windows 自动下载运行 NapCat 官方一键包（连 QQ 一起装好）+ 桌面快捷方式。用户只需扫码登录小号、粘贴模型 API Key。 |
curl -fsSL https://raw.githubusercontent.com/EROQIN/kinstra-neko/main/installer/linux/install.sh | sudo bash
# 国内网络慢可： sudo CN_MIRROR=1 bash install.sh
脚本会：装 Node 22（内存不足自动加 2G swap，swappiness=10）→ 全局装 DSH → 建独立 kinstra-neko profile 并装本插件 → 引导装 NapCat（无桌面环境配 Xvfb 扫码）→ 注册 kinstra-neko systemd 服务（开机自启、--max-old-space-size=700）。
irm https://raw.githubusercontent.com/EROQIN/kinstra-neko/main/installer/windows/install.ps1 | iex
脚本会自动下载运行 NapCat 官方一键包（NapCat.Shell.Windows.OneKey，连 QQNT 一起装好，无需预装 QQ），并把 NapCat 目录、run-napcat.bat 薄壳与 OneBot 配置都准备好；也支持在「连接」页改接任意 OneBot v11 实现。
DSH 是 pnpm 生态（依赖多为 alpha 预发布版本，npm 的严格 peer 校验会报 ERESOLVE），请用 pnpm：
npm i -g pnpm # 若还没有 pnpm
pnpm dlx kinstra-neko@latest init # 建 profile、装 bundle、引导写凭据
dsh --profile kinstra-neko --port 3090 # 控制台会自动打开带一次性 token 的页面
journalctl -u kinstra-neko -n 30 | grep -o 'http://.*token=.*' | tail -1 取带 token 的地址（裸 http://<IP>:3090 会被令牌门挡住，云服务器记得安全组放行 3090）。DSH 支持 DeepSeek 官方与任意 OpenAI 兼容网关。密钥写 ~/.dsh/.credentials.yaml（权限 0600，永不明文回传面板），provider / 模型表写 profile 的 cordis 配置（DSH 设置页图形化完成，安装器也会引导）。
最小 OpenAI 兼容配置示例（dsh-llm-pi-ai 风格）：
- name: '@deepseek-ai/dsh-llm-pi-ai'
config:
providers:
deepseek:
api: openai-completions
baseURL: https://api.deepseek.com/v1
apiKeyEnv: DEEPSEEK_API_KEY
models:
- id: deepseek-chat
contextWindow: 131072
2G 服务器建议选上下文适中、单价低的对话模型；群会话 preset 已把 compaction 阈值调小（6144 字符触发、工具结果裁剪），控制长会话内存。
QQ 小号
▲ OneBot v11（NapCat 安装器自动托管 / 任意兼容实现；WS 收事件 + HTTP 调接口）
src/onebot, src/gateway
▼
chat hub（白名单 → 群聊决策 → 停顿分段 → 引用/@/拍一拍）
▼
DSH Session（一群一会话，kinstra-social / kinstra-private 两个 preset）
+ systemPrompt.variable 注入人格、context 注入记忆、会话级 remember/recall 工具
▼ turn/end + assistant/message
回复拆条 → 气泡延迟 → OneBot send_msg（试运行则只记 observe）
| 模块 | 职责 |
|---|---|
src/config | zod 配置 schema、深合并默认、面板密钥脱敏 |
src/onebot | WS 指数退避重连、HTTP/WS 双通道、消息段解析（@/引用/图片/表情/语音/合并转发/卡片） |
src/chat/group-policy.ts | 纯函数发言决策，单测覆盖（必回 / 插话 / engaged / 冷却 / 静默 / burst） |
src/chat/hub.ts | 消息中枢：停顿聚合、编号引用、回复拆气泡与打字延迟 |
src/memory/store.ts | JSONL + 热群 LRU 倒排索引、BM25、遗忘曲线、人物档案 |
src/persona | Markdown 人格卡 CRUD、社交/私聊输出规则 |
src/sessions | DSH 会话生命周期与记忆工具（kinstra_remember / kinstra_recall） |
src/gateway | NapCat 安装目录探测、OneBot 配置生成、进程启停与健康检查（loopback + 令牌） |
src/client | 品牌插槽、配置面板、首启向导 |
| 内容 | 位置 |
|---|---|
| 插件全部配置 | ~/.dsh/plugins-data/kinstra-neko/config.json（一般只通过面板改） |
| 人格卡 | ~/.dsh/plugins-data/kinstra-neko/personas/*.md |
| 长期记忆 | ~/.dsh/plugins-data/kinstra-neko/memory/facts.jsonl |
| 试运行记录 | ~/.dsh/plugins-data/kinstra-neko/observe.jsonl |
| 聊天 → DSH 会话映射 | ~/.dsh/plugins-data/kinstra-neko/sessions.json |
| 模型 API Key | ~/.dsh/.credentials.yaml（0600） |
| profile / bundle | ~/.dsh/profiles/kinstra-neko/ |
面板「群聊与权限」：
config.group.overrides[群号] 可为单个群单独调一套。面板「人格」：直接编辑 Markdown 人格卡。输出约定写在卡里：
| 写法 | 含义 |
|---|---|
| 换行 | 拆成多条气泡 |
[沉默] | 本轮不说话 |
<reply:编号> | 引用回复对应编号的群消息 |
<at:QQ号> | 真 @ 群成员 |
<poke> | 拍一拍 |
完整规则见 personas/neko.md 与 src/persona/rules.ts。
sudo systemctl status kinstra-neko # 状态
sudo systemctl restart kinstra-neko # 重启
journalctl -u kinstra-neko -f # 实时日志
free -h # 确认 swap 已生效
面板「日志」标签也能看到插件侧最近 300 条分级日志；连接页提供一键测试与重连。
npm install --legacy-peer-deps # DSH 是 pnpm 生态，npm 需此开关
npm run typecheck # tsc --noEmit
npm test # vitest，56 个用例
npm run build # tsdown 双入口：lib/index.js + lib/client.js
# 装进本地 DSH 调试：
dsh kinstra-neko --from-default-profile web --dump-config >/dev/null # 仅首次
dsh plugin --profile kinstra-neko add "link:$PWD"
dsh --profile kinstra-neko --port 3090 # 控制台会自动打开带一次性 token 的页面
无真实 QQ 环境时，决策、消息解析、记忆、回复拆条均为纯函数，直接跑单测即可； 端到端链路有内存假 DSH host + 假 OneBot 的 e2e 测试覆盖。
MIT。本项目代码不包含任何第三方 QQ 美术素材；品牌图标与横幅均为原创 SVG。 接入的各协议端、DeepSeek Harness 各自遵循其许可证与条款。