@aiwayds/dsh-topics-memory 0.6.0

package/src/sync.ts

@@ -0,0 +1,170 @@
+/**
+ * GitHub sync layer (ADR 0002/0003/0008) — active only when the `repo`
+ * setting is non-empty; local-only mode bypasses the whole module.
+ *
+ * Semantics: pull --rebase (autostash) on session start and before each
+ * push; push debounced (config, default 45s) after write-through commits,
+ * hard flush on session end / plugin dispose. A rebase conflict aborts the
+ * rebase and marks the conflicted topics — demoted in retrieval with a
+ * visible warning, resolved by hand (ADR 0003: no automatic smart merging).
+ *
+ * @module sync
+ */
+
+import { spawn } from 'node:child_process'
+import * as gitmod from './git.ts'
+import type { BundleStore } from './store.ts'
+
+export function remoteUrlFor(repo: string): string {
+  return `https://github.com/${repo}.git`
+}
+
+export interface SyncConfig {
+  /** `owner/name`; empty string = local-only mode. */
+  repo: string
+  pushDebounceSeconds: number
+}
+
+export type TokenResolver = () => Promise<string | undefined>
+export type UrlResolver = (repo: string) => string
+
+export class Sync {
+  private timer: NodeJS.Timeout | undefined
+  private pending = false
+  private inFlight: Promise<void> = Promise.resolve()
+  lastError = ''
+  lastPushAt?: string
+  lastPullAt?: string
+  private readonly store: BundleStore
+  private readonly cfg: () => SyncConfig
+  private readonly token: TokenResolver
+  private readonly urlFor: UrlResolver
+
+  constructor(store: BundleStore, cfg: () => SyncConfig, token: TokenResolver = defaultTokenResolver, urlFor: UrlResolver = remoteUrlFor) {
+    this.store = store
+    this.cfg = cfg
+    this.token = token
+    this.urlFor = urlFor
+  }
+
+  get active(): boolean {
+    return this.cfg().repo !== ''
+  }
+
+  /** Session start (or `/topics sync pull`): rebase onto remote, mark conflicts. */
+  async pull(): Promise<{ ok: boolean; conflicted: string[]; message: string }> {
+    if (!this.active) return { ok: true, conflicted: [], message: 'local-only 模式，无同步' }
+    const token = await this.safeToken()
+    await gitmod.setRemote(this.store.root, this.urlFor(this.cfg().repo))
+    if (!(await gitmod.remoteBranchExists(this.store.root, token))) {
+      this.lastPullAt = new Date().toISOString()
+      return { ok: true, conflicted: [], message: '远端还没有分支，跳过拉取' }
+    }
+    const outcome = await gitmod.pullRebase(this.store.root, token)
+    this.lastPullAt = new Date().toISOString()
+    if (outcome.ok) {
+      // A successful rebase clears previous conflict marks.
+      const prior = await this.store.getConflicts()
+      if (prior.size > 0) await this.store.setConflicts([])
+      return { ok: true, conflicted: [], message: '已与远端同步' }
+    }
+    const conflictedSlugs = outcome.conflicted.map((p) => p.replace(/^topics\//, '').replace(/\.md$/, ''))
+    if (conflictedSlugs.length > 0) {
+      await this.store.setConflicts(outcome.conflicted)
+    }
+    this.lastError = outcome.output.slice(-500)
+    return { ok: false, conflicted: conflictedSlugs, message: `rebase 冲突：${conflictedSlugs.join('、') || '未知路径'}（已标记降权，待手工解决）` }
+  }
+
+  /** Called after every write-through commit — schedules the debounced push. */
+  schedulePush(): void {
+    if (!this.active) return
+    this.pending = true
+    if (this.timer !== undefined) return
+    const seconds = Math.max(1, this.cfg().pushDebounceSeconds)
+    this.timer = setTimeout(() => {
+      this.timer = undefined
+      void this.flush()
+    }, seconds * 1000)
+    // Never hold the process open for a debounced push.
+    this.timer.unref?.()
+  }
+
+  /** Debounce flush, also used for session end and plugin dispose. */
+  async flush(): Promise<{ ok: boolean; message: string }> {
+    if (!this.active) return { ok: true, message: 'local-only 模式，无同步' }
+    this.pending = false
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer)
+      this.timer = undefined
+    }
+    const run = this.inFlight.then(async () => {
+      if (!(await this.store.hasGit())) return { ok: false, message: 'bundle 不是 git 仓库' }
+      const token = await this.safeToken()
+      await gitmod.setRemote(this.store.root, this.urlFor(this.cfg().repo))
+      if (await gitmod.remoteBranchExists(this.store.root, token)) {
+        const pre = await gitmod.pullRebase(this.store.root, token)
+        if (!pre.ok) {
+          const conflicted = pre.conflicted.map((p) => p.replace(/^topics\//, '').replace(/\.md$/, ''))
+          if (conflicted.length > 0) await this.store.setConflicts(pre.conflicted)
+          this.lastError = pre.output.slice(-500)
+          return { ok: false, message: `push 前 rebase 失败：${conflicted.join('、') || pre.output.slice(-120)}` }
+        }
+      }
+      const result = await gitmod.push(this.store.root, token)
+      if (result.ok) {
+        this.lastPushAt = new Date().toISOString()
+        this.lastError = ''
+        return { ok: true, message: '已推送到远端' }
+      }
+      this.lastError = result.output.slice(-500)
+      return { ok: false, message: `push 失败：${result.output.slice(-160)}` }
+    })
+    this.inFlight = run.then(
+      () => undefined,
+      () => undefined,
+    )
+    return run
+  }
+
+  /** Commit the meta sidecars (injection log, observations) — flush cadence. */
+  async commitMeta(): Promise<void> {
+    if (!this.active) return
+    await gitmod.addAndCommit(this.store.root, ['meta'], 'topics(meta): flush injection log / observations').catch(() => undefined)
+  }
+
+  dispose(): void {
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer)
+      this.timer = undefined
+    }
+  }
+
+  private async safeToken(): Promise<string | undefined> {
+    try {
+      return await this.token()
+    } catch {
+      return undefined
+    }
+  }
+}
+
+/** Env first, gh CLI fallback per dsh-vault precedent; login is never our job. */
+async function defaultTokenResolver(): Promise<string | undefined> {
+  const env = process.env.GITHUB_TOKEN?.trim()
+  if (env !== undefined && env !== '') return env
+  return ghCliToken()
+}
+
+/** gh CLI fallback per dsh-vault precedent; login is never this plugin's job. */
+async function ghCliToken(): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    const child = spawn('gh', ['auth', 'token'], { stdio: ['ignore', 'pipe', 'ignore'], env: process.env })
+    let out = ''
+    child.stdout?.on('data', (d: Buffer) => {
+      out += d.toString('utf8')
+    })
+    child.on('error', () => resolve(undefined))
+    child.on('close', (code) => resolve(code === 0 ? out.trim() || undefined : undefined))
+  })
+}

