agentquad 0.3.0

package/src/wiki/guide.js

@@ -0,0 +1,44 @@
+// Rendered verbatim into ~/.agentquad/wiki/WIKI_GUIDE.md on first init.
+// Users are free to edit the file afterwards; we only write it if it's missing.
+export const WIKI_GUIDE_CONTENT = `# Wiki 维护指南（LLM 读这个）
+
+## 你的职责
+每次被调用时，\`sources/\` 下会有一批新的 todo 素材文件。你的任务是：读完新 sources，把其中可沉淀的知识融入 \`topics/\` / \`projects/\` / \`index.md\`，让 wiki 保持有条理、可检索。
+
+## 硬规则
+- \`sources/*.md\` 是输入，**永远不要修改它们**
+- 页面命名：kebab-case，例如 \`topics/cloudbase-cloud-function-deploy.md\`
+- 页面间用相对 markdown 链接互相引用（例如 \`[CloudBase 部署](../topics/cloudbase-cloud-function-deploy.md)\`）
+- 每个页面专注一个主题，不要让单页膨胀到难读
+
+## 决策流程
+对每个新 source，问自己：
+1. 这条 todo 揭示了什么**可复用**的知识？（踩过的坑、通用模式、项目结构摘要、外部工具配置）
+2. 对应 topic 页是否已经存在？
+   - 存在 → 在合适的段落追加；合并类似条目
+   - 不存在 → 新建 topic 页
+3. 这条 todo 有 workDir（项目路径）吗？
+   - 有 → 同时更新 \`projects/<projectName>.md\`：项目概述、该项目沉淀过的主要知识点列表（带链接指向 topic）
+4. 如果这条 todo 只是琐碎任务（比如"写邮件"、"买东西"），可以跳过，不强行产出内容
+
+## 更新 index.md
+\`index.md\` 是顶级目录。每次都确保：
+- 列出 topics/ 下所有页面（按主题分类）
+- 列出 projects/ 下所有页面
+- 最近 7 天的变更可以用一个 "Recent" 段落点出
+
+## 追加 log.md
+最后一步：往 log.md 追加一个 \`## YYYY-MM-DD HH:MM\` 段落，写清楚你这次改了/新增了哪些页，每条一句话。
+
+## 语言
+中文优先，代码/命令/路径保留原文。
+`
+
+export const EMPTY_INDEX_CONTENT = `# Wiki Index
+
+还没有沉淀任何主题。去 AgentQuad 里点「沉淀到记忆」按钮开始。
+`
+
+export const EMPTY_LOG_CONTENT = `# Wiki 更新日志
+
+`

package/src/wiki/index.js

