you-should-know-relay

1import { atom, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Forwarded } from '../types'
5
6// The built-in plugin that draws the heads-up above the prompt. It sits in the
7// builtin tier, beneath this mod, so its `$.store.set` calls pass through here.
8const SOURCE = 'cc-plugin-you-should-know'
9const KEEP = 50
10
11const forwarded = atom(
12  { plugin: 'you-should-know-relay', key: 'forwarded' } as const,
13  [] as Forwarded,
14)
15// Kept in `$.store`, so a pause holds in every session until resumed.
16const PAUSED = 'isPaused'
17const readPaused = async ($: EngineInterface) => (await $.store.get(PAUSED)) === true
18
19type Offer = { line: string; explanation: string | undefined; shownAt: number | undefined }
20
21const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null
22
23// The built-in keeps one entry per session under its "sessions" key; an entry
24// whose `view.kind` is "offer" is the heads-up it shows now.
25export const offerFor = (sessions: unknown, sessionId: string): Offer | undefined => {
26  if (!Array.isArray(sessions)) return undefined
27  const entry: unknown = sessions.find(s => isRecord(s) && s.id === sessionId)
28  const view = isRecord(entry) ? entry.view : undefined
29  if (!isRecord(view) || view.kind !== 'offer' || typeof view.line !== 'string') return undefined
30  // Its lines end in an extra "." after a full-width stop ("…不到。.").
31  const line = view.line.trim().replace(/([。！？])\.$/, '$1')
32  if (line === '') return undefined
33  return {
34    line,
35    explanation:
36      typeof view.explanation === 'string' && view.explanation.trim() !== ''
37        ? view.explanation.trim()
38        : undefined,
39    shownAt: typeof view.shownAt === 'number' ? view.shownAt : undefined,
40  }
41}
42
43export const reminder = (offer: Offer) =>
44  [
45    '[you-should-know 轉送] Claude Code 內建的 you-should-know 外掛剛在提示框上方提醒使用者一件事，它判斷這是你還沒有明確告訴使用者的重點：',
46    '',
47    `「${offer.line}」`,
48    ...(offer.explanation === undefined ? [] : ['', `外掛的補充說明：${offer.explanation}`]),
49    '',
50    '這段文字由 you-should-know-relay mod 自動轉送，不是使用者打的字。請在接下來的回覆中處理這一點：若屬實，向使用者明確說明，並考慮它對目前工作的影響；若你判斷不成立或已經說明過，簡短說明理由即可。',
51  ].join('\n')
52
53export const register: Register = on => {
54  on('session.start', async ($, e, next) => {
55    await $.command.register({
56      name: 'you-should-know-relay',
57      description: '暫停或恢復把 you-should-know 的提醒轉給 Claude',
58    })
59
60    return next(e)
61  })
62
63  on('command.run', { command: 'you-should-know-relay' }, async $ => {
64    const paused = !(await readPaused($))
65    await $.store.set(PAUSED, paused)
66
67    return {
68      text: paused
69        ? '已暫停：you-should-know 的提醒不再轉給 Claude（再執行一次 /you-should-know-relay 恢復）'
70        : '已恢復：you-should-know 的提醒會自動轉給 Claude',
71    }
72  })
73
74  on('store.set', { key: 'sessions' }, async ($, e, next) => {
75    const result = await next(e)
76    if (next.origin.plugin !== SOURCE) return result
77
78    try {
79      const offer = offerFor(e.value, await $.session.id())
80      if (offer === undefined) return result
81
82      // The built-in rewrites "sessions" many times while one heads-up shows.
83      const id = `${offer.shownAt ?? ''}:${offer.line}`
84      let isNew = false
85      await update($, forwarded, list => {
86        isNew = !list.includes(id)
87        return isNew ? [...list, id].slice(-KEEP) : list
88      })
89      // A heads-up shown while paused is marked too, so resuming never sends it.
90      if (!isNew || (await readPaused($))) return result
91
92      try {
93        await $.session.append({
94          message: { type: 'user', content: [{ type: 'text', text: reminder(offer) }] },
95        })
96      } catch (error) {
97        // Not appended: let a later write of the same heads-up try again.
98        await update($, forwarded, list => list.filter(x => x !== id))
99        throw error
100      }
101      $.ui.toast('you-should-know：已把這則提醒轉給 Claude')
102    } catch (error) {
103      $.ui.log(`you-should-know-relay: not forwarded: ${String(error)}`, { to: 'debug' })
104    }
105    return result
106  })
107}
108

1// `${shownAt}:${line}` of each heads-up already forwarded this session.
2export type Forwarded = string[]
3
4declare module 'claude-code' {
5  interface PluginState {
6    'you-should-know-relay': { forwarded: Forwarded }
7  }
8}
9