@codehourra/llm-iwiki 0.1.0

package/src/skills.ts

@@ -0,0 +1,168 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+export type SkillTarget = 'codex' | 'claude-code' | 'cursor'
+
+export const SKILL_TARGETS = ['codex', 'claude-code', 'cursor'] as const satisfies readonly SkillTarget[]
+
+export interface InitSkillsOptions {
+  cwd: string
+  target: SkillTarget | null
+  force: boolean
+  dryRun: boolean
+}
+
+export interface InitSkillsResult {
+  written: string[]
+  skipped: string[]
+}
+
+interface SkillTemplate {
+  directory: string
+  content: string
+}
+
+const TARGET_NAMES: Record<SkillTarget, string> = {
+  codex: 'Codex',
+  'claude-code': 'Claude Code',
+  cursor: 'Cursor',
+}
+
+const SKILL_TEMPLATES: SkillTemplate[] = [
+  {
+    directory: 'aiwiki-after-session',
+    content: `---
+name: aiwiki-after-session
+description: Capture session knowledge into llm-iwiki summaries, experiences, and Obsidian export after project work.
+---
+
+# AIWiki After Session
+
+Use this skill after a meaningful coding or design session in the current project.
+
+## Steps
+
+1. Sync the current project:
+   \`\`\`bash
+   llm-iwiki sync --project .
+   \`\`\`
+2. Prepare changed summaries:
+   \`\`\`bash
+   llm-iwiki summarize prepare changed --project . --out .llm-iwiki/tasks/summaries-task.md
+   \`\`\`
+3. Generate \`.llm-iwiki/tasks/summaries.yaml\` from the prepared task.
+4. Apply the summaries:
+   \`\`\`bash
+   llm-iwiki summarize apply --project . --file .llm-iwiki/tasks/summaries.yaml
+   \`\`\`
+5. Prepare experience proposals from changed summaries:
+   \`\`\`bash
+   llm-iwiki experiences prepare --project . --from changed-summaries --out .llm-iwiki/tasks/experiences-task.md
+   \`\`\`
+6. Generate \`.llm-iwiki/tasks/experiences.yaml\` from the prepared task.
+7. Propose the experiences:
+   \`\`\`bash
+   llm-iwiki experiences propose --project . --file .llm-iwiki/tasks/experiences.yaml
+   \`\`\`
+8. Export project knowledge to Obsidian:
+   \`\`\`bash
+   llm-iwiki obsidian export --project .
+   \`\`\`
+`,
+  },
+  {
+    directory: 'aiwiki-before-debug',
+    content: `---
+name: aiwiki-before-debug
+description: Search project memory before debugging so related history is visible before changing code.
+---
+
+# AIWiki Before Debug
+
+Use this skill before investigating a bug, failure, error message, or confusing behavior.
+
+## Steps
+
+1. Search the full project knowledge index:
+   \`\`\`bash
+   llm-iwiki search "<error or topic>" --project . --index all
+   \`\`\`
+2. Read any related summaries, experiences, or prior decisions before editing code.
+3. Report whether related history was found, and name the most relevant item when it was found.
+`,
+  },
+  {
+    directory: 'aiwiki-project-retrospective',
+    content: `---
+name: aiwiki-project-retrospective
+description: Review recent project knowledge and extract retrospective themes from llm-iwiki.
+---
+
+# AIWiki Project Retrospective
+
+Use this skill when preparing a project retrospective or looking for recent repeated lessons.
+
+## Steps
+
+1. Prepare a retrospective from recent project history:
+   \`\`\`bash
+   llm-iwiki experiences prepare --project . --from all-recent --since 30d --out .llm-iwiki/tasks/retrospective-task.md
+   \`\`\`
+2. Review the prepared task for repeated themes, unresolved questions, and process improvements.
+3. Capture any accepted learnings through the normal llm-iwiki experience proposal flow.
+`,
+  },
+]
+
+function appendTargetGuidance(content: string, target: SkillTarget | null): string {
+  if (!target) return content
+
+  return `${content}
+## Tool Target
+
+This skill is initialized for ${TARGET_NAMES[target]}.
+`
+}
+
+function isFileExistsError(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'EEXIST'
+}
+
+export function initSkills(options: InitSkillsOptions): InitSkillsResult {
+  const written: string[] = []
+  const skipped: string[] = []
+
+  for (const template of SKILL_TEMPLATES) {
+    const filePath = join(options.cwd, '.agents', 'skills', template.directory, 'SKILL.md')
+
+    if (existsSync(filePath) && !options.force) {
+      skipped.push(filePath)
+      continue
+    }
+
+    written.push(filePath)
+
+    if (options.dryRun) {
+      continue
+    }
+
+    mkdirSync(dirname(filePath), { recursive: true })
+    const content = appendTargetGuidance(template.content, options.target)
+    if (options.force) {
+      writeFileSync(filePath, content)
+      continue
+    }
+
+    try {
+      writeFileSync(filePath, content, { flag: 'wx' })
+    } catch (error) {
+      if (!isFileExistsError(error)) {
+        throw error
+      }
+      written.pop()
+      skipped.push(filePath)
+    }
+  }
+
+  return { written, skipped }
+}