@@ -0,0 +1,232 @@
+import { existsSync, mkdirSync, readdirSync, writeFileSync, appendFileSync } from 'node:fs'
+import { execFile, spawn } from 'node:child_process'
+import { promisify } from 'node:util'
+import { join } from 'node:path'
+import { WIKI_GUIDE_CONTENT, EMPTY_INDEX_CONTENT, EMPTY_LOG_CONTENT } from './guide.js'
+import { loadTranscript as defaultLoadTranscript } from '../transcript.js'
+import { summarizeTurns as defaultSummarize } from '../summarize.js'
+import { redact as defaultRedact } from './redact.js'
+import { buildSourceMarkdown, sourceFileName } from './sources.js'
+
+const execFileP = promisify(execFile)
+
+function isGitRepo(dir) { return existsSync(join(dir, '.git')) }
+function isNonEmptyDir(dir) {
+  if (!existsSync(dir)) return false
+  try { return readdirSync(dir).length > 0 } catch { return false }
+}
+
+async function gitInit(wikiDir) {
+  await execFileP('git', ['init', '-q'], { cwd: wikiDir })
+  await execFileP('git', ['add', '-A'], { cwd: wikiDir })
+  try {
+    await execFileP('git', ['commit', '-q', '-m', 'wiki: initial commit'], { cwd: wikiDir })
+  } catch {
+    await execFileP(
+      'git',
+      ['-c', 'user.email=agentquad@local', '-c', 'user.name=agentquad', 'commit', '-q', '-m', 'wiki: initial commit'],
+      { cwd: wikiDir },
+    )
+  }
+}
+
+async function gitCommit(wikiDir, message) {
+  await execFileP('git', ['add', '-A'], { cwd: wikiDir })
+  try {
+    const { stdout } = await execFileP('git', ['status', '--porcelain'], { cwd: wikiDir })
+    if (!stdout.trim()) return { committed: false }
+  } catch {}
+  try {
+    await execFileP('git', ['commit', '-q', '-m', message], { cwd: wikiDir })
+  } catch {
+    await execFileP(
+      'git',
+      ['-c', 'user.email=agentquad@local', '-c', 'user.name=agentquad', 'commit', '-q', '-m', message],
+      { cwd: wikiDir },
+    )
+  }
+  return { committed: true }
+}
+
+function defaultExecClaude({ command, bin, args = [], cwd, stdin, timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    const cmd = bin || command
+    const child = spawn(cmd, [...args, '-p', '--output-format', 'text'], {
+      cwd, stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+    const timer = setTimeout(() => {
+      try { child.kill('SIGTERM') } catch {}
+      reject(new Error(`claude timeout after ${timeoutMs}ms`))
+    }, timeoutMs)
+    child.stdout.on('data', d => { stdout += d.toString() })
+    child.stderr.on('data', d => { stderr += d.toString() })
+    child.on('error', e => { clearTimeout(timer); reject(e) })
+    child.on('close', code => { clearTimeout(timer); resolve({ exitCode: code, stdout, stderr }) })
+    if (stdin != null) {
+      child.stdin.write(stdin)
+      child.stdin.end()
+    }
+  })
+}
+
+function buildClaudePrompt(newSourceFiles) {
+  const list = newSourceFiles.map(f => `- sources/${f}`).join('\n')
+  return `请严格按照 WIKI_GUIDE.md 的规则维护本 wiki。先读 WIKI_GUIDE.md，再读下面这批新的 sources，然后更新 topics/ projects/ index.md 和 log.md：
+
+${list}
+
+约束重申：
+- 不要修改 sources/*.md
+- 只产出 markdown 文件修改，不要输出总结到终端`
+}
+
+export function createWikiService({
+  db,
+  logDir,
+  wikiDir,
+  getTools,
+  maxTailTurns = 20,
+  timeoutMs = 600_000,
+  redactEnabled = true,
+  loadTranscript = (session) => defaultLoadTranscript({
+    tool: session.tool,
+    nativeSessionId: session.nativeSessionId,
+    cwd: session.cwd || null,
+    sessionId: session.sessionId,
+    logDir,
+  }),
+  summarize = defaultSummarize,
+  execClaude = null,
+}) {
+  let running = false
+  let lastInitState = 'unknown'
+
+  async function init() {
+    if (existsSync(wikiDir) && isNonEmptyDir(wikiDir) && !isGitRepo(wikiDir)) {
+      lastInitState = 'exists-not-git'
+      return { state: 'exists-not-git', wikiDir }
+    }
+    if (!existsSync(wikiDir)) mkdirSync(wikiDir, { recursive: true })
+    mkdirSync(join(wikiDir, 'sources'), { recursive: true })
+    mkdirSync(join(wikiDir, 'topics'), { recursive: true })
+    mkdirSync(join(wikiDir, 'projects'), { recursive: true })
+
+    const guidePath = join(wikiDir, 'WIKI_GUIDE.md')
+    if (!existsSync(guidePath)) writeFileSync(guidePath, WIKI_GUIDE_CONTENT)
+    if (!existsSync(join(wikiDir, 'index.md'))) writeFileSync(join(wikiDir, 'index.md'), EMPTY_INDEX_CONTENT)
+    if (!existsSync(join(wikiDir, 'log.md'))) writeFileSync(join(wikiDir, 'log.md'), EMPTY_LOG_CONTENT)
+
+    if (!isGitRepo(wikiDir)) {
+      try { await gitInit(wikiDir) } catch (e) {
+        lastInitState = 'git-failed'
+        return { state: 'git-failed', wikiDir, error: e.message }
+      }
+    }
+    lastInitState = 'ready'
+    return { state: 'ready', wikiDir }
+  }
+
+  function status() {
+    const runs = db.listWikiRuns({ limit: 1 })
+    return {
+      wikiDir,
+      initState: lastInitState,
+      lastRun: runs[0] || null,
+      pendingTodoCount: db.listUnappliedDoneTodos().length,
+      running,
+    }
+  }
+
+  function pending() {
+    return db.listUnappliedDoneTodos().map(t => ({
+      id: t.id, title: t.title, workDir: t.workDir,
+      quadrant: t.quadrant, completedAt: t.updatedAt,
+    }))
+  }
+
+  async function runOnce({ todoIds, dryRun = false } = {}) {
+    if (!Array.isArray(todoIds) || todoIds.length === 0) {
+      throw new Error('todoIds must be a non-empty array')
+    }
+    if (running) throw new Error('wiki run already running')
+    running = true
+    const run = db.createWikiRun({ todoCount: todoIds.length, dryRun: dryRun ? 1 : 0 })
+
+    try {
+      const writtenFiles = []
+      for (const todoId of todoIds) {
+        const todo = db.getTodo(todoId)
+        if (!todo) throw new Error(`todo_not_found: ${todoId}`)
+        const comments = db.listComments(todoId)
+        const redactFn = redactEnabled ? defaultRedact : (s) => String(s ?? '')
+        const md = await buildSourceMarkdown({
+          todo, comments,
+          loadTranscript,
+          summarize,
+          redact: redactFn,
+          maxTailTurns,
+        })
+        const filename = sourceFileName(todo)
+        const abs = join(wikiDir, 'sources', filename)
+        writeFileSync(abs, md)
+        writtenFiles.push(filename)
+        db.upsertWikiCoverage(run.id, todoId, `sources/${filename}`, false)
+      }
+
+      if (dryRun) {
+        db.completeWikiRun(run.id, { exitCode: 0, note: `dry-run: ${writtenFiles.length} sources` })
+        appendFileSync(join(wikiDir, 'log.md'),
+          `\n- [${new Date().toISOString()}] dry-run, wrote ${writtenFiles.length} source(s)\n`)
+        return { dryRun: true, runId: run.id, sourcesWritten: writtenFiles.length, exitCode: 0 }
+      }
+
+      const tools = getTools()
+      const tool = tools.claude || {}
+      const runner = execClaude || defaultExecClaude
+      const prompt = buildClaudePrompt(writtenFiles)
+      const result = await runner({
+        command: tool.command || 'claude',
+        bin: tool.bin,
+        args: tool.args || [],
+        cwd: wikiDir,
+        stdin: prompt,
+        timeoutMs,
+      })
+      if (result.exitCode !== 0) {
+        throw new Error(`claude exited ${result.exitCode}: ${String(result.stderr || '').slice(0, 400)}`)
+      }
+
+      const now = new Date()
+      const tag = `${now.getFullYear()}-${String(now.getMonth()+1).padStart(2,'0')}-${String(now.getDate()).padStart(2,'0')}-${String(now.getHours()).padStart(2,'0')}`
+      await gitCommit(wikiDir, `wiki: batch ${tag} (${todoIds.length} todos)`)
+
+      db.markCoverageApplied(run.id)
+      db.completeWikiRun(run.id, { exitCode: 0, note: `batch: ${writtenFiles.length} sources` })
+      appendFileSync(join(wikiDir, 'log.md'),
+        `\n- [${now.toISOString()}] batch run #${run.id}: ${writtenFiles.length} source(s), exit 0\n`)
+
+      return { dryRun: false, runId: run.id, sourcesWritten: writtenFiles.length, exitCode: 0 }
+    } catch (e) {
+      db.failWikiRun(run.id, e.message)
+      throw e
+    } finally {
+      running = false
+    }
+  }
+
+  function markOrphansAsFailed() {
+    let n = 0
+    for (const orphan of db.findOrphanWikiRuns()) {
+      db.failWikiRun(orphan.id, 'AgentQuad process died mid-run')
+      n++
+    }
+    return n
+  }
+
+  return {
+    init, status, pending, runOnce, markOrphansAsFailed,
+    listRuns: (limit = 20) => db.listWikiRuns({ limit }),
+  }
+}

package/src/wiki/redact.js

@@ -0,0 +1,34 @@
+// API key / secret redaction for wiki source markdown.
+// Catches obvious leak patterns; not a security guarantee — user should never
+// paste real production secrets into todo descriptions, this is a seatbelt.
+
+const PATTERNS = [
+  // Anthropic / OpenAI sk- style keys
+  /\bsk-[A-Za-z0-9_\-]{20,}\b/g,
+  // AWS access key id
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  // GitHub tokens (personal, oauth, server-to-server, refresh)
+  /\bgh[pousr]_[A-Za-z0-9]{30,}\b/g,
+  // Google API key
+  /\bAIza[0-9A-Za-z_\-]{30,}\b/g,
+  // Slack tokens
+  /\bxox[baprs]-[A-Za-z0-9\-]{10,}\b/g,
+]
+
+// env-style SECRET_KEY=..., API_TOKEN=..., etc. Replace value but keep key.
+const ENV_LINE = /\b([A-Z][A-Z0-9_]{2,}(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|PWD))\s*=\s*\S+/g
+
+// inline key: "value", api_key: 'value', password = "value"
+const INLINE_KV = /\b(password|passwd|pwd|secret|api[_-]?key|access[_-]?token|auth[_-]?token|token)\b\s*[:=]\s*['"]?[^\s'",}]{6,}/gi
+
+export function redact(input) {
+  if (input == null) return ''
+  let s = typeof input === 'string' ? input : String(input)
+  for (const re of PATTERNS) s = s.replace(re, '[REDACTED]')
+  s = s.replace(ENV_LINE, (_, key) => `${key}=[REDACTED]`)
+  s = s.replace(INLINE_KV, (match, key) => {
+    const sep = match.includes(':') ? ':' : '='
+    return `${key}${sep} [REDACTED]`
+  })
+  return s
+}

package/src/wiki/sources.js

@@ -0,0 +1,122 @@
+function pad(n) { return String(n).padStart(2, '0') }
+
+function toDate(ts) {
+  const d = new Date(ts)
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+}
+
+function toDateTime(ts) {
+  const d = new Date(ts)
+  return `${toDate(ts)} ${pad(d.getHours())}:${pad(d.getMinutes())}`
+}
+
+function shortId(id) {
+  return String(id).slice(0, 8)
+}
+
+function hoursBetween(startMs, endMs) {
+  if (!startMs || !endMs) return null
+  return +((endMs - startMs) / 3_600_000).toFixed(2)
+}
+
+export function sourceFileName(todo, nowMs = Date.now()) {
+  return `${toDate(nowMs)}-${shortId(todo.id)}.md`
+}
+
+function renderTurn(turn) {
+  const roleMap = {
+    user: '用户',
+    assistant: 'AI',
+    thinking: '思考',
+    tool_use: `工具调用(${turn.toolName || ''})`,
+    tool_result: '工具输出',
+    raw: '原始',
+  }
+  const role = roleMap[turn.role] || turn.role
+  const content = String(turn.content || '')
+  return `【${role}】${content}`
+}
+
+export async function buildSourceMarkdown({
+  todo,
+  comments = [],
+  loadTranscript,
+  summarize,
+  redact,
+  maxTailTurns = 20,
+  maxBytes = 128 * 1024,
+  now = Date.now(),
+}) {
+  const lines = []
+
+  const duration = hoursBetween(todo.createdAt, todo.updatedAt)
+  lines.push('---')
+  lines.push(`todoId: ${todo.id}`)
+  lines.push(`title: ${todo.title.replace(/\n/g, ' ')}`)
+  lines.push(`quadrant: ${todo.quadrant}`)
+  lines.push(`workDir: ${todo.workDir || '-'}`)
+  lines.push(`createdAt: ${new Date(todo.createdAt).toISOString()}`)
+  lines.push(`completedAt: ${new Date(todo.updatedAt).toISOString()}`)
+  if (duration != null) lines.push(`durationHours: ${duration}`)
+  lines.push('---')
+  lines.push('')
+  lines.push(`# ${todo.title}`)
+  lines.push('')
+
+  if (todo.description && todo.description.trim()) {
+    lines.push('## 描述')
+    lines.push(redact(todo.description))
+    lines.push('')
+  }
+
+  if (comments.length) {
+    lines.push(`## 评论（${comments.length}）`)
+    for (const c of comments) {
+      lines.push(`- [${toDateTime(c.createdAt)}] ${redact(c.content)}`)
+    }
+    lines.push('')
+  }
+
+  const sessions = Array.isArray(todo.aiSessions) ? todo.aiSessions : []
+  if (sessions.length) {
+    lines.push('## AI 会话')
+    let idx = 0
+    for (const s of sessions) {
+      idx += 1
+      const parsed = (await loadTranscript(s)) || { source: 'empty', turns: [] }
+      const turns = Array.isArray(parsed.turns) ? parsed.turns : []
+      const completed = s.completedAt ? toDateTime(s.completedAt) : '-'
+      lines.push(`### Session ${idx} — ${s.tool}（${turns.length} 轮，完成时间 ${completed}）`)
+
+      let summary = ''
+      if (turns.length) {
+        try {
+          summary = await summarize(turns, { tool: s.tool })
+        } catch (e) {
+          summary = `（摘要失败：${e.message}）`
+        }
+      }
+      if (summary) {
+        lines.push(`**摘要**：${redact(summary)}`)
+        lines.push('')
+      }
+
+      const tail = turns.slice(-maxTailTurns)
+      if (tail.length) {
+        lines.push(`**最后 ${tail.length} 轮原文**：`)
+        lines.push('')
+        for (const t of tail) {
+          lines.push(redact(renderTurn(t)))
+          lines.push('')
+        }
+      }
+    }
+  }
+
+  let out = lines.join('\n')
+  if (Buffer.byteLength(out, 'utf8') > maxBytes) {
+    const head = out.slice(0, maxBytes - 200)
+    out = `${head}\n\n...（内容过长已截断，原始 transcript 保留在本地）...\n`
+  }
+  return out
+}