@geekbeer/minion 3.49.1 → 3.50.0

package/core/lib/note-mentions.js

@@ -0,0 +1,54 @@
+/**
+ * Helpers for the note user-mention syntax: `@[Display Name](user:UUID)`.
+ *
+ * HQ stores notes as Markdown. When humans write `@[Yuno](user:abc-...)` in
+ * the note editor (via Ctrl+I), the minion needs to read it as a normal
+ * `@Yuno`-style attribution rather than the raw bracket form. These helpers
+ * normalize and parse that syntax so skills/runners do not have to reinvent it.
+ *
+ * The UUID is the stable identity; the display name is a snapshot at insertion
+ * time and is the human-friendly handle.
+ */
+
+// Allow short test ids too (>= 8 chars) so the helper is usable in fixtures
+// even when the canonical 36-char UUID is not present.
+const USER_MENTION_REGEX = /@\[([^\]\n]+?)\]\(user:([0-9a-fA-F-]{8,})\)/g
+
+/**
+ * Replace `@[Display Name](user:UUID)` with `@Display Name`.
+ * Pass minion-bound markdown through this before injecting into a prompt or
+ * task payload so Claude does not see the raw bracket syntax.
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function normalizeNoteMentions(markdown) {
+  if (typeof markdown !== 'string' || markdown.length === 0) return markdown
+  return markdown.replace(USER_MENTION_REGEX, (_match, name) => `@${name}`)
+}
+
+/**
+ * Extract every user mention as { userId, displayName } in document order.
+ * Useful when a workflow step needs to know "who wrote this note" without
+ * round-tripping through HQ.
+ *
+ * @param {string} markdown
+ * @returns {Array<{ userId: string, displayName: string }>}
+ */
+function extractNoteMentions(markdown) {
+  if (typeof markdown !== 'string' || markdown.length === 0) return []
+  const out = []
+  // RegExp.exec with /g maintains lastIndex on the regex itself, so use a fresh copy.
+  const re = new RegExp(USER_MENTION_REGEX.source, 'g')
+  let match
+  while ((match = re.exec(markdown)) !== null) {
+    out.push({ displayName: match[1], userId: match[2] })
+  }
+  return out
+}
+
+module.exports = {
+  USER_MENTION_REGEX,
+  normalizeNoteMentions,
+  extractNoteMentions,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "3.49.1",
+  "version": "3.50.0",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "linux/server.js",
   "bin": {

package/rules/core.md

@@ -390,6 +390,30 @@ hq note get <project_id> <note_id>
 hq note search <project_id> "キーワード"
 ```
 
+### ノート内のユーザーメンション
+
+人間ユーザーがノート編集UIで `Ctrl+I` を押すと、自分の発言を示すアバター付きチップが行頭に挿入される。マークダウン上は次の形式で永続化される:
+
+```
+@[Display Name](user:UUID)
+```
+
+ミニオンがノートを読む場合、この記法はそのままだと冗長なので、`@/Display Name` 表記に正規化してから処理する。`packages/minion/core/lib/note-mentions.js` のヘルパを使う:
+
+```js
+const { normalizeNoteMentions, extractNoteMentions } = require('./core/lib/note-mentions')
+
+// 例: ノート本文を読み取って正規化
+const normalized = normalizeNoteMentions(noteMarkdown)
+// "@Yuno が書きました。"
+
+// 例: 誰の発言かを抽出
+const mentions = extractNoteMentions(noteMarkdown)
+// [{ displayName: 'Yuno', userId: 'abc-...' }, ...]
+```
+
+UUIDは安定IDなので、表示名が変わっても発言者の同一性を判定できる。書き戻す側のミニオンは原則この記法を生成しないこと(人間専用の発言マーカー)。
+
 ### `~/files/` への保存
 
 バイナリファイルやユーザーがダウンロードする必要があるファイルは `~/files/` に配置する。