package/src/summarize.ts

@@ -0,0 +1,122 @@
+import type { ParsedSummariesYaml } from './types'
+import type { LlmIwikiDatabase } from './db'
+import { compactTranscript } from './compaction'
+import { getSessionMessages, listSessionsToSummarize } from './sessions'
+
+export interface PrepareSummariesResult {
+  markdown: string
+  sessionCount: number
+}
+
+const SUMMARIES_FORMAT = `## 输出格式
+
+请阅读下面每个会话的压缩记录，为有价值的会话生成一份 \`summaries.yaml\`，写入
+\`.llm-iwiki/tasks/summaries.yaml\`，再运行 \`llm-iwiki summarize apply\`。
+
+\`\`\`yaml
+project_id: <见下方 project_id>
+summaries:
+  - session_id: <会话的 session_id，原样照抄>
+    title: <一句话标题>
+    value: none | low | medium | high
+    summary_markdown: |
+      用 Markdown 概括这次会话解决了什么问题、关键决策、结论。
+\`\`\`
+
+要求：
+- \`value\` 表示这次会话的沉淀价值，\`medium\` / \`high\` 会进入经验提取。
+- \`session_id\` 必须与下面给出的完全一致。
+- 没有价值的会话可以省略，不必每个都写。`
+
+export function prepareSummariesTask(
+  db: LlmIwikiDatabase,
+  projectId: string,
+  scope: 'changed' | 'all',
+): PrepareSummariesResult {
+  const sessions = listSessionsToSummarize(db, projectId, scope)
+
+  const blocks: string[] = []
+  for (const session of sessions) {
+    const messages = getSessionMessages(db, session.id)
+    if (messages.length === 0) continue
+    const transcript = compactTranscript(messages)
+    blocks.push(
+      [
+        `### ${session.id}`,
+        `- source: ${session.sourceId}`,
+        `- title: ${session.title ?? '(无标题)'}`,
+        `- messages: ${session.messageCount}`,
+        '',
+        transcript,
+      ].join('\n'),
+    )
+  }
+
+  const markdown = [
+    `# Summaries Task`,
+    '',
+    `project_id: ${projectId}`,
+    `scope: ${scope}`,
+    `sessions: ${blocks.length}`,
+    '',
+    SUMMARIES_FORMAT,
+    '',
+    '---',
+    '',
+    blocks.join('\n\n---\n\n'),
+    '',
+  ].join('\n')
+
+  return { markdown, sessionCount: blocks.length }
+}
+
+export interface ApplySummariesResult {
+  written: number
+  skipped: string[]
+}
+
+function hash(value: string): string {
+  return Bun.hash(value).toString(16)
+}
+
+export function applySummaries(db: LlmIwikiDatabase, parsed: ParsedSummariesYaml): ApplySummariesResult {
+  const now = new Date().toISOString()
+  let written = 0
+  const skipped: string[] = []
+
+  const apply = db.transaction(() => {
+    for (const summary of parsed.summaries) {
+      const session = db
+        .query<{ project_id: string | null }, [string]>('SELECT project_id FROM sessions WHERE id = ?')
+        .get(summary.sessionId)
+      if (!session) {
+        skipped.push(summary.sessionId)
+        continue
+      }
+
+      db.query(`
+        INSERT INTO session_summaries (id, session_id, project_id, title, value, summary_markdown, metadata_json, created_at, updated_at)
+        VALUES ($id, $sessionId, $projectId, $title, $value, $summaryMarkdown, $metadata, $now, $now)
+        ON CONFLICT(id) DO UPDATE SET
+          title = excluded.title,
+          value = excluded.value,
+          summary_markdown = excluded.summary_markdown,
+          metadata_json = excluded.metadata_json,
+          updated_at = excluded.updated_at
+      `).run({
+        $id: `sum_${hash(summary.sessionId)}`,
+        $sessionId: summary.sessionId,
+        $projectId: session.project_id ?? parsed.projectId,
+        $title: summary.title,
+        $value: summary.value,
+        $summaryMarkdown: summary.summaryMarkdown,
+        $metadata: JSON.stringify(summary.metadata),
+        $now: now,
+      })
+      written += 1
+    }
+  })
+  apply()
+
+  return { written, skipped }
+}

