@x-otto/cli 0.0.1-alpha.5 → 0.0.1-alpha.50

package/dist/bundled-extensions/plugin-feedback/src/issue-aggregator.ts

@@ -0,0 +1,109 @@
+/**
+ * issue-aggregator.ts — RFC-430 §2.4/§2.5：github/coding 双源并行聚合。
+ *
+ * 语义（与 RFC-430 §2.4 `FeedbackIssueListResult` 契约一一对应）：
+ *   - 双源并行拉取（Promise.allSettled 风格——单源异常/拒绝不传播、不拖垮另一源）；
+ *   - 单源 8s 硬超时（超时该源按失败处理，reason 标明 timeout）；
+ *   - 任一源失败/无凭据/未配置 → 该源 items 为空且 `unavailable[source]` 携带
+ *     面向用户的原因文案（只含失败类别/HTTP 状态码，绝无 token）；
+ *   - 双源全败不抛——返回 `{ items: [], unavailable: { github, coding } }`。
+ *
+ * 排序：updatedAt（缺省 createdAt）降序，缺失时间戳的条目排最后但保持稳定序。
+ */
+import type { FeedbackIssueItem, FeedbackIssueListResult, FeedbackSource } from '@x-otto/plugin'
+
+/** 单源拉取硬超时（ms，RFC-430 §2.4）。 */
+export const PER_SOURCE_TIMEOUT_MS = 8000
+
+/** 与 github-lister/coding-lister 同构的单源拉取函数形状。 */
+export type SourceLister = (
+  opts: { state: 'open' | 'closed' | 'all'; limit: number },
+) => Promise<{ ok: true; items: FeedbackIssueItem[] } | { ok: false; reason: string }>
+
+export interface AggregateDeps {
+  github: SourceLister
+  coding: SourceLister
+  /** 单源超时注入点（测试用极小值模拟超时路径），缺省 8000。 */
+  timeoutMs?: number
+}
+
+/** 给单源拉取包一层硬超时——超时按失败处理（竞速 loser 的迟到结果被丢弃）。 */
+function withTimeout(
+  lister: SourceLister,
+  opts: { state: 'open' | 'closed' | 'all'; limit: number },
+  timeoutMs: number,
+): Promise<{ ok: true; items: FeedbackIssueItem[] } | { ok: false; reason: string }> {
+  return new Promise((resolvePromise) => {
+    let settled = false
+    const settle = (v: { ok: true; items: FeedbackIssueItem[] } | { ok: false; reason: string }): void => {
+      if (settled) return
+      settled = true
+      resolvePromise(v)
+    }
+    const timer = setTimeout(() => {
+      settle({ ok: false, reason: `timeout after ${timeoutMs}ms` })
+    }, timeoutMs)
+    // unref：聚合调用方提前返回时，挂起的计时不拖住进程退出。
+    timer.unref?.()
+    lister(opts).then(
+      (v) => { clearTimeout(timer); settle(v) },
+      (error) => {
+        clearTimeout(timer)
+        settle({ ok: false, reason: `unexpected error: ${error instanceof Error ? error.name : 'unknown'}` })
+      },
+    )
+  })
+}
+
+function sortByUpdatedDesc(items: FeedbackIssueItem[]): FeedbackIssueItem[] {
+  // 稳定排序（V8 Array.sort 稳定）：无时间戳的 key = 0 沉底，同值保持原相对序。
+  const key = (it: FeedbackIssueItem): number => {
+    const ts = Date.parse(it.updatedAt ?? it.createdAt ?? '')
+    return Number.isNaN(ts) ? 0 : ts
+  }
+  return [...items].sort((a, b) => key(b) - key(a))
+}
+
+/**
+ * 双源并行聚合主入口。任何单源失败都只反映在该源的 unavailable 文案上，
+ * 不影响另一源结果；本函数自身绝不抛出。
+ */
+export async function aggregateIssueLists(
+  opts: { state?: 'open' | 'closed' | 'all'; limitPerSource?: number } = {},
+  deps: AggregateDeps,
+): Promise<FeedbackIssueListResult> {
+  const state = opts.state ?? 'open'
+  const limit = opts.limitPerSource ?? 20
+  const timeoutMs = deps.timeoutMs ?? PER_SOURCE_TIMEOUT_MS
+
+  const sources: Array<{ source: FeedbackSource; lister: SourceLister }> = [
+    { source: 'github', lister: deps.github },
+    { source: 'coding', lister: deps.coding },
+  ]
+
+  const settled = await Promise.allSettled(
+    sources.map(({ lister }) => withTimeout(lister, { state, limit }, timeoutMs)),
+  )
+
+  const items: FeedbackIssueItem[] = []
+  const unavailable: Partial<Record<FeedbackSource, string>> = {}
+  settled.forEach((result, i) => {
+    const source = sources[i]!.source
+    if (result.status === 'fulfilled' && result.value.ok) {
+      items.push(...result.value.items)
+    } else if (result.status === 'fulfilled' && !result.value.ok) {
+      // `!ok` 显式写出才能让 TS 把联合收窄到 `{ ok: false; reason: string }`——
+      // 仅靠外层 else 不参与判别式收窄（result.value 是新的属性访问路径）。
+      unavailable[source] = result.value.reason
+    } else if (result.status === 'rejected') {
+      // Promise.allSettled 的 rejected 分支：lister 自身抛异常（防御——正常路径
+      // withTimeout 内部已把异常归一化为 ok:false，此处是双保险）。
+      unavailable[source] = `unexpected error: ${String(result.reason)}`
+    }
+  })
+
+  return {
+    items: sortByUpdatedDesc(items),
+    ...(Object.keys(unavailable).length > 0 ? { unavailable } : {}),
+  }
+}

