@miphamai/cli 0.48.0 → 0.50.0

package/src/core/crsi-producer.ts

@@ -12,6 +12,10 @@
 
 import type { CrsiInsight } from './auto-memory'
 import type { MetaRule } from './meta-rule-engine'
+import type { Llm } from '../providers/llm'
+import { readdirSync, appendFileSync, readFileSync, existsSync, mkdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
 
 /** 教训文件（相对仓库根）。预建，沙箱只能改已存在文件。 */
 export const LESSONS_FILE = 'apps/cli/crsi-lessons.md'
@@ -86,6 +90,9 @@ export function produceCrsiProposal(
   const signal = selectCrsiSignal(insights, metaRules)
   if (!signal) return null
 
+  // 幂等：同一信号的教训标题已在文件中，不再重复产出。
+  if (currentLessons.includes(`## ${signal.category}: ${signal.title}`)) return null
+
   const lesson = buildLessonContent(signal, timestamp)
   const newContent = currentLessons ? `${currentLessons.trimEnd()}\n\n${lesson}\n` : `${lesson}\n`
 
@@ -186,3 +193,210 @@ export function produceRuleProposal(
     originalContent: currentManagedRules,
   }
 }
+
+// ── Producer 散文提议（块 1）：从失败信号生成「改 skill 散文」提议 ──
+// A1 边界首次实演：LLM 只作「生成」（候选），判定仍走确定性（guard 预筛 / 行为效果 / 人审）。
+
+const PROSE_SELECT_PROMPT_VERSION = '1.0.0'
+
+function buildSelectSkillPrompt(signal: CrsiSignal, skillFiles: string[]): string {
+  return [
+    `你是 CRSI producer（producer-prose-select v${PROSE_SELECT_PROMPT_VERSION}）。给定失败信号，从候选 skill 文件列表中选出最相关的一个，返回其文件路径（只返回路径，一行，不要其他文字）。`,
+    '',
+    '失败信号：',
+    `- category: ${signal.category}`,
+    `- title: ${signal.title}`,
+    signal.severity ? `- severity: ${signal.severity}` : '',
+    `- suggestion: ${signal.suggestion}`,
+    `- evidence: ${signal.evidence.join(' | ')}`,
+    '',
+    '候选 skill 文件：',
+    ...skillFiles.map((f) => `- ${f}`),
+  ]
+    .filter(Boolean)
+    .join('\n')
+}
+
+async function collectLlmText(llm: Llm, prompt: string): Promise<string> {
+  let text = ''
+  const req = {
+    model: 'prose',
+    messages: [{ role: 'user' as const, content: prompt }],
+    systemPrompt: '',
+  }
+  for await (const chunk of llm.chat(req)) {
+    if (chunk.type === 'text' && chunk.content) text += chunk.content
+  }
+  return text.trim()
+}
+
+function extractFilePath(response: string, skillFiles: string[]): string | null {
+  for (const f of skillFiles) {
+    if (response.includes(f)) return f
+  }
+  return null
+}
+
+export async function selectTargetSkill(
+  signal: CrsiSignal,
+  llm: Llm,
+  skillFiles: string[],
+): Promise<string | null> {
+  if (skillFiles.length === 0) return null
+  const prompt = buildSelectSkillPrompt(signal, skillFiles)
+  const response = await collectLlmText(llm, prompt)
+  if (!response) return null
+  return extractFilePath(response, skillFiles)
+}
+
+const PROSE_GENERATE_PROMPT_VERSION = '1.0.0'
+
+function buildGenerateProsePrompt(
+  signal: CrsiSignal,
+  filePath: string,
+  originalContent: string,
+): string {
+  return [
+    `你是 CRSI producer（producer-prose-generate v${PROSE_GENERATE_PROMPT_VERSION}）。基于失败信号，改进目标 skill 的内容。`,
+    '',
+    '失败信号：',
+    `- category: ${signal.category}`,
+    `- title: ${signal.title}`,
+    `- suggestion: ${signal.suggestion}`,
+    `- evidence: ${signal.evidence.join(' | ')}`,
+    '',
+    `目标文件：${filePath}`,
+    '',
+    '当前内容：',
+    originalContent,
+    '',
+    '请返回改进后的完整 markdown（保持 YAML frontmatter 的 name/description 字段，正文针对失败信号做针对性改进）。只返回 markdown，不要额外说明。',
+  ].join('\n')
+}
+
+function stripMarkdownFence(text: string): string {
+  const match = text.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/)
+  return match ? match[1]! : text
+}
+
+export async function generateProseContent(
+  signal: CrsiSignal,
+  llm: Llm,
+  filePath: string,
+  originalContent: string,
+): Promise<string | null> {
+  const prompt = buildGenerateProsePrompt(signal, filePath, originalContent)
+  const response = await collectLlmText(llm, prompt)
+  if (!response) return null
+  return stripMarkdownFence(response)
+}
+
+export interface ProseProposalResult {
+  filePath: string
+  newContent: string
+  originalContent: string
+  description: string
+}
+
+export async function produceProseProposal(
+  signal: CrsiSignal,
+  llm: Llm,
+  skillFiles: string[],
+  readSkill: (filePath: string) => string,
+): Promise<ProseProposalResult | null> {
+  const filePath = await selectTargetSkill(signal, llm, skillFiles)
+  if (!filePath) return null
+
+  let originalContent: string
+  try {
+    originalContent = readSkill(filePath)
+  } catch {
+    return null
+  }
+
+  const newContent = await generateProseContent(signal, llm, filePath, originalContent)
+  if (!newContent) return null
+
+  return { filePath, newContent, originalContent, description: signal.title }
+}
+
+const SKILL_DIRS: Array<[string, string]> = [
+  ['standard', '.SKILL.md'],
+  ['mipham', '.mipham-skill.md'],
+]
+
+/** 收集仓库内所有 skill 文件（相对仓库根的路径），供 produceProseProposal 选目标。 */
+export function collectSkillFiles(root: string): string[] {
+  const files: string[] = []
+  for (const [dir, ext] of SKILL_DIRS) {
+    let entries: string[] = []
+    try {
+      entries = readdirSync(join(root, 'apps', 'cli', 'skills', dir))
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (entry.endsWith(ext)) files.push(`apps/cli/skills/${dir}/${entry}`)
+    }
+  }
+  return files
+}
+
+// ── 幂等去重（prose ledger） ──
+// 散文提议（块 1）的幂等：同一失败信号只生成一次提议。与 --rule 路径「目标文件内 id marker」去重不同，
+// 散文改的是 skill 内容（非追加 marker），故用 ~/.mipham 下的 append-only ledger 记录「已提议的信号」。
+
+/** 散文提议的稳定 id（同 category + 同 title → 同 id，同 managedRuleId 的 hash 语义）。 */
+export function proseProposalId(signal: CrsiSignal): string {
+  return `prose-${signal.category}-${stableHash(signal.title)}`
+}
+
+/** ledger 里的一条散文提议记录。 */
+export interface ProseProposalRecord {
+  id: string
+  filePath: string
+  timestamp: string
+}
+
+function proseLedgerFile(): string {
+  return join(homedir(), '.mipham', 'crsi', 'prose-proposals.jsonl')
+}
+
+/** 该信号是否已生成过散文提议。 */
+export function hasProposedProse(id: string): boolean {
+  try {
+    if (!existsSync(proseLedgerFile())) return false
+    const lines = readFileSync(proseLedgerFile(), 'utf-8').trim().split('\n').filter(Boolean)
+    return lines.some((line) => {
+      try {
+        return (JSON.parse(line) as { id?: string }).id === id
+      } catch {
+        return false
+      }
+    })
+  } catch {
+    return false
+  }
+}
+
+/** 追加一条散文提议记录（append-only，非关键——失败不影响提议本身）。 */
+export function appendProseProposal(record: ProseProposalRecord): void {
+  try {
+    mkdirSync(join(homedir(), '.mipham', 'crsi'), { recursive: true })
+    appendFileSync(proseLedgerFile(), JSON.stringify(record) + '\n', 'utf-8')
+  } catch {
+    // ledger 非关键，失败不影响提议本身
+  }
+}
+
+/** 清空散文提议 ledger，返回清除的记录数（无文件时返回 0）。 */
+export function clearProseProposals(): number {
+  try {
+    if (!existsSync(proseLedgerFile())) return 0
+    const lines = readFileSync(proseLedgerFile(), 'utf-8').trim().split('\n').filter(Boolean)
+    rmSync(proseLedgerFile(), { force: true })
+    return lines.length
+  } catch {
+    return 0
+  }
+}