package/src/sync.ts

@@ -0,0 +1,207 @@
+import type { LlmIwikiDatabase } from './db'
+import { resolveProjectByPath } from './projects'
+import { COLLECTORS, type Collector, type RawSession } from './collectors'
+
+export interface SourceSyncReport {
+  source: string
+  new: number
+  changed: number
+  unchanged: number
+  sourceMissing: number
+  total: number
+}
+
+export interface SyncReport {
+  bySource: SourceSyncReport[]
+}
+
+export interface SyncOptions {
+  homeDir: string
+  projectFilter?: string | null
+}
+
+function hash(value: string): string {
+  return Bun.hash(value).toString(16)
+}
+
+function sessionPrimaryId(sourceId: string, session: RawSession): string {
+  return `ses_${hash(`${sourceId}\u0000${session.sourceSessionId}\u0000${session.rawPath}`)}`
+}
+
+function messageContentHash(role: string, content: string): string {
+  return hash(`${role}\u0000${content}`)
+}
+
+function sessionContentHash(messageHashes: string[]): string {
+  return hash(`${messageHashes.length}\u0000${messageHashes.join('\u0000')}`)
+}
+
+function upsertSource(db: LlmIwikiDatabase, collector: Collector, now: string): void {
+  db.query(`
+    INSERT INTO sources (id, name, enabled, scan_paths, config_json, last_sync_at)
+    VALUES ($id, $name, 1, NULL, NULL, $now)
+    ON CONFLICT(id) DO UPDATE SET
+      name = excluded.name,
+      last_sync_at = excluded.last_sync_at
+  `).run({ $id: collector.id, $name: collector.name, $now: now })
+}
+
+function resolveProjectId(db: LlmIwikiDatabase, rawProjectPath: string | null): string | null {
+  if (!rawProjectPath) return null
+  try {
+    return resolveProjectByPath(db, rawProjectPath).id
+  } catch {
+    return null
+  }
+}
+
+function writeSession(
+  db: LlmIwikiDatabase,
+  collector: Collector,
+  session: RawSession,
+  now: string,
+  report: SourceSyncReport,
+): string {
+  const id = sessionPrimaryId(collector.id, session)
+  const messageHashes = session.messages.map((message) => messageContentHash(message.role, message.content))
+  const contentHash = sessionContentHash(messageHashes)
+  const projectId = resolveProjectId(db, session.rawProjectPath)
+
+  const existing = db
+    .query<{ content_hash: string; first_seen_at: string }, [string]>(
+      'SELECT content_hash, first_seen_at FROM sessions WHERE id = ?',
+    )
+    .get(id)
+
+  if (existing && existing.content_hash === contentHash) {
+    db.query('UPDATE sessions SET project_id = $projectId, status = $status, last_seen_at = $now WHERE id = $id').run({
+      $projectId: projectId,
+      $status: 'unchanged',
+      $now: now,
+      $id: id,
+    })
+    report.unchanged += 1
+    return id
+  }
+
+  const status = existing ? 'changed' : 'new'
+  const firstSeenAt = existing?.first_seen_at ?? now
+
+  db.query(`
+    INSERT INTO sessions (
+      id, source_id, source_session_id, project_id, checkout_id, raw_project_path, raw_path,
+      title, message_count, content_hash, status, created_at, updated_at, first_seen_at, last_seen_at
+    ) VALUES (
+      $id, $sourceId, $sourceSessionId, $projectId, NULL, $rawProjectPath, $rawPath,
+      $title, $messageCount, $contentHash, $status, $createdAt, $updatedAt, $firstSeenAt, $now
+    )
+    ON CONFLICT(id) DO UPDATE SET
+      project_id = excluded.project_id,
+      raw_project_path = excluded.raw_project_path,
+      title = excluded.title,
+      message_count = excluded.message_count,
+      content_hash = excluded.content_hash,
+      status = excluded.status,
+      created_at = excluded.created_at,
+      updated_at = excluded.updated_at,
+      last_seen_at = excluded.last_seen_at
+  `).run({
+    $id: id,
+    $sourceId: collector.id,
+    $sourceSessionId: session.sourceSessionId,
+    $projectId: projectId,
+    $rawProjectPath: session.rawProjectPath,
+    $rawPath: session.rawPath,
+    $title: session.title,
+    $messageCount: session.messages.length,
+    $contentHash: contentHash,
+    $status: status,
+    $createdAt: session.createdAt,
+    $updatedAt: session.updatedAt,
+    $firstSeenAt: firstSeenAt,
+    $now: now,
+  })
+
+  db.query('DELETE FROM messages WHERE session_id = ?').run(id)
+  session.messages.forEach((message, index) => {
+    db.query(`
+      INSERT INTO messages (id, session_id, role, content, timestamp, seq_order, content_hash)
+      VALUES ($id, $sessionId, $role, $content, $timestamp, $seqOrder, $contentHash)
+    `).run({
+      $id: `msg_${id}_${index}`,
+      $sessionId: id,
+      $role: message.role,
+      $content: message.content,
+      $timestamp: message.timestamp,
+      $seqOrder: index,
+      $contentHash: messageHashes[index]!,
+    })
+  })
+
+  if (status === 'new') report.new += 1
+  else report.changed += 1
+  return id
+}
+
+function markMissingSessions(
+  db: LlmIwikiDatabase,
+  sourceId: string,
+  seenIds: Set<string>,
+  now: string,
+  report: SourceSyncReport,
+): void {
+  const rows = db
+    .query<{ id: string }, [string]>(
+      "SELECT id FROM sessions WHERE source_id = ? AND status != 'source_missing'",
+    )
+    .all(sourceId)
+
+  for (const row of rows) {
+    if (seenIds.has(row.id)) continue
+    db.query('UPDATE sessions SET status = $status, last_seen_at = $now WHERE id = $id').run({
+      $status: 'source_missing',
+      $now: now,
+      $id: row.id,
+    })
+    report.sourceMissing += 1
+  }
+}
+
+export function runSync(db: LlmIwikiDatabase, options: SyncOptions): SyncReport {
+  const now = new Date().toISOString()
+  const bySource: SourceSyncReport[] = []
+
+  for (const collector of COLLECTORS) {
+    if (!collector.detect(options.homeDir)) continue
+
+    upsertSource(db, collector, now)
+    const report: SourceSyncReport = {
+      source: collector.id,
+      new: 0,
+      changed: 0,
+      unchanged: 0,
+      sourceMissing: 0,
+      total: 0,
+    }
+
+    const sessions = collector.collect(options.homeDir)
+    const seenIds = new Set<string>()
+
+    const writeAll = db.transaction(() => {
+      for (const session of sessions) {
+        if (options.projectFilter && session.rawProjectPath !== options.projectFilter) continue
+        const id = writeSession(db, collector, session, now, report)
+        seenIds.add(id)
+        report.total += 1
+      }
+      if (!options.projectFilter) {
+        markMissingSessions(db, collector.id, seenIds, now, report)
+      }
+    })
+    writeAll()
+
+    bySource.push(report)
+  }
+
+  return { bySource }
+}

package/src/types.ts

@@ -0,0 +1,26 @@
+export type SummaryValue = 'none' | 'low' | 'medium' | 'high'
+export type Confidence = 'low' | 'medium' | 'high'
+
+export interface ParsedSummariesYaml {
+  projectId: string
+  summaries: Array<{
+    sessionId: string
+    title: string
+    value: SummaryValue
+    summaryMarkdown: string
+    metadata: Record<string, unknown>
+  }>
+}
+
+export interface ParsedExperiencesYaml {
+  projectId: string
+  experiences: Array<{
+    title: string
+    slug: string | null
+    summary: string
+    bodyMarkdown: string
+    sourceSessions: string[]
+    confidence: Confidence | null
+    metadata: Record<string, unknown>
+  }>
+}