package/dist/bundled-extensions/plugin-feedback/src/issue-submitter.ts

@@ -0,0 +1,241 @@
+/**
+ * issue-submitter.ts — RFC-207/RFC-209 §2.5：GitHub issue 双通道提交逻辑。
+ *
+ * `submitIssueViaGh`（仅供 TUI/CLI 本地进程调用，可能走 gh CLI）与 `buildIssueUrl`
+ * （纯函数、两端共用、不执行任何子进程/网络调用）是接口层面物理分离的两个方法——
+ * 防止 web-ui 浏览器请求误触发服务器侧 gh CLI 调用（RFC-209 §2.1/§2.5/重要事项规则7）。
+ *
+ * body 模板结构对齐 RFC-207 §3.1；URL 长度保护对齐 §3.3（浏览器通道 6000 字符阈值）；
+ * gh CLI 通道的临时文件生命周期对齐 §2.6a（0700 目录/0600 文件/UUID 文件名/close+exit
+ * 双重清理）；错误分类表对齐 §2.7（R3 修订的 5 种失败模式）；label 失败重试对齐 §2.7（R8）。
+ */
+import { existsSync, mkdirSync, writeFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { spawn } from 'node:child_process'
+
+import { isShadowModeEnabled, OTTO_HOME } from '@x-otto/env'
+import { buildAllowedEnv } from '@x-otto/shared'
+
+import type { FeedbackIssueInput, FeedbackIssueResult } from '@x-otto/plugin'
+import type { FeedbackLoggerPort } from './pulse-survey-sink'
+
+/** 宿主注入的日志端口（RFC-185 D3，同 pulse-survey-sink 的 FeedbackLoggerPort）；缺省 no-op。 */
+const noopLogger: FeedbackLoggerPort = { warn: () => {} }
+
+/** GitHub issue body 服务端上限约 65536 字符；留安全余量（RFC-207 §2.6b）。 */
+const MAX_BODY_CHARS = 60000
+/** GitHub issues/new 查询参数 URL 长度安全阈值（RFC-207 §3.3，留余量于常见 8KB 限制之下）。 */
+const MAX_URL_CHARS = 6000
+/** gh 探测/子进程等待超时（毫秒，RFC-207 §2.7 R6 修订）。 */
+const GH_AUTH_STATUS_TIMEOUT_MS = 5000
+
+/** 按 RFC-207 §3.1 模板拼装 issue body（两通道共用）。 */
+function buildIssueBody(input: FeedbackIssueInput): string {
+  const body = [
+    '## Reproduction Steps',
+    input.reproduce || '*(not provided)*',
+    '',
+    '## Expected Behavior',
+    input.expected || '*(not provided)*',
+    '',
+    '## Actual Behavior',
+    input.actual || '*(not provided)*',
+    '',
+    '## Environment',
+    input.envInfo,
+    '',
+    '---',
+    '*Generated by `otto feedback` — edit this issue directly to add more details.*',
+  ].join('\n')
+  return capBodySize(body)
+}
+
+/** RFC-207 §2.6b：body 超长截断保护，两通道统一走本函数。 */
+function capBodySize(body: string, limit = MAX_BODY_CHARS): string {
+  if (body.length <= limit) return body
+  const suffix = '\n\n*(Content truncated — please edit the issue to paste the full details after creation)*'
+  return body.slice(0, limit - suffix.length) + suffix
+}
+
+/**
+ * 两端共用——只构造预填 URL 字符串，不执行任何子进程/网络调用，纯函数式（RFC-209 §2.1）。
+ * URL 超限时截断 body 并追加提示（RFC-207 §3.3），完整 body 需调用方另行展示（如终端打印）。
+ */
+export function buildIssueUrl(input: FeedbackIssueInput): string {
+  const title = `[otto] ${input.title}`
+  let body = buildIssueBody(input)
+  let url = toGithubUrl(input.repo, title, body)
+
+  if (url.length > MAX_URL_CHARS) {
+    const suffix = '\n\n*(Content too long — full content available in clipboard/terminal output; please paste manually)*'
+    // 迭代收窄直到 URL 落在阈值内（body 截断量与 URL 编码膨胀率非线性，简单二分足够）。
+    let low = 0
+    let high = body.length
+    while (low < high) {
+      const mid = Math.floor((low + high) / 2)
+      const candidate = body.slice(0, mid) + suffix
+      const candidateUrl = toGithubUrl(input.repo, title, candidate)
+      if (candidateUrl.length <= MAX_URL_CHARS) {
+        low = mid + 1
+      } else {
+        high = mid
+      }
+    }
+    body = body.slice(0, Math.max(0, low - 1)) + suffix
+    url = toGithubUrl(input.repo, title, body)
+  }
+
+  return url
+}
+
+function toGithubUrl(repo: string, title: string, body: string): string {
+  const params = new URLSearchParams({ title, body, labels: 'from-cli' })
+  return `https://github.com/${repo}/issues/new?${params.toString()}`
+}
+
+/** RFC-207 §2.6a：临时文件目录（~/.otto/tmp/，非共享系统级 os.tmpdir()，最小暴露面）。 */
+function feedbackTmpDir(): string {
+  return join(OTTO_HOME, 'tmp')
+}
+
+/** 写入 0600 权限的临时 body 文件，返回路径 + 清理句柄（RFC-207 §2.6a）。 */
+function writeTempBodyFile(body: string): { path: string; cleanup: () => void } {
+  const dir = feedbackTmpDir()
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 })
+  }
+  const path = join(dir, `feedback-${randomUUID()}.md`)
+  writeFileSync(path, body, { mode: 0o600 })
+  let cleaned = false
+  const cleanup = () => {
+    if (cleaned) return
+    cleaned = true
+    try {
+      unlinkSync(path)
+    } catch {
+      // fail-soft：清理失败不影响主流程（孤儿文件留存，非安全关键——0600 权限已限制访问）。
+    }
+  }
+  return { path, cleanup }
+}
+
+/** 探测 gh 是否已登录（RFC-207 §2.7），5 秒超时视为不可用。 */
+function checkGhAuthStatus(): Promise<boolean> {
+  return new Promise((resolvePromise) => {
+    let settled = false
+    const child = spawn('gh', ['auth', 'status'], { env: buildAllowedEnv() })
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      child.kill('SIGTERM')
+      resolvePromise(false)
+    }, GH_AUTH_STATUS_TIMEOUT_MS)
+    child.on('error', () => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolvePromise(false)
+    })
+    child.on('exit', (code) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolvePromise(code === 0)
+    })
+  })
+}
+
+/** RFC-207 §2.7 R3 修订：gh issue create stderr 分类。 */
+function classifyGhError(stderr: string): { kind: string; detail: string } {
+  if (/HTTP 404|HTTP 403/.test(stderr)) {
+    return { kind: 'repo-not-found-or-forbidden', detail: stderr }
+  }
+  if (/Issues has been disabled/i.test(stderr)) {
+    return { kind: 'issues-disabled', detail: stderr }
+  }
+  if (/unknown flag/i.test(stderr)) {
+    return { kind: 'gh-version-too-old', detail: stderr }
+  }
+  if (/dial tcp|no such host/i.test(stderr)) {
+    return { kind: 'network-error', detail: stderr }
+  }
+  return { kind: 'unclassified', detail: stderr }
+}
+
+/** 是否为 label 相关失败（RFC-207 §2.7 R8：不存在的 label 重试一次不带 label）。 */
+function isLabelError(stderr: string): boolean {
+  return /label/i.test(stderr) && /not found/i.test(stderr)
+}
+
+function runGhIssueCreate(args: string[]): Promise<{ ok: true; stdout: string } | { ok: false; stderr: string }> {
+  return new Promise((resolvePromise) => {
+    const child = spawn('gh', ['issue', 'create', ...args], { env: buildAllowedEnv() })
+    let stdout = ''
+    let stderr = ''
+    child.stdout?.on('data', (chunk) => { stdout += String(chunk) })
+    child.stderr?.on('data', (chunk) => { stderr += String(chunk) })
+    child.on('error', (err) => {
+      resolvePromise({ ok: false, stderr: String(err) })
+    })
+    child.on('exit', (code) => {
+      if (code === 0) resolvePromise({ ok: true, stdout })
+      else resolvePromise({ ok: false, stderr })
+    })
+  })
+}
+
+/**
+ * 仅供 TUI/CLI 本地进程调用——内部走 gh CLI 通道（spawn 本机已认证的 gh）。
+ * 不做通道选择编排（先试 gh、失败降级浏览器）——那是宿主 CLI 核心层职责（RFC-209 §2.4/
+ * 重要事项规则7），本函数只负责"尝试用 gh 提交，报告成功或分类后的失败"。
+ */
+export async function submitIssueViaGh(
+  input: FeedbackIssueInput,
+  logger: FeedbackLoggerPort = noopLogger,
+): Promise<FeedbackIssueResult> {
+  // RFC-345：影子态零磁盘写入——gh 通道必须落临时 body 文件（§2.6a）才能跑，
+  // 无法不写盘完成，故整个 gh 通道在影子态下禁用；宿主收到本结果会走浏览器
+  // 通道（buildIssueUrl 纯函数、零磁盘写入，不受影响）。
+  if (isShadowModeEnabled()) {
+    return { ok: false, kind: 'shadow-mode-disabled', detail: 'gh issue 通道在影子模式下禁用（避免临时 body 文件落盘）' }
+  }
+
+  const authed = await checkGhAuthStatus()
+  if (!authed) {
+    return { ok: false, kind: 'gh-not-authenticated', detail: 'gh CLI not found or not authenticated' }
+  }
+
+  const title = `[otto] ${input.title}`
+  const body = buildIssueBody(input)
+  const { path: bodyPath, cleanup } = writeTempBodyFile(body)
+
+  try {
+    let result = await runGhIssueCreate([
+      '--repo', input.repo,
+      '--title', title,
+      '--body-file', bodyPath,
+      '--label', 'from-cli',
+    ])
+
+    if (!result.ok && isLabelError(result.stderr)) {
+      // RFC-207 §2.7 R8：label 不存在时去掉 --label 重试一次。
+      result = await runGhIssueCreate([
+        '--repo', input.repo,
+        '--title', title,
+        '--body-file', bodyPath,
+      ])
+    }
+
+    if (result.ok) {
+      const url = result.stdout.trim().split('\n').pop() ?? ''
+      return { ok: true, url }
+    }
+    const classified = classifyGhError(result.stderr)
+    logger.warn(`gh issue create failed: ${JSON.stringify(classified)}`)
+    return { ok: false, ...classified }
+  } finally {
+    cleanup()
+    process.on('exit', cleanup) // 兜底：异常退出（Ctrl+C）时仍尝试清理
+  }
+}