package/src/core/crsi-sandbox.ts

@@ -107,10 +107,15 @@ const PROTECTED_PATHS = [
   'apps/cli/src/vajra/constitution.ts',
   // eval harness
   'apps/cli/test/',
+  'apps/cli/src/core/eval-harness.ts',
+  'apps/cli/src/core/behavior-tasks.ts',
+  'apps/cli/src/core/behavior-tasks.json',
   // 改进机制自身
   'apps/cli/src/agent/effectiveness-tracker.ts',
   'apps/cli/src/core/meta-rule-engine.ts',
   'apps/cli/src/core/crsi-sandbox.ts',
+  'apps/cli/src/core/crsi-producer.ts',
+  'apps/cli/src/core/proposal-guard.ts',
 ]
 
 /** 是否命中只读边界。前缀匹配，目录条目以 `/` 结尾。 */

package/src/core/eval-harness.ts

@@ -22,6 +22,7 @@ import { RedTeam } from './red-team'
 import { isProtectedPath } from './crsi-sandbox'
 import { produceRuleProposal, MANAGED_RULES_FILE } from './crsi-producer'
 import type { CrsiSignal } from './crsi-producer'
+import { loadBehaviorTasks, judgeBehaviorTask } from './behavior-tasks'
 
 // ── Types ──
 
