amiru 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 huabuyu233
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,219 @@
-# Temporary Holding Version
+# Amiru
+
+**Amiru** 是一个运行在 DeepSeek Harness 上的 QQ AI 陪伴运行时。角色由人设卡决定，而不是写死在代码里；它不自己连接 QQ，也不复制 QQ 插件，而是复用官方 QQ 机器人插件的会话与出站能力。
+
+它只做四件事：
+
+1. **收/发官方 QQ 消息**：复用 [`@tencent-connect/dsh-qqbot`](https://www.npmjs.com/package/@tencent-connect/dsh-qqbot) 的 session、preset、出站与主动投递。
+2. **按用户隔离的长期记忆**：以 `account_id + chat_key` 为边界，不按昵称、不跨用户共享。
+3. **可直接编辑的人设卡**：Markdown 文件放在本地，改完下一轮生效，不是黑盒。
+4. **克制的主动对话**：静默时长、免打扰、每日上限、连续未回退避；触发后走一轮正常 Agent 回合。
+
+> Amiru 是“陪伴运行时”，不是“恋爱模拟器”。默认人设卡只是一个示例，你可以把它换成任何角色：朋友、搭档、树洞、虚构人物，或完全自定义的存在。
+
+## 状态
+
+当前是 **可运行的原型**：已在 DSH + 官方 QQ 机器人上跑通私聊收发、首轮人设注入与记忆写入。主动回合已实现，仍需要更多 live 验证。
+
+主动消息需要 QQ 插件包含 `proactiveDelivery.externalTurns`。仓库市面上的 `dsh-qqbot` v0.5.5 旧构建没有这个能力；请使用带该能力的源码版本（见下文）。
+
+## 架构
+
+```text
+QQ 用户
+  ↕  QQ WebSocket
+@tencent-connect/dsh-qqbot
+  ↕  DSH Agent / session / outbound
+Amiru
+  ├─ binding：哪个 QQ 会话用哪张人设卡
+  ├─ prompt：静态人设、关系状态、记忆上下文
+  ├─ memory：本地 JSON / JSONL，按 binding 隔离
+  └─ proactive：定时评估，通过 Agent.followup() 发起正常回合
+```
+
+Amiru **不新开第二条 QQ 连接**，也不绕过 QQ 插件的发送链路。
+
+## 环境要求
+
+- DeepSeek Harness（DSH）
+- 已安装并启用的官方 QQ 机器人插件 `@tencent-connect/dsh-qqbot`
+- QQ 开放平台机器人 `appId` / `appSecret`
+- Node.js 20+
+- 可选的源码版 QQ 插件，用于主动消息投递
+
+## 安装
+
+### 从源码安装（当前推荐）
+
+先安装带 `externalTurns` 的 QQ 插件源码版：
+
+```text
+plugin_manager install_bundle target="/absolute/path/to/dsh-qqbot"
+```
+
+如果该源码包是 `link:` 安装，`plugin_manager` 不会替它安装依赖。先在其目录执行：
+
+```bash
+pnpm install --prod --ignore-scripts
+```
+
+再安装 Amiru：
+
+```text
+plugin_manager install_bundle target="/absolute/path/to/amiru"
+```
+
+安装后重启 DSH，确认插件列表出现 `Amiru`。
+
+### 从 npm 安装（发布后）
+
+```text
+plugin_manager install_bundle target="amiru@0.1.0"
+```
+
+## QQ 插件配置
+
+在 QQ 机器人插件的配置中确认：
+
+- `appId` / `appSecret` 已填写；
+- 私聊访问模式允许你的账号；
+- `proactiveDelivery.externalTurns` 为 `c2c`（只私聊）或 `all`（私聊和群聊）；
+- 建议给陪伴会话单独设置一个 Agent preset，避免和编码助手共用同一套工具与提示词。
+
+如果 DSH 通过系统代理启动，而代理不可用或不代理 QQ，请在启动 DSH 前设置：
+
+```text
+NO_PROXY=localhost,127.0.0.1,api.sgroup.qq.com,bots.qq.com,q.qq.com
+```
+
+Windows 可以用：
+
+```powershell
+setx NO_PROXY "localhost,127.0.0.1,api.sgroup.qq.com,bots.qq.com,q.qq.com"
+```
+
+然后**完全退出并重新打开 DSH**。QQ 的 token 域名是 `bots.qq.com`，OpenAPI 是 `api.sgroup.qq.com`；漏掉前者会一直报 `ECONNREFUSED 127.0.0.1:7890`。
+
+## 人设卡
+
+首次启动会自动生成：
+
+```text
+~/.amiru/personas/default.md
+```
+
+直接编辑这个 Markdown。标题就是段落名；`〔私聊〕` 只注入私聊，`〔群聊〕` 只注入群聊，不写标记则两边都用。
+
+```markdown
+# 名字
+阿梨
+
+# 年龄与身份
+24 岁，在城市里做独立插画师。
+
+# 性格
+温柔，有自己的边界；会吐槽，但不刻薄。
+
+# 说话方式
+短句，口语化。不用客服腔，不列清单，不主动说“我可以帮你……”。
+
+# 〔私聊〕关系边界
+亲密但不低俗；不查岗，不要求秒回。
+
+# 禁止
+不要自称 AI 助手、心理咨询师或客服。
+```
+
+改完下一轮生效，不需要重启。也可以新增 `~/.amiru/personas/another.md`，把 binding 的 `personaId` 改成 `another`。
+
+**选卡提示**：从 SillyTavern / Chub / JanitorAI 等社区拿到的角色卡不能直接导入，需要改写成 Markdown；删掉 `{{char}}` / `{{user}}` 等模板语法，控制在 6000 字符以内。
+
+## 记忆
+
+```text
+~/.amiru/
+  bindings.json      # 每个 QQ 私聊/群聊的 binding
+  memories.json      # 结构化长期记忆
+  messages.jsonl     # 最近对话，最多 5000 条
+  personas/          # 人设卡
+```
+
+- 以 `account_id + chat_key` 隔离，不用昵称做 key，避免同名串记忆。
+- 每轮确定性写入用户/助手消息；`amiru_remember` 工具让模型在明确事实、偏好、承诺、日期、边界时主动记一条。
+- 规则扫描会兜底记录“我叫… / 我喜欢… / 我答应… / 记住…”这类句子。
+- 注入预算默认 1400 字，只放关系状态、长期记忆、上一次会话的最近几条，避免和当前对话重复。
+- 所有数据都在本机，没有遥测，也不会上传到第三方。
+
+### 从旧版迁移
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+0.1.0 之前这个项目先后叫过 **AIGirl** 和 **Ami**，两个旧数据目录都可以直接搬过来：
+
+```bash
+cp -a ~/.ami ~/.amiru     # 从 Ami 版本升级
+cp -a ~/.aigirl ~/.amiru  # 或从更早的 AIGirl 版本升级
+```
+
+然后重新安装 Amiru，并把 binding 的 `personaId` 指向 `~/.amiru/personas/` 下的文件。
+
+
+## 主动对话
+
+默认策略：
+
+| 项 | 默认 |
+|---|---|
+| 静默多久才考虑 | 120 分钟 |
+| 两次主动最小间隔 | 120 分钟 |
+| 每天上限 | 2 条 |
+| 至少聊过 | 3 条用户消息 |
+| 免打扰 | 23:30–08:00 |
+| 连续未回 | 2 次后 48 小时不再发 |
+
+触发优先级：连续未回后的轻接话 → 长时间沉默 → 日常想起。提示词要求给出具体由头，并直接输出一句自然、简短、可以立刻发出去的话。
+
+> **为什么没有 `<SKIP>`**：`agent.followup()` 产生的 assistant 文本会由 QQ 插件直接出站，出站层无法可靠拦截占位符。因此主动回合在硬门通过后才生成，提示词不再提供“跳过”选项，避免把 `<SKIP>` 原样发给用户。
+
+## 配置
+
+`cordis.patch.yml` 里的 `config` 可改：
+
+```yaml
+enabled: true
+defaultPersona: default
+dataDir: ~/.amiru
+proactive:
+  enabled: true
+  idleMinutes: 120
+  minIntervalMinutes: 120
+  dailyCap: 2
+  minUserMessages: 3
+  quietStart: '23:30'
+  quietEnd: '08:00'
+  maxUnanswered: 2
+  backoffHours: 48
+```
+
+`qqPrefsPath` 默认读 `~/.dsh-qqbot/model-prefs.json`，也可用环境变量 `QQBOT_DATA_DIR`。
+
+## 开发
+
+```bash
+node --test test/*.test.js
+npm run check
+```
+
+代码结构：
+
+- `index.js`：事件接线、QQ session 识别、主动 tick。
+- `src/persona.js`：Markdown 人设卡解析与 scope 过滤。
+- `src/qq.js`：`qqbot:<appId>:<scope>:<peerId>` 解析与 prefs 反查。
+- `src/store.js`：binding / message / memory 持久化。
+- `src/memory.js`：关系摘要、记忆注入、规则兜底。
+- `src/proactive.js`：硬门、评分、主动提示词。
+- `src/prompt.js`：`amiru:*` system prompt 段与 `amiru_remember` 工具。
+
+详细设计见 [`docs/plugin-design.md`](docs/plugin-design.md) 与 [`docs/runtime-spec.md`](docs/runtime-spec.md)。
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,16 @@
+- insert:
+    - id: amiru
+      name: 'amiru'
+      config:
+        enabled: true
+        defaultPersona: default
+        proactive:
+          enabled: true
+          idleMinutes: 120
+          minIntervalMinutes: 120
+          dailyCap: 2
+          minUserMessages: 3
+          quietStart: '23:30'
+          quietEnd: '08:00'
+          maxUnanswered: 2
+          backoffHours: 48

package/icon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="AI companion">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#ff8fb1"/>
+      <stop offset="1" stop-color="#8f7bff"/>
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="16" fill="url(#g)"/>
+  <path d="M20 24c0-6 5-10 12-10s12 4 12 10v9c0 7-5 12-12 12s-12-5-12-12z" fill="#fff" opacity=".94"/>
+  <circle cx="27" cy="29" r="2" fill="#5b4b8a"/>
+  <circle cx="37" cy="29" r="2" fill="#5b4b8a"/>
+  <path d="M27 37c3 2 7 2 10 0" fill="none" stroke="#5b4b8a" stroke-width="2" stroke-linecap="round"/>
+</svg>

package/index.js

@@ -0,0 +1,191 @@
+import { normalizeConfig } from './src/config.js'
+import { AmiruStore } from './src/store.js'
+import { PersonaStore } from './src/persona.js'
+import { QQSessionIndex } from './src/qq.js'
+import { buildRecallHint, maybeAutoRemember } from './src/memory.js'
+import { buildProactivePrompt, dayKey, evaluateProactive } from './src/proactive.js'
+import { attachPrompt } from './src/prompt.js'
+import { eventIdentity, extractEventText, isProactiveUserMessage, isUserMessageEvent } from './src/session-events.js'
+
+export const name = 'amiru'
+export const inject = ['agents']
+
+function safeLog(ctx, level, message) {
+  try {
+    ctx?.logger?.[level]?.(`[amiru] ${message}`)
+  } catch {
+    // Logging must never break a turn.
+  }
+}
+
+export function apply(ctx, rawConfig = {}) {
+  const config = normalizeConfig(rawConfig)
+  if (!config.enabled) return
+
+  const store = new AmiruStore(config.dataDir)
+  const personas = new PersonaStore(config.personaDir, {
+    defaultPersona: config.defaultPersona,
+    maxChars: config.maxPersonaChars,
+  })
+  const qq = new QQSessionIndex(config.qqPrefsPath)
+  const retryTimers = new Set()
+  const inFlightProactive = new Set()
+  const seenEvents = new Set()
+
+  function rememberSeen(key) {
+    seenEvents.add(key)
+    if (seenEvents.size > 4000) {
+      const first = seenEvents.values().next().value
+      seenEvents.delete(first)
+    }
+  }
+
+  function ensureBinding(sessionId) {
+    const info = qq.resolve(sessionId)
+    if (!info) return null
+    return store.ensureBinding({
+      accountId: info.accountId,
+      chatKey: info.chatKey,
+      scope: info.scope,
+      peerId: info.peerId,
+      sessionId,
+      appId: info.appId,
+      personaId: config.defaultPersona,
+    })
+  }
+
+  function attachFor(sessionId, agent) {
+    const live = agent ?? ctx.agents.get(sessionId)
+    const agentCtx = live?.ctx
+    if (!agentCtx) return false
+    const ok = attachPrompt(agentCtx, {
+      resolveBinding: () => ensureBinding(sessionId),
+      store,
+      personaStore: personas,
+      config,
+    })
+    if (ok) safeLog(ctx, 'info', `attached session=${sessionId}`)
+    return ok
+  }
+
+  function attachWithRetry(sessionId, agent) {
+    if (attachFor(sessionId, agent)) return
+    // The QQ plugin persists its sessionId after agents.create/resume returns.
+    // A short retry closes that ordering gap without blocking agent creation.
+    for (const delay of [0, 25, 100, 300, 1000]) {
+      if (delay === 0) continue
+      const timer = setTimeout(() => {
+        retryTimers.delete(timer)
+        if (attachFor(sessionId, agent)) {
+          for (const other of retryTimers) clearTimeout(other)
+          retryTimers.clear()
+        }
+      }, delay)
+      timer.unref?.()
+      retryTimers.add(timer)
+    }
+  }
+
+  ctx.on('agent/created', ({ agent } = {}) => {
+    const sessionId = agent?.id
+    if (!sessionId) return
+    attachWithRetry(sessionId, agent)
+  })
+
+  ctx.on('session/event', (session, event) => {
+    const sessionId = session?.id
+    if (!sessionId || !event?.type) return
+    const eventKey = eventIdentity(sessionId, event)
+    if (seenEvents.has(eventKey)) return
+    rememberSeen(eventKey)
+
+    const binding = ensureBinding(sessionId)
+    if (!binding) return
+
+    if (event.type === 'user/message') {
+      if (!isUserMessageEvent(event)) return
+      const text = extractEventText(event)
+      if (!text || isProactiveUserMessage(event)) return
+      store.appendMessage({ bindingId: binding.bindingId, sessionId, role: 'user', message: event.data, time: event.time })
+      store.recordUserMessage(binding.bindingId, event.time ?? Date.now())
+      maybeAutoRemember(store, binding, text)
+      attachFor(sessionId)
+      return
+    }
+
+    if (event.type === 'assistant/message') {
+      const message = event.data?.message
+      const text = extractEventText(event)
+      if (!text) return
+      store.appendMessage({ bindingId: binding.bindingId, sessionId, role: 'assistant', message, time: event.time })
+      store.recordAssistantMessage(binding.bindingId, event.time ?? Date.now())
+    }
+  })
+
+  async function runProactiveFor(binding) {
+    if (inFlightProactive.has(binding.bindingId)) return
+    const decision = evaluateProactive({ binding, config })
+    if (!decision.allowed) return
+    inFlightProactive.add(binding.bindingId)
+    try {
+      let agent = ctx.agents.get(binding.sessionId)
+      if (!agent) {
+        try {
+          const handle = await ctx.agents.resume({
+            resumeSessionId: binding.sessionId,
+            setup: (agentCtx) => {
+              attachPrompt(agentCtx, {
+                resolveBinding: () => store.getBinding(binding.bindingId) || binding,
+                store,
+                personaStore: personas,
+                config,
+              })
+            },
+          })
+          agent = handle.agent
+        } catch (error) {
+          safeLog(ctx, 'warn', `resume failed session=${binding.sessionId}: ${error?.message ?? error}`)
+          return
+        }
+      }
+
+      const recallHint = buildRecallHint({ store, binding, config })
+      const prompt = buildProactivePrompt({
+        binding,
+        recallHint,
+        trigger: decision.trigger,
+      })
+      await agent.followup({
+        content: [{ type: 'text', text: prompt }],
+        source: { kind: 'user' },
+      })
+      store.recordProactive(binding.bindingId, dayKey(), Date.now())
+      safeLog(ctx, 'info', `proactive sent session=${binding.sessionId} trigger=${decision.trigger}`)
+    } catch (error) {
+      safeLog(ctx, 'warn', `proactive failed: ${error?.message ?? error}`)
+    } finally {
+      inFlightProactive.delete(binding.bindingId)
+    }
+  }
+
+  async function proactiveTick() {
+    if (!config.proactive.enabled) return
+    for (const binding of store.listBindings()) {
+      await runProactiveFor(binding)
+    }
+  }
+
+  ctx.effect(() => {
+    const timer = setInterval(() => {
+      proactiveTick().catch((error) => safeLog(ctx, 'warn', `tick failed: ${error?.message ?? error}`))
+    }, config.proactive.tickSeconds * 1000)
+    timer.unref?.()
+    return () => {
+      clearInterval(timer)
+      for (const pending of retryTimers) clearTimeout(pending)
+      retryTimers.clear()
+    }
+  })
+
+  safeLog(ctx, 'info', `ready data=${config.dataDir} personas=${config.personaDir}`)
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Amiru",
+    "description": "Persona-driven AI companion runtime for QQ: editable persona cards, per-user memory, and restrained proactive care."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Amiru 陪伴",
+    "description": "人设驱动的 QQ AI 陪伴运行时：可编辑人设、按用户隔离的长期记忆、克制的主动关心。"
+  }
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "amiru",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Persona-driven AI companion runtime for the official QQ bot plugin in DeepSeek Harness",
+  "license": "MIT",
+  "author": "huabuyu233",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/huabuyu233/amiru.git"
+  },
+  "homepage": "https://github.com/huabuyu233/amiru#readme",
+  "bugs": {
+    "url": "https://github.com/huabuyu233/amiru/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "src/*.js",
+    "locale/*.json",
+    "icon.svg",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "check": "node --check index.js && node --check src/config.js && node --check src/store.js && node --check src/persona.js && node --check src/memory.js && node --check src/proactive.js && node --check src/qq.js && node --check src/prompt.js && node --check src/session-events.js"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "qqbot",
+    "ai-companion",
+    "persona",
+    "memory",
+    "proactive"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/config.js

@@ -0,0 +1,64 @@
+import { homedir } from 'node:os'
+import { isAbsolute, resolve } from 'node:path'
+
+function pick(value, fallback) {
+  return value === undefined || value === null || value === '' ? fallback : value
+}
+
+function positive(value, fallback) {
+  const n = Number(value)
+  return Number.isFinite(n) && n > 0 ? n : fallback
+}
+
+function nonNegative(value, fallback) {
+  const n = Number(value)
+  return Number.isFinite(n) && n >= 0 ? n : fallback
+}
+
+function timeString(value, fallback) {
+  const s = String(value ?? '')
+  return /^\d{2}:\d{2}$/.test(s) ? s : fallback
+}
+
+export function resolveDataDir(raw) {
+  const value = String(raw ?? '').trim()
+  if (!value) return resolve(homedir(), '.amiru')
+  return isAbsolute(value) ? resolve(value) : resolve(process.cwd(), value)
+}
+
+export function resolveQQPrefsPath(raw) {
+  const value = String(raw ?? '').trim()
+  if (value) return isAbsolute(value) ? resolve(value) : resolve(process.cwd(), value)
+  const qqHome = String(process.env.QQBOT_DATA_DIR ?? '').trim()
+  if (qqHome) return resolve(qqHome, 'model-prefs.json')
+  return resolve(homedir(), '.dsh-qqbot', 'model-prefs.json')
+}
+
+export function normalizeConfig(raw = {}) {
+  const dataDir = resolveDataDir(raw.dataDir)
+  const proactive = raw.proactive && typeof raw.proactive === 'object' ? raw.proactive : {}
+  return {
+    enabled: raw.enabled !== false,
+    dataDir,
+    personaDir: raw.personaDir ? resolveDataDir(raw.personaDir) : resolve(dataDir, 'personas'),
+    defaultPersona: String(pick(raw.defaultPersona, 'default')).replace(/[^a-zA-Z0-9_-]/g, '') || 'default',
+    maxPersonaChars: positive(raw.maxPersonaChars, 6000),
+    memoryMessageLimit: positive(raw.memoryMessageLimit, 10),
+    memoryItemLimit: positive(raw.memoryItemLimit, 8),
+    memoryMaxChars: positive(raw.memoryMaxChars, 1400),
+    qqPrefsPath: resolveQQPrefsPath(raw.qqPrefsPath),
+    toolsEnabled: raw.toolsEnabled !== false,
+    proactive: {
+      enabled: proactive.enabled !== false,
+      idleMinutes: positive(proactive.idleMinutes, 120),
+      minIntervalMinutes: positive(proactive.minIntervalMinutes, 120),
+      dailyCap: nonNegative(proactive.dailyCap, 2),
+      minUserMessages: nonNegative(proactive.minUserMessages, 3),
+      quietStart: timeString(proactive.quietStart, '23:30'),
+      quietEnd: timeString(proactive.quietEnd, '08:00'),
+      maxUnanswered: nonNegative(proactive.maxUnanswered, 2),
+      backoffHours: positive(proactive.backoffHours, 48),
+      tickSeconds: positive(proactive.tickSeconds, 60),
+    },
+  }
+}