package/dist/bundled-extensions/plugin-feedback/src/platform-resolver.ts

@@ -0,0 +1,76 @@
+/**
+ * platform-resolver.ts — RFC-430 §2.1：反馈面板目标平台判定链。
+ *
+ * 判定顺序（显式配置优先于自动探测）：
+ *   1. settings `feedback_platform` 为 `'github'`/`'coding'` 显式值 → 直接生效，零探测；
+ *   2. `'auto'`（含未配置）→ `feedback_coding_base_url` 已配置且该地址经
+ *      `isIntranetReachable(false, [baseUrl])`（@x-otto/shared，TCP 握手语义）可达
+ *      → `'coding'`；
+ *   3. 其余一切情形（base_url 未配置/不可达/URL 非法）→ `'github'`。
+ *
+ * settings 读取经宿主注入端口（`FeedbackSettingsPort`，由 plugin.ts 的 ctx/host
+ * `getSettings` 装配注入），本模块不直读配置文件——保持插件的可测试性与宿主的
+ * 配置权威（单一真源在宿主 setting 层）。
+ */
+import { isIntranetReachable } from '@x-otto/shared'
+
+import type { FeedbackSource } from '@x-otto/plugin'
+import type { FeedbackLoggerPort } from './pulse-survey-sink'
+
+/** 宿主注入的 settings 读取端口（窄接口，只暴露本插件需要的三个键）。 */
+export interface FeedbackSettingsPort {
+  /** 等价 settings `feedback_repo`（`owner/repo`）。 */
+  getFeedbackRepo(): string | undefined
+  /** 等价 settings `feedback_platform`；未配置返回 undefined（语义 'auto'）。 */
+  getFeedbackPlatform(): 'auto' | 'github' | 'coding' | undefined
+  /** 等价 settings `feedback_coding_base_url`。 */
+  getFeedbackCodingBaseUrl(): string | undefined
+  /** 等价 settings `feedback_coding_repo`。 */
+  getFeedbackCodingRepo(): string | undefined
+}
+
+/** 缺省空端口（单测/宿主未注入场景）：全部 undefined —— 判定链恒落 'github'。 */
+export const EMPTY_SETTINGS_PORT: FeedbackSettingsPort = {
+  getFeedbackRepo: () => undefined,
+  getFeedbackPlatform: () => undefined,
+  getFeedbackCodingBaseUrl: () => undefined,
+  getFeedbackCodingRepo: () => undefined,
+}
+
+const noopLogger: FeedbackLoggerPort = { warn: () => {} }
+
+/**
+ * 平台判定链（见文件头）。baseUrl 以 `https?://` 开头才参与探测（非法配置静默落
+ * github + warn，不抛）；探测结果按 host:port 缓存（isIntranetReachable 内部 TTL）。
+ */
+export async function resolveFeedbackPlatform(
+  settings: FeedbackSettingsPort,
+  logger: FeedbackLoggerPort = noopLogger,
+): Promise<FeedbackSource> {
+  let explicit: 'auto' | 'github' | 'coding' | undefined
+  try {
+    explicit = settings.getFeedbackPlatform()
+  } catch (error) {
+    logger.warn(`feedback platform resolve: settings read failed (fail-soft → github): ${String(error)}`)
+    return 'github'
+  }
+  if (explicit === 'github' || explicit === 'coding') return explicit
+
+  // 'auto' / 未配置：仅当 base_url 已配置且内网可达时才选 coding。
+  let baseUrl: string | undefined
+  try {
+    baseUrl = settings.getFeedbackCodingBaseUrl()
+  } catch (error) {
+    logger.warn(`feedback platform resolve: coding base url read failed (fail-soft → github): ${String(error)}`)
+    return 'github'
+  }
+  if (!baseUrl || !/^https?:\/\//.test(baseUrl)) return 'github'
+
+  try {
+    return (await isIntranetReachable(false, [baseUrl])) ? 'coding' : 'github'
+  } catch (error) {
+    // 防御性兜底：isIntranetReachable 本身已 fail-soft，此处只为杜绝任何意外穿透。
+    logger.warn(`feedback platform resolve: intranet probe failed (fail-soft → github): ${String(error)}`)
+    return 'github'
+  }
+}

package/dist/bundled-extensions/plugin-feedback/src/pulse-survey-sink.ts

@@ -0,0 +1,114 @@
+/**
+ * pulse-survey-sink.ts — RFC-208 §2.2/§3.3：满意度脉冲调查本地日志落地层。
+ * RFC-209 §2.2/重要事项规则6：从 packages/coding/src/feedback/pulse-survey-sink.ts
+ * **原样迁移**（纯代码搬迁，非重写）——fail-soft/5MB截断/sink解析逻辑与迁移前完全一致。
+ *
+ * `PulseSurveySink` 是数据落地的可替换接口（RFC-208 grill 结果："可配置，暂时留接口"）——
+ * v1 只提供 `LocalJsonlPulseSurveySink` 一个实现，写入 `~/.otto/pulse-surveys.jsonl`，
+ * 不联网、不需要凭据。配置项 `pulse_survey.sink` 当前仅 `'local'` 合法（非法值 fallback，
+ * 见 `resolvePulseSurveySink`），不实现除本地 JSONL 外的任何 sink（RFC-208 重要事项规则 4）。
+ *
+ * 写入模式复用 `plugin-log-writer.ts` 的既有设计（同步 appendFileSync + 5MB 截断保留最后
+ * 50% + fail-soft 全局吞错）——本弹层触发频率远低于插件日志，性能非考量因素；两处独立各自
+ * 实现一份（而非抽取共享 helper），因为跨包共享收益不明显、且各自的 fail-soft 边界（本模块
+ * 不涉及 pluginId 路径穿越校验）不完全相同，重复优于错误的抽象。
+ */
+import { existsSync, mkdirSync, appendFileSync, statSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { OTTO_HOME, isShadowModeEnabled } from '@x-otto/env'
+
+import type { PulseSurveyEntry, PulseSurveyRating } from '@x-otto/plugin'
+
+export type { PulseSurveyEntry, PulseSurveyRating }
+
+/**
+ * 宿主注入的日志端口（RFC-185 D3：插件源码禁止自建 createLogger——esbuild 会把
+ * `@x-otto/shared` logger 整体 bundle 进 plugin.cjs 形成宿主管不着的第二份 pino 单例，
+ * trace 级直写 stderr 破坏 Ink TUI）。形状对齐 `PluginContext.logger` 的 warn 档；
+ * 缺省 no-op（如单测直接实例化、宿主未注入场景）。
+ */
+export interface FeedbackLoggerPort {
+  warn: (msg: string) => void
+}
+
+const noopLogger: FeedbackLoggerPort = { warn: () => {} }
+
+/** 单文件大小上限（5MB，同 plugin-log-writer.ts）；超限截断保留最后 50%。 */
+const MAX_LOG_FILE_BYTES = 5 * 1024 * 1024
+
+/** 数据落地可替换接口（RFC-208 grill "留接口"要求）。v1 仅 `LocalJsonlPulseSurveySink` 一种实现。 */
+export interface PulseSurveySink {
+  record(entry: PulseSurveyEntry): void
+}
+
+/** 日志文件路径（`resolve` 而非 `join`，对齐 plugin-log-writer.ts:47 pluginLogsDir() 的既有惯例）。 */
+export function pulseSurveyLogPath(): string {
+  return resolve(OTTO_HOME, 'pulse-surveys.jsonl')
+}
+
+/** 单文件超限时截断保留最后 50%（有损策略，同 plugin-log-writer.ts truncateIfOversized）。 */
+function truncateIfOversized(path: string, logger: FeedbackLoggerPort): void {
+  let size: number
+  try {
+    size = statSync(path).size
+  } catch {
+    return // 文件不存在，无需截断
+  }
+  if (size <= MAX_LOG_FILE_BYTES) return
+
+  try {
+    const content = readFileSync(path, 'utf8')
+    const keepFrom = Math.floor(content.length / 2)
+    // 从字符中点找下一个换行符，避免截断到半行 JSON。
+    const nl = content.indexOf('\n', keepFrom)
+    const truncated = nl >= 0 ? content.slice(nl + 1) : content.slice(keepFrom)
+    writeFileSync(path, truncated)
+  } catch (error) {
+    // fail-soft：截断失败不影响后续写入尝试（append 会继续追加到超限文件，下次再试截断）。
+    logger.warn(`pulse survey log truncation failed (fail-soft): path=${path} err=${String(error)}`)
+  }
+}
+
+/**
+ * 本地 JSONL 落地实现（RFC-208 v1 唯一 sink）。
+ * fail-soft（RFC-208 重要事项规则 3）：写入失败绝不能抛出到调用方或打断用户当前对话流，
+ * 全部异常在本类内部吞掉，仅 logger.warn 记录。
+ */
+export class LocalJsonlPulseSurveySink implements PulseSurveySink {
+  constructor(private readonly logger: FeedbackLoggerPort = noopLogger) {}
+
+  record(entry: PulseSurveyEntry): void {
+    // RFC-345 §D3：影子态不写脉冲调查日志（~/.otto/pulse-surveys.jsonl）。
+    if (isShadowModeEnabled()) {
+      return
+    }
+    try {
+      const path = pulseSurveyLogPath()
+      const dir = resolve(OTTO_HOME)
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true })
+      }
+
+      truncateIfOversized(path, this.logger)
+
+      appendFileSync(path, `${JSON.stringify(entry)}\n`)
+    } catch (error) {
+      this.logger.warn(`pulse survey record append failed (fail-soft): ${String(error)}`)
+    }
+  }
+}
+
+/**
+ * `pulse_survey.sink` 配置解析（RFC-208 重要事项规则 4）：当前仅 `'local'` 合法，
+ * 非法值 fallback 到 `'local'` 并 warn，不实现除本地 JSONL 外的任何 sink。
+ */
+export function resolvePulseSurveySink(
+  sinkConfig: string | undefined,
+  logger: FeedbackLoggerPort = noopLogger,
+): PulseSurveySink {
+  if (sinkConfig !== undefined && sinkConfig !== 'local') {
+    logger.warn(`pulse_survey.sink="${sinkConfig}" is not a supported sink; falling back to 'local'`)
+  }
+  return new LocalJsonlPulseSurveySink(logger)
+}