@@ -223,6 +224,12 @@ export function runEval(): EvalReport {
     })
   }
 
+  // ── 行为任务集（ground truth：约束行为效果，确定性无 LLM） ──
+  const behaviorTasks = loadBehaviorTasks()
+  for (const task of behaviorTasks) {
+    results.push(judgeBehaviorTask(task, ruleEngine))
+  }
+
   const passed = results.filter((r) => r.passed).length
   return {
     total: results.length,

package/src/core/instructions.ts

@@ -2,6 +2,7 @@ import { readFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { parse as parseYaml } from 'yaml'
 import type { InstructionFile } from '../shared/index.ts'
+import { COAUTHOR_TRAILER } from '../shared/index.ts'
 
 interface FrontmatterResult {
   data: Record<string, unknown>
@@ -163,6 +164,16 @@ its live CRSI / SIS / constitution state. Report the numbers you read
 from it as live counts; if it shows a subsystem as 未初始化 (uninitialized),
 say so explicitly instead of claiming it exists.`)
 
+    // AI 署名披露：提交时附带 Co-Authored-By 署名（与 Undercover 式隐瞒相反）
+    parts.push(`## Commit Attribution
+
+When you create a git commit, always append this trailer on its own line
+at the end of the commit message, disclosing AI involvement:
+
+${COAUTHOR_TRAILER}
+
+Never omit it or present the work as purely human-authored.`)
+
     return parts.join('\n\n---\n\n')
   }
 

package/src/core/proposal-guard.ts

@@ -0,0 +1,100 @@
+// apps/cli/src/core/proposal-guard.ts
+// CRSI 提案预筛器（块 2 最小版）：结构确定性预筛，零 LLM。
+//
+// 这是 CRSI 自改进「producer 改散文」闭环的第一道闸（三层验证的第①层）：
+//   ① 结构确定性（本文件）：受保护路径 + 自引用封闭 + 目标范围 + 结构不变量
+//   ② 行为效果（M3/A：LLM 生成行为 → 测试判定）—— 留作 seam，未实现
+//   ③ 人类审批 —— CrsiSandbox 之后
+//
+// 诚实边界：本预筛只能证「结构合法」，不能证「散文更好」——
+// 后者是第②层（行为效果）的职责，需要 LLM 生成行为，属另一 A1 边界决策。
+
+import { parse as parseYaml } from 'yaml'
+import { isProtectedPath } from './crsi-sandbox'
+import { MANAGED_RULES_FILE, MANAGED_RULE_MARKER } from './crsi-producer'
+
+/** producer 产出的一条「改散文」提议（最小字段集，guard 阶段只消费这些）。 */
+export interface ProducerProposal {
+  id: string
+  /** 仓库根相对路径 */
+  filePath: string
+  /** 最小版只放行两类目标，收窄散文风险面 */
+  kind: 'skill' | 'managed-rule'
+  /** 改后的完整文件内容 */
+  newContent: string
+}
+
+export interface PrefilterVerdict {
+  pass: boolean
+  /** 拒绝理由；pass=true 时为空 */
+  reasons: string[]
+}
+
+const SKILL_DIR = 'apps/cli/skills/'
+
+function isSkillPath(filePath: string): boolean {
+  return (
+    filePath.startsWith(SKILL_DIR) &&
+    (filePath.endsWith('.SKILL.md') || filePath.endsWith('.mipham-skill.md'))
+  )
+}
+
+/**
+ * 更严、独立于 skills loader 的最小 frontmatter 解析。
+ *
+ * 与 loader 的宽松回退不同：frontmatter 缺失 / YAML 非法 / name 或 description
+ * 为空，都判失败（返回 null）——proposal 必须显式携带合法头部，不得依赖
+ * loader 的「文件名兜底 name」「空 description」等宽进逻辑。
+ */
+function parseStrictSkillFrontmatter(raw: string): { name: string; description: string } | null {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/)
+  if (!match) return null
+
+  let data: unknown
+  try {
+    data = parseYaml(match[1] || '')
+  } catch {
+    return null
+  }
+
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) return null
+  const obj = data as Record<string, unknown>
+
+  const name = typeof obj.name === 'string' ? obj.name.trim() : ''
+  const description = typeof obj.description === 'string' ? obj.description.trim() : ''
+  if (!name || !description) return null
+  return { name, description }
+}
+
+export function prefilterProposal(p: ProducerProposal): PrefilterVerdict {
+  const reasons: string[] = []
+
+  // ① 受保护路径 + 自引用封闭（isProtectedPath 已含评估机制自身的 5 个补洞）
+  if (isProtectedPath(p.filePath)) {
+    reasons.push(`protected path: ${p.filePath} is read-only to the self-improvement loop`)
+  }
+
+  // ② 目标范围白名单
+  const inScope =
+    (p.kind === 'skill' && isSkillPath(p.filePath)) ||
+    (p.kind === 'managed-rule' && p.filePath === MANAGED_RULES_FILE)
+  if (!inScope) {
+    reasons.push(`out of scope: ${p.filePath} is not an allowed ${p.kind} target`)
+  }
+
+  // ③ 结构不变量
+  if (p.kind === 'skill') {
+    if (!parseStrictSkillFrontmatter(p.newContent)) {
+      reasons.push(
+        'skill frontmatter invalid: missing/illegal frontmatter or empty name/description',
+      )
+    }
+  } else if (!p.newContent.includes(MANAGED_RULE_MARKER)) {
+    reasons.push('managed rule missing the producer append marker')
+  }
+
+  // ②（行为效果 seam）：此处接入 M3/A 任务表现度量——用 LLM 生成行为 + 确定性
+  // 测试判定，过滤「行为效果退化」的提议。未实现，属 producer LLM 生成能力（块 1）。
+
+  return { pass: reasons.length === 0, reasons }
+}

package/src/core/task-runner-tasks.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "tasks": [
+    {
+      "id": "task-answer-fn",
+      "instruction": "用 Write 工具在 <taskDir>/solution.ts 写入一个 TypeScript 文件，导出 `export function answer(): number { return 42 }`。",
+      "groundTruth": {
+        "kind": "file-contains",
+        "file": "solution.ts",
+        "contains": ["export function answer", "42"]
+      }
+    }
+  ]
+}

package/src/core/task-runner.ts

@@ -0,0 +1,163 @@
+// apps/cli/src/core/task-runner.ts
+// CRSI 端到端任务运行器（C-MVP）——行为效果度量基建。
+import { existsSync, readFileSync, mkdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import tasksFile from './task-runner-tasks.json' with { type: 'json' }
+import { QueryEngine } from './engine'
+import { ContextManager } from './context'
+import { PermissionSystem } from './permission'
+import { ProviderRegistry } from '../providers/registry'
+import type { Llm } from '../providers/llm'
+import { createToolRegistry } from '../tools'
+import type { PermissionLevel } from '../shared'
+
+export type RunnerGroundTruth = { kind: 'file-contains'; file: string; contains: string[] }
+
+export interface RunnerTask {
+  id: string
+  instruction: string
+  groundTruth: RunnerGroundTruth
+}
+
+export function loadRunnerTasks(): RunnerTask[] {
+  return tasksFile.tasks as unknown as RunnerTask[]
+}
+
+export function judgeTask(task: RunnerTask, taskDir: string): { passed: boolean; detail?: string } {
+  if (task.groundTruth.kind !== 'file-contains') {
+    return { passed: false, detail: `unsupported groundTruth kind: ${task.groundTruth.kind}` }
+  }
+  const filePath = join(taskDir, task.groundTruth.file)
+  if (!existsSync(filePath)) {
+    return { passed: false, detail: `file not found: ${task.groundTruth.file}` }
+  }
+  const content = readFileSync(filePath, 'utf-8')
+  for (const needle of task.groundTruth.contains) {
+    if (!content.includes(needle)) {
+      return { passed: false, detail: `missing substring: ${needle}` }
+    }
+  }
+  return { passed: true }
+}
+
+export interface TaskRunResult {
+  taskId: string
+  passed: boolean
+  detail?: string
+}
+
+const TASK_DIR_PLACEHOLDER = '<taskDir>'
+
+function buildEngine(llm: Llm, permission: PermissionLevel, systemPrompt?: string): QueryEngine {
+  const registry = new ProviderRegistry([], 'test', 'test-model')
+  // 注册一个永不 chat 的占位 provider——llm 被 setLlm 覆盖，但 process() 内部
+  // 多处调用 registry.getActive().config.id 记录 provider id，必须能取到。
+  registry.register('test', {
+    config: { id: 'test', name: 'Test', protocol: 'openai-compatible', apiKey: 'key', models: [] },
+    chat: async function* () {
+      yield { type: 'stop' }
+    },
+    listModels: async () => [],
+    healthCheck: async () => true,
+  })
+  const context = new ContextManager({ maxTokens: 100_000, compactionThreshold: 0.9 })
+  if (systemPrompt !== undefined) context.setSystemPrompt(systemPrompt)
+  const tools = createToolRegistry()
+  const engine = new QueryEngine(registry, context, tools, new PermissionSystem(permission))
+  engine.setLlm(llm)
+  return engine
+}
+
+export async function runTask(
+  task: RunnerTask,
+  llm: Llm,
+  opts: { taskDir?: string; permission?: PermissionLevel; systemPrompt?: string } = {},
+): Promise<TaskRunResult> {
+  const taskDir = opts.taskDir ?? join(process.cwd(), '.mipham', 'task-runner')
+  const permission = opts.permission ?? 'bypassPermissions'
+
+  rmSync(taskDir, { recursive: true, force: true })
+  mkdirSync(taskDir, { recursive: true })
+
+  const instruction = task.instruction.replaceAll(TASK_DIR_PLACEHOLDER, taskDir)
+  const engine = buildEngine(llm, permission, opts.systemPrompt)
+
+  for await (const _ of engine.process(instruction)) {
+    /* drain agentic loop */
+  }
+
+  const verdict = judgeTask(task, taskDir)
+  return { taskId: task.id, passed: verdict.passed, detail: verdict.detail }
+}
+
+export interface TaskRunStats {
+  taskId: string
+  samples: number
+  passed: number
+  /** 0-1 */
+  passRate: number
+}
+
+export async function runTaskN(
+  task: RunnerTask,
+  llm: Llm,
+  n: number,
+  opts: { taskDir?: string; permission?: PermissionLevel; systemPrompt?: string } = {},
+): Promise<TaskRunStats> {
+  let passed = 0
+  for (let i = 0; i < n; i++) {
+    const result = await runTask(task, llm, opts)
+    if (result.passed) passed++
+  }
+  return { taskId: task.id, samples: n, passed, passRate: n > 0 ? passed / n : 0 }
+}
+
+export interface RunComparison {
+  baseline: TaskRunStats
+  candidate: TaskRunStats
+  /** 弱判：candidate 不退化（不低于 baseline 且至少 1 次成功） */
+  notDegraded: boolean
+  /** candidate 严格更好（通过率更高） */
+  improved: boolean
+}
+
+export function isNotDegraded(baseline: TaskRunStats, candidate: TaskRunStats): boolean {
+  return candidate.passRate >= baseline.passRate && candidate.passed >= 1
+}
+
+export function isImproved(baseline: TaskRunStats, candidate: TaskRunStats): boolean {
+  return candidate.passRate > baseline.passRate
+}
+
+export function compareRuns(baseline: TaskRunStats, candidate: TaskRunStats): RunComparison {
+  return {
+    baseline,
+    candidate,
+    notDegraded: isNotDegraded(baseline, candidate),
+    improved: isImproved(baseline, candidate),
+  }
+}
+
+export async function runBeforeAfter(
+  task: RunnerTask,
+  llm: Llm,
+  n: number,
+  opts: {
+    beforePrompt?: string
+    afterPrompt?: string
+    taskDir?: string
+    permission?: PermissionLevel
+  } = {},
+): Promise<RunComparison> {
+  const baseline = await runTaskN(task, llm, n, {
+    taskDir: opts.taskDir,
+    permission: opts.permission,
+    systemPrompt: opts.beforePrompt,
+  })
+  const candidate = await runTaskN(task, llm, n, {
+    taskDir: opts.taskDir,
+    permission: opts.permission,
+    systemPrompt: opts.afterPrompt,
+  })
+  return compareRuns(baseline, candidate)
+}

package/src/daemon/heartbeat.ts

@@ -0,0 +1,83 @@
+// apps/cli/src/daemon/heartbeat.ts — 心跳式通知（保守版 KAIROS「订阅与推送」）
+//
+// 借鉴 Claude Code KAIROS 的「主动感知」思路，但严格约束为「只通知、不自主行动」：
+//   - 定时扫描 pending 的 goal（active）与 schedule（enabled）
+//   - 有 pending 时推送一条摘要（默认走 Feishu），无 pending 时静默
+//   - 绝不替用户执行任何动作——「主动感知可以，自主行动必须有闸门」（CRSI 受约束哲学）
+//
+// 纯函数（collectPendingItems / buildHeartbeatMessage / heartbeatTick）便于测试；
+// startHeartbeat 只做 setInterval + unref 的薄接线。
+
+import type { DaemonGoal, DaemonSchedule } from './types'
+
+/** 默认心跳间隔：30 分钟（提醒型通知，不宜过频）。 */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30 * 60_000
+
+export interface PendingItems {
+  goalCount: number
+  scheduleCount: number
+  summaries: string[]
+}
+
+/** 收集待办项：active 的 goal + enabled 的 schedule。纯函数。 */
+export function collectPendingItems(
+  goals: DaemonGoal[],
+  schedules: DaemonSchedule[],
+): PendingItems {
+  const activeGoals = goals.filter((g) => g.status === 'active')
+  const enabledSchedules = schedules.filter((s) => s.enabled)
+
+  const summaries: string[] = []
+  for (const g of activeGoals) summaries.push(`🎯 ${g.description}`)
+  for (const s of enabledSchedules) summaries.push(`⏰ [${s.cronExpr}] ${s.prompt}`)
+
+  return {
+    goalCount: activeGoals.length,
+    scheduleCount: enabledSchedules.length,
+    summaries,
+  }
+}
+
+const MAX_SUMMARY_ITEMS = 10
+
+/** 把待办渲染成通知文案；无可待办时返回 null（不打扰）。纯函数。 */
+export function buildHeartbeatMessage(pending: PendingItems): string | null {
+  if (pending.goalCount === 0 && pending.scheduleCount === 0) return null
+
+  const lines = [
+    `💓 Mipham 心跳提醒：${pending.goalCount} 个待办 goal，${pending.scheduleCount} 个定时任务`,
+    '',
+    ...pending.summaries.slice(0, MAX_SUMMARY_ITEMS),
+  ]
+  if (pending.summaries.length > MAX_SUMMARY_ITEMS) {
+    lines.push(`… 另外 ${pending.summaries.length - MAX_SUMMARY_ITEMS} 项`)
+  }
+  return lines.join('\n')
+}
+
+export interface HeartbeatSource {
+  listGoals(): DaemonGoal[]
+  listSchedules(): DaemonSchedule[]
+}
+
+/** 单次心跳：收集待办，有则推送。抽出来便于直接测试。 */
+export function heartbeatTick(source: HeartbeatSource, push: (message: string) => void): void {
+  const pending = collectPendingItems(source.listGoals(), source.listSchedules())
+  const message = buildHeartbeatMessage(pending)
+  if (message) push(message)
+}
+
+export interface HeartbeatDeps {
+  source: HeartbeatSource
+  push: (message: string) => void
+  intervalMs?: number
+}
+
+/** 启动心跳定时器（unref 不阻止进程退出），返回 stop 函数。 */
+export function startHeartbeat(deps: HeartbeatDeps): () => void {
+  const intervalMs = deps.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS
+  const id = setInterval(() => heartbeatTick(deps.source, deps.push), intervalMs)
+  // Bun 的 Timer 有 unref；假定时器/其它运行时不保证——用可选调用容错。
+  ;(id as { unref?: () => void }).unref?.()
+  return () => clearInterval(id)
+}