package/src/tools.ts

@@ -0,0 +1,225 @@
+/**
+ * Model-facing tools (ADR 0004 explicit channel): `topic_save`, `topic_search`,
+ * `topic_observe`, `topic_history`.
+ *
+ * @module tools
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { TopicsService } from './service.ts'
+
+const STRING_ARRAY = { type: 'array', items: { type: 'string' } } as const
+
+function preview(text: string, max = 240): string {
+  const line = text.split('\n').find((l) => l.trim() !== '') ?? ''
+  return line.length <= max ? line : `${line.slice(0, max)}…`
+}
+
+export function buildTopicTools(service: TopicsService) {
+  const topicSave = defineTool({
+    name: 'topic_save',
+    description:
+      'Create or update one Topic in the long-term topic memory (OKF bundle). ' +
+      'Use when a durable conclusion crystallizes: the topic name, what it depends on, open questions, ' +
+      'the current conclusion, its impact, and actionable recommendations. ' +
+      'Pass `slug` to update an existing topic; omit it to create a new one.',
+    parameters: {
+      title: { type: 'string', required: true, description: 'Human-readable topic name (immutable identity; renaming creates a new topic)' },
+      conclusion: { type: 'string', required: true, description: 'The current best conclusion, self-contained markdown prose' },
+      description: { type: 'string', description: 'One-line summary for indexes and snippets' },
+      tags: { ...STRING_ARRAY, description: 'Cross-cutting tags (project, domain, component); lowercased on save' },
+      depends: { ...STRING_ARRAY, description: 'Slugs of prerequisite topics (topics this one builds on)' },
+      open_questions: { ...STRING_ARRAY, description: 'Unresolved questions this topic still carries' },
+      impact: { ...STRING_ARRAY, description: 'What this conclusion affects: topics, projects, decisions' },
+      recommendations: { type: 'string', description: 'Actionable recommendation following from the conclusion' },
+      status: { type: 'string', description: 'Lifecycle: draft (default) | stable | deprecated' },
+      slug: { type: 'string', description: 'Existing topic slug to update; omit to create' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          slug: { type: 'string', required: true },
+          path: { type: 'string', required: true },
+          created: { type: 'boolean', required: true },
+          committed: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [
+        {
+          type: 'text' as const,
+          text: `${value.created ? 'Created' : 'Updated'} topic \`${value.slug}\` → ${value.path}${value.committed ? ' (committed)' : ''}`,
+        },
+      ],
+    },
+    async execute(args) {
+      const result = await service.saveTopic({
+        title: args.title,
+        conclusion: args.conclusion,
+        description: args.description,
+        tags: args.tags,
+        depends: args.depends,
+        openQuestions: args.open_questions,
+        impact: args.impact,
+        recommendations: args.recommendations,
+        status: args.status === 'draft' || args.status === 'stable' || args.status === 'deprecated' ? args.status : undefined,
+        slug: args.slug,
+        source: 'model',
+      })
+      return { slug: result.slug, path: result.path, created: result.created, committed: result.committed }
+    },
+  })
+
+  const topicSearch = defineTool({
+    name: 'topic_search',
+    description:
+      'Search the long-term topic memory by keywords (hot path, no LLM). ' +
+      'Use when the user references past work, or when injected topic memory hints at related history.',
+    parameters: {
+      query: { type: 'string', required: true, description: 'What to recall from topic memory' },
+      top_k: { type: 'number', description: 'Max results (default 8)' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          results: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                slug: { type: 'string', required: true },
+                title: { type: 'string', required: true },
+                status: { type: 'string', required: true },
+                score: { type: 'number', required: true },
+                preview: { type: 'string', required: true },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => [
+        {
+          type: 'text' as const,
+          text:
+            value.results.length === 0
+              ? 'No topic memory found for this query.'
+              : value.results
+                  .map((r: { slug: string; title: string; status: string; score: number; preview: string }) => `### ${r.title} [${r.status}] (${r.slug} score:${r.score.toFixed(2)})\n${r.preview}`)
+                  .join('\n\n'),
+        },
+      ],
+    },
+    async execute(args) {
+      const outcome = await service.search(args.query, args.top_k)
+      const roster = new Map((await service.roster()).map((r) => [r.slug, r]))
+      const docs = await Promise.all(
+        outcome.hits.map(async (h) => {
+          const doc = await service.store.readTopic(h.slug).catch(() => undefined)
+          return { hit: h, doc }
+        }),
+      )
+      return {
+        results: docs.flatMap(({ hit, doc }) => {
+          const meta = roster.get(hit.slug)
+          if (doc === undefined || meta === undefined) return []
+          const conclusion = extractConclusion(doc.body)
+          return [
+            {
+              slug: hit.slug,
+              title: doc.fm.title,
+              status: doc.fm.status,
+              score: hit.score,
+              preview: preview(conclusion !== '' ? conclusion : (doc.fm.description ?? '')),
+            },
+          ]
+        }),
+      }
+    },
+  })
+
+  const topicObserve = defineTool({
+    name: 'topic_observe',
+    description:
+      'Record one atomic observation (a decision, finding, constraint, or open question) as raw material ' +
+      'for later distillation into topic memory. Cheap and safe to call mid-task; prefer topic_save when a ' +
+      'full conclusion is already settled.',
+    parameters: {
+      kind: { type: 'string', required: true, description: 'One of: decision | finding | constraint | question' },
+      text: { type: 'string', required: true, description: 'The observation, one atomic statement' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: { id: { type: 'string', required: true } },
+      },
+      render: (_args, value) => [{ type: 'text' as const, text: `Observed (${value.id})` }],
+    },
+    async execute(args) {
+      const kind = args.kind === 'decision' || args.kind === 'finding' || args.kind === 'constraint' || args.kind === 'question' ? args.kind : 'finding'
+      const obs = await service.observe({ kind, text: args.text })
+      return { id: obs.id }
+    },
+  })
+
+  const topicHistory = defineTool({
+    name: 'topic_history',
+    description:
+      'Show the git history of one topic — how its conclusion changed over time, commit by commit. ' +
+      'Use when the user asks when/why a conclusion changed or wants to trace a decision.',
+    parameters: {
+      slug: { type: 'string', required: true, description: 'Topic slug' },
+      limit: { type: 'number', description: 'Max commits (default 20)' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          entries: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                hash: { type: 'string', required: true },
+                date: { type: 'string', required: true },
+                message: { type: 'string', required: true },
+                conclusion: { type: 'string' },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => [
+        {
+          type: 'text' as const,
+          text:
+            value.entries.length === 0
+              ? 'No history (topic unknown or bundle not a git repo).'
+              : value.entries
+                  .map((e: { hash: string; date: string; message: string; conclusion?: string }) => `- ${e.hash} ${e.date} ${e.message}${e.conclusion !== undefined ? `\n  结论当时: ${e.conclusion}` : ''}`)
+                  .join('\n'),
+        },
+      ],
+    },
+    async execute(args) {
+      const { entries } = await service.history(args.slug, args.limit ?? 20)
+      return { entries: entries.map((e) => ({ ...e, conclusion: e.conclusion as string | undefined })) }
+    },
+  })
+
+  return [topicSave, topicSearch, topicObserve, topicHistory]
+}
+
+function extractConclusion(body: string): string {
+  // Local copy to avoid importing okf section helpers into the hot render path.
+  const m = /^# Conclusion\s*\n+([\s\S]*?)(?=\n# |\s*$)/im.exec(body)
+  return m === null ? '' : m[1].trim()
+}