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

package/dist/bundled-extensions/plugin-feedback/plugin.ts

@@ -0,0 +1,198 @@
+/**
+ * plugin.ts —— plugin-feedback 代码式插件入口（RFC-209 D1 feedback 轴；RFC-430 M1
+ * 双平台反馈面板扩展；RFC-440 /feedback 斜杠命令插件化）。
+ *
+ * 承载 RFC-208（满意度脉冲调查记录）+ RFC-207（GitHub issue 提交）+ RFC-430 M1
+ * （github/coding 双源 issue 列表聚合 + 平台判定链 + 本地「已解决」标记）+ RFC-440
+ * （TUI 斜杠命令 /feedback 的插件实现）的业务契约实现。不含任何 TUI/web-ui 渲染
+ * 代码——核心包通过 `FeedbackRegistry` 接口调用本插件导出的方法。
+ *
+ * settings 读取经宿主注入端口（RFC-430 M1：`PluginContext.host.getSettings` 窄
+ * 端口，additive 于 `PluginHostCapabilities`；宿主未注入时静默落默认——平台判定
+ * 链 fail-soft 到 'github'，coding 源报 unavailable），插件不直读配置文件。
+ */
+import { definePlugin } from '@x-otto/plugin'
+import { openBrowser } from '@x-otto/shared'
+import { SDK_VERSION } from '@x-otto/env'
+import { spawn } from 'node:child_process'
+import { platform, arch, release } from 'node:os'
+import { resolvePulseSurveySink } from './src/pulse-survey-sink'
+import { submitIssueViaGh, buildIssueUrl } from './src/issue-submitter'
+import { resolveFeedbackPlatform, type FeedbackSettingsPort } from './src/platform-resolver'
+import { createCodingAdapter } from './src/coding-adapter'
+import { listGithubIssues } from './src/github-lister'
+import { listCodingIssues } from './src/coding-lister'
+import { aggregateIssueLists } from './src/issue-aggregator'
+import { LocalJsonlResolvedMarksSink } from './src/resolved-sink'
+
+import type {
+  FeedbackIssueInput,
+  PulseSurveyEntry,
+  PulseSurveyResolvedConfig,
+  PluginSlashCommandHandler,
+} from '@x-otto/plugin'
+
+/** RFC-207 §3.4：目标仓库解析优先级——settings `feedback_repo` > git remote origin > `--repo` 参数。 */
+function resolveGitRemoteRepo(cwd: string): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    const child = spawn('git', ['remote', 'get-url', 'origin'], { cwd, stdio: ['ignore', 'pipe', 'ignore'] })
+    let out = ''
+    child.stdout?.on('data', (chunk) => { out += String(chunk) })
+    child.on('error', () => resolve(undefined))
+    child.on('exit', (code) => {
+      if (code !== 0) return resolve(undefined)
+      const url = out.trim()
+      // ssh: git@host:owner/repo.git / https: https://host/owner/repo.git → owner/repo
+      const m = url.match(/(?:[:/])([^/:]+)\/([^/]+?)(?:\.git)?$/)
+      resolve(m ? `${m[1]}/${m[2]}` : undefined)
+    })
+  })
+}
+
+/** RFC-207 §3.1 环境信息行（脱敏——只含版本/运行时/OS/模型，不含路径/环境变量）。 */
+function buildEnvInfo(modelId: string | undefined): string {
+  return [
+    `- otto version: ${SDK_VERSION}`,
+    `- Node: ${process.version}`,
+    `- OS: ${platform()} ${arch()} ${release()}`,
+    `- Model: ${modelId ?? '(none configured)'}`,
+  ].join('\n')
+}
+
+/**
+ * RFC-440：TUI 斜杠命令 /feedback 实现（自 RFC-207/209/430 的 cli handler 迁移——
+ * 编排留在插件：面板打开 → openInput 链 → 通道选择 submitIssueViaGh → 降级浏览器）。
+ * 只消费宿主注入的窄桥（ctx.tui/ctx.app），不依赖 cli 包任何符号。
+ * 具名导出供插件包单测直接调用（mock PluginSlashCommandContext）。
+ */
+export const handleFeedbackCommand: PluginSlashCommandHandler = async (ctx) => {
+  const args = ctx.args
+  // RFC-430 M3：裸 /feedback（无参数）→ 打开面板；带 --repo/--title/--browser → 走 openInput 提交。
+  const hasPanelArgs = args.some((a) => a === '--repo' || a === '--title' || a === '--browser')
+  if (!hasPanelArgs) {
+    const panel = ctx.app.pluginPanels.find((p) => p.pluginId === 'plugin-feedback')
+    if (panel) {
+      await ctx.tui.openPluginPanel({
+        title: panel.title,
+        modulePath: panel.modulePath,
+        exportName: panel.exportName,
+        pluginId: panel.pluginId,
+      })
+      return
+    }
+  }
+
+  // ── openInput 提交流程（面板未注册或显式带参数时降级走此路径）──
+  // --repo <owner/repo> 命令行参数（RFC-207 §3.4 解析优先级的第三档）。
+  const repoArgIndex = args.indexOf('--repo')
+  const cliRepoArg = repoArgIndex >= 0 ? args[repoArgIndex + 1] : undefined
+
+  const configuredRepo = ctx.app.settings.get('feedback_repo')
+  const repo =
+    (typeof configuredRepo === 'string' && configuredRepo.length > 0 && configuredRepo) ||
+    (await resolveGitRemoteRepo(ctx.app.workspaceDir)) ||
+    cliRepoArg
+  if (!repo) {
+    ctx.tui.showToast('Feedback', '无法解析目标仓库——请在 .otto/config.json 中配置 "feedback_repo"')
+    return
+  }
+
+  const title = await ctx.tui.openInput({ title: 'Issue 标题' })
+  if (!title || title.trim().length === 0) return // 标题必填，取消/空输入即中止
+
+  const reproduce = (await ctx.tui.openInput({ title: '复现步骤' })) ?? undefined
+  const expected = (await ctx.tui.openInput({ title: '期望行为' })) ?? undefined
+  const actual = (await ctx.tui.openInput({ title: '实际行为' })) ?? undefined
+
+  const envInfo = buildEnvInfo(ctx.app.modelId)
+  const input: FeedbackIssueInput = { title: title.trim(), reproduce, expected, actual, envInfo, repo }
+
+  const bodyPreview = [reproduce, expected, actual].filter(Boolean).join('\n').slice(0, 300)
+  const confirmed = await ctx.tui.confirm('提交反馈？', `${input.title}\n\n${bodyPreview}`)
+  if (!confirmed) return
+
+  ctx.tui.showToast('Feedback', '正在提交…')
+
+  // 通道选择（RFC-207 §2.7/RFC-209 §2.4）：优先 submitIssueViaGh，失败降级 buildIssueUrl + openBrowser。
+  const result = await submitIssueViaGh(input)
+  if (result.ok) {
+    ctx.tui.showToast('Feedback', `已创建: ${result.url}`)
+    return
+  }
+  const url = buildIssueUrl(input)
+  if (url) {
+    openBrowser(url)
+    ctx.tui.showToast('Feedback', `已打开: ${url}`)
+  }
+}
+
+export default definePlugin((ctx) => {
+  // RFC-185 D3：日志走宿主注入端口（ctx.logger），不自建 createLogger——esbuild 会把
+  // @x-otto/shared logger bundle 成第二份 pino 单例直写 stderr 破坏 TUI。
+  const logger = { warn: (msg: string) => ctx.logger.warn(msg) }
+  const sink = resolvePulseSurveySink(undefined, logger)
+  const resolvedSink = new LocalJsonlResolvedMarksSink(logger)
+
+  // RFC-430 M1：settings 读取端口（宿主注入；未注入时全部 undefined —— 判定链落
+  // github、coding 源报 not configured，全部 fail-soft）。settings 值面是宿主权威，
+  // 插件只做窄读取，不缓存（每次调用现读，settings.changed 后自然生效）。
+  // `host.getSettings` 按契约返回 `unknown`（宿主不做类型保证）——插件侧自行运行时
+  // 收窄，非法值落 undefined（fail-soft，判定链据此降级）。
+  const readStringSetting = (key: string): string | undefined => {
+    const v = ctx.host?.getSettings?.(key)
+    return typeof v === 'string' && v.length > 0 ? v : undefined
+  }
+  const settingsPort: FeedbackSettingsPort = {
+    getFeedbackRepo: () => readStringSetting('feedback_repo'),
+    getFeedbackPlatform: () => {
+      const v = ctx.host?.getSettings?.('feedback_platform')
+      return v === 'auto' || v === 'github' || v === 'coding' ? v : undefined
+    },
+    getFeedbackCodingBaseUrl: () => readStringSetting('feedback_coding_base_url'),
+    getFeedbackCodingRepo: () => readStringSetting('feedback_coding_repo'),
+  }
+
+  // Coding 适配器单实例（listIssues 与 buildCodingIssueUrl 共享同一份配置快照语义——
+  // 每次调用时读取 settings 现值，配置变更无需重载插件）。
+  const codingAdapter = createCodingAdapter({
+    get baseUrl() {
+      return settingsPort.getFeedbackCodingBaseUrl()
+    },
+    get repo() {
+      return settingsPort.getFeedbackCodingRepo()
+    },
+    logger,
+  })
+
+  return {
+    // RFC-440：TUI 斜杠命令 /feedback（宿主注入窄桥执行，命令名须与
+    // contributes.slashCommands[].name 对应）。
+    slashCommands: { feedback: handleFeedbackCommand },
+    feedbackProviders: {
+      recordPulseSurvey: (entry: PulseSurveyEntry) => sink.record(entry),
+      resolvePulseSurveyConfig: (raw: unknown): PulseSurveyResolvedConfig => {
+        const cfg = (raw ?? {}) as { enabled?: boolean; probability?: number; min_turn_gap?: number }
+        return {
+          enabled: cfg.enabled ?? true,
+          probability: cfg.probability ?? 0.05,
+          minTurnGap: cfg.min_turn_gap ?? 20,
+        }
+      },
+      submitIssueViaGh: (input: FeedbackIssueInput) => submitIssueViaGh(input, logger),
+      buildIssueUrl,
+
+      // ── RFC-430 M1：双平台反馈面板方法面 ──
+      listIssues: (opts) =>
+        aggregateIssueLists(opts, {
+          github: (o) => listGithubIssues(settingsPort.getFeedbackRepo(), o, { logger }),
+          coding: (o) => listCodingIssues(o, { adapter: codingAdapter }),
+        }),
+      resolveFeedbackPlatform: () => resolveFeedbackPlatform(settingsPort, logger),
+      markIssueResolved: (mark) => Promise.resolve(resolvedSink.mark(mark)),
+      unmarkIssueResolved: (source, platformIssueId) =>
+        Promise.resolve(resolvedSink.unmark(source, platformIssueId)),
+      listResolvedMarks: () => Promise.resolve(resolvedSink.list()),
+      buildCodingIssueUrl: (input: FeedbackIssueInput) => codingAdapter.buildCodingIssueUrl(input),
+    },
+  }
+})

package/dist/bundled-extensions/plugin-feedback/src/coding-adapter.ts

@@ -0,0 +1,183 @@
+/**
+ * coding-adapter.ts — RFC-430 §2.6：Coding 平台（企业内网代码托管）适配器。
+ *
+ * 配置驱动（全部运行时注入，公网源码零内网域名硬编码——scan-public-sensitive.mjs 门禁）：
+ *   - baseUrl：settings `feedback_coding_base_url`（如企业自建托管的 https 地址）；
+ *   - repo：settings `feedback_coding_repo`；
+ *   - token：`OTTO_FEEDBACK_CODING_TOKEN` 环境变量（**绝不落 settings 明文、绝不进日志**）。
+ *
+ * fail-soft 纪律（与 pulse-survey-sink 一致）：所有失败路径（未配置/无 token/网络错误/
+ * 非 2xx/JSON 解析失败）返回 `{ ok: false, reason }`，**不抛出、不穿透**；reason 只携带
+ * HTTP 状态码与失败类别，不回显 URL 以外的任何服务端响应体（防 token/内部信息经日志外泄）。
+ */
+import type { FeedbackIssueInput, FeedbackIssueItem } from '@x-otto/plugin'
+import type { FeedbackLoggerPort } from './pulse-survey-sink'
+
+/** token 环境变量名（集中定义，杜绝散写）。 */
+export const CODING_TOKEN_ENV = 'OTTO_FEEDBACK_CODING_TOKEN'
+
+const noopLogger: FeedbackLoggerPort = { warn: () => {} }
+
+/** fetch 注入点（测试 mock；生产缺省 globalThis.fetch）。 */
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>
+
+export interface CodingAdapterOptions {
+  baseUrl?: string | undefined
+  repo?: string | undefined
+  logger?: FeedbackLoggerPort
+  fetchImpl?: FetchLike
+  /** 单次请求超时（ms），缺省 8000。 */
+  timeoutMs?: number
+  /** 环境变量读取注入点（测试），缺省 process.env。 */
+  env?: Record<string, string | undefined>
+}
+
+export interface CodingAdapter {
+  /** 拉取 issue 列表并归一化为 FeedbackIssueItem[]；任何失败 fail-soft。 */
+  listIssues(opts?: { state?: 'open' | 'closed' | 'all'; limit?: number }): Promise<
+    { ok: true; items: FeedbackIssueItem[] } | { ok: false; reason: string }
+  >
+  /** 构造新建 issue 预填 URL（纯函数）；未配置 baseUrl/repo 返回 null。 */
+  buildCodingIssueUrl(input: FeedbackIssueInput): string | null
+}
+
+/** 归一化 baseUrl：去尾斜杠；非法值返回 undefined。 */
+function normalizeBaseUrl(baseUrl: string | undefined): string | undefined {
+  if (!baseUrl) return undefined
+  const trimmed = baseUrl.trim().replace(/\/+$/, '')
+  return /^https?:\/\//.test(trimmed) ? trimmed : undefined
+}
+
+/** Coding 列表端点（best-effort 通用形态，具体企业部署可在 M2 按真实 API 对齐）。 */
+function codingIssuesUrl(baseUrl: string, repo: string, state: 'open' | 'closed' | 'all', limit: number): string {
+  const params = new URLSearchParams({ state, per_page: String(limit) })
+  return `${baseUrl}/api/v1/repos/${encodeURIComponent(repo)}/issues?${params.toString()}`
+}
+
+/**
+ * 宽容归一化：Coding 列表条目字段名按常见托管 API 形态尽力映射，缺字段降级
+ * undefined，绝不抛（坏条目整条跳过——一条脏数据不应拖垮整个列表）。
+ */
+function normalizeCodingEntry(raw: unknown, baseUrl: string, repo: string): FeedbackIssueItem | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined
+  const r = raw as Record<string, unknown>
+  const idRaw = r['number'] ?? r['id'] ?? r['iid'] ?? r['code']
+  const titleRaw = r['title'] ?? r['name']
+  if (idRaw === undefined || idRaw === null || typeof titleRaw !== 'string') return undefined
+  const stateRaw = typeof r['state'] === 'string' ? r['state'].toLowerCase() : ''
+  const state: 'open' | 'closed' =
+    stateRaw === 'closed' || stateRaw === 'resolved' || stateRaw === 'completed' ? 'closed' : 'open'
+  const url =
+    typeof r['url'] === 'string' ? r['url']
+    : typeof r['html_url'] === 'string' ? r['html_url']
+    : typeof r['web_url'] === 'string' ? r['web_url']
+    : `${baseUrl}/${repo}/issues/${String(idRaw)}`
+  const authorRaw = r['author'] ?? r['creator'] ?? r['user']
+  const author =
+    typeof authorRaw === 'string' ? authorRaw
+    : typeof authorRaw === 'object' && authorRaw !== null
+      ? (() => {
+          const a = authorRaw as Record<string, unknown>
+          return typeof a['login'] === 'string' ? a['login'] : typeof a['name'] === 'string' ? a['name'] : undefined
+        })()
+    : undefined
+  const labelsRaw = r['labels']
+  const labels = Array.isArray(labelsRaw)
+    ? labelsRaw
+        .map((l) => (typeof l === 'string' ? l : typeof l === 'object' && l !== null ? (l as Record<string, unknown>)['name'] : undefined))
+        .filter((l): l is string => typeof l === 'string')
+    : undefined
+  const body = typeof r['body'] === 'string' ? r['body'] : typeof r['description'] === 'string' ? r['description'] : undefined
+  return {
+    source: 'coding',
+    platformIssueId: String(idRaw),
+    title: titleRaw,
+    state,
+    url,
+    ...(author ? { author } : {}),
+    ...(typeof r['created_at'] === 'string' ? { createdAt: r['created_at'] } : {}),
+    ...(typeof r['updated_at'] === 'string' ? { updatedAt: r['updated_at'] } : {}),
+    kind: 'issue',
+    ...(body ? { excerpt: body.slice(0, 140) } : {}),
+    ...(labels && labels.length > 0 ? { labels } : {}),
+  }
+}
+
+export function createCodingAdapter(options: CodingAdapterOptions): CodingAdapter {
+  const logger = options.logger ?? noopLogger
+  const env = options.env ?? process.env
+  const baseUrl = normalizeBaseUrl(options.baseUrl)
+  const repo = options.repo?.trim() || undefined
+  const timeoutMs = options.timeoutMs ?? 8000
+
+  const fetchImpl: FetchLike | undefined =
+    options.fetchImpl ??
+    (typeof globalThis.fetch === 'function' ? (globalThis.fetch as unknown as FetchLike) : undefined)
+
+  return {
+    async listIssues(opts) {
+      if (!baseUrl || !repo) return { ok: false, reason: 'coding not configured' }
+      const token = env[CODING_TOKEN_ENV]
+      if (!token) return { ok: false, reason: `token missing (${CODING_TOKEN_ENV})` }
+      if (!fetchImpl) return { ok: false, reason: 'fetch unavailable' }
+
+      const state = opts?.state ?? 'open'
+      const limit = opts?.limit ?? 20
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), timeoutMs)
+      try {
+        const res = await fetchImpl(codingIssuesUrl(baseUrl, repo, state, limit), {
+          headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+          signal: controller.signal,
+        })
+        if (!res.ok) {
+          // 只带 HTTP 状态码——响应体可能含内部信息，不进 reason/日志。
+          return { ok: false, reason: `http ${res.status}` }
+        }
+        let data: unknown
+        try {
+          data = await res.json()
+        } catch {
+          return { ok: false, reason: 'invalid json' }
+        }
+        const entries = Array.isArray(data)
+          ? data
+          : typeof data === 'object' && data !== null && Array.isArray((data as Record<string, unknown>)['items'])
+            ? ((data as Record<string, unknown>)['items'] as unknown[])
+            : []
+        const items = entries
+          .map((e) => normalizeCodingEntry(e, baseUrl, repo))
+          .filter((e): e is FeedbackIssueItem => e !== undefined)
+        return { ok: true, items }
+      } catch (error) {
+        const reason = controller.signal.aborted
+          ? `timeout after ${timeoutMs}ms`
+          : `network error: ${error instanceof Error ? error.name : 'unknown'}`
+        logger.warn(`coding listIssues failed (fail-soft): ${reason}`)
+        return { ok: false, reason }
+      } finally {
+        clearTimeout(timer)
+      }
+    },
+
+    buildCodingIssueUrl(input) {
+      if (!baseUrl || !repo) return null
+      const title = `[otto] ${input.title}`
+      const body = [
+        '## Reproduction Steps',
+        input.reproduce || '*(not provided)*',
+        '',
+        '## Expected Behavior',
+        input.expected || '*(not provided)*',
+        '',
+        '## Actual Behavior',
+        input.actual || '*(not provided)*',
+        '',
+        '## Environment',
+        input.envInfo,
+      ].join('\\n')
+      const params = new URLSearchParams({ title, body })
+      return `${baseUrl}/${repo}/issues/new?${params.toString()}`
+    },
+  }
+}

package/dist/bundled-extensions/plugin-feedback/src/coding-lister.ts

@@ -0,0 +1,26 @@
+/**
+ * coding-lister.ts — RFC-430 §2.6：Coding 源列表拉取的归一化出口。
+ *
+ * 薄封装层：经 `createCodingAdapter`（coding-adapter.ts，配置/凭据/容错全部内聚在
+ * 适配器里）拉取并归一化为 `FeedbackIssueItem[]`。独立成文件是为了让
+ * issue-aggregator 对两个源（github-lister/coding-lister）看到同构的
+ * `(opts) => Promise<{ok, items|reason}>` 形状，聚合层无需感知适配器细节。
+ */
+import type { FeedbackIssueItem } from '@x-otto/plugin'
+import { createCodingAdapter, type CodingAdapter, type CodingAdapterOptions } from './coding-adapter'
+
+export type CodingListResult = { ok: true; items: FeedbackIssueItem[] } | { ok: false; reason: string }
+
+export interface CodingListerOptions extends CodingAdapterOptions {
+  /** 复用外部已构造的 adapter（plugin.ts 单实例共享 buildCodingIssueUrl）；缺省内部构造。 */
+  adapter?: CodingAdapter
+}
+
+/** Coding 列表主入口（与 listGithubIssues 同构的失败语义：fail-soft 不抛）。 */
+export async function listCodingIssues(
+  opts: { state?: 'open' | 'closed' | 'all'; limit?: number } = {},
+  options: CodingListerOptions = {},
+): Promise<CodingListResult> {
+  const adapter = options.adapter ?? createCodingAdapter(options)
+  return adapter.listIssues(opts)
+}

package/dist/bundled-extensions/plugin-feedback/src/github-lister.ts

@@ -0,0 +1,230 @@
+/**
+ * github-lister.ts — RFC-430 §2.5：GitHub issue 列表双通道拉取。
+ *
+ * 通道优先级：
+ *   1. `gh issue list --json … --repo <repo>`（spawn 数组传参 + buildAllowedEnv +
+ *      超时，gh 探测复用 issue-submitter 的 gh 探测纪律）——本机已认证
+ *      gh 的用户零额外配置；
+ *   2. gh 不可用（未安装/未登录/超时）→ 回落 REST
+ *      `GET https://api.github.com/repos/{repo}/issues`（`OTTO_FEEDBACK_GITHUB_TOKEN`
+ *      env 存在时带 Authorization；缺 token 时匿名请求可能被限流，仍尽力尝试）。
+ *
+ * fail-soft：任何失败返回 `{ ok: false, reason }` 不抛出；JSON 解析容错（缺字段降级
+ * undefined，坏条目跳过）。token 只经 env 注入，不进日志（reason 只带 HTTP 状态码）。
+ */
+import { spawn } from 'node:child_process'
+
+import { buildAllowedEnv } from '@x-otto/shared'
+
+import type { FeedbackIssueItem } from '@x-otto/plugin'
+import type { FeedbackLoggerPort } from './pulse-survey-sink'
+
+/** token 环境变量名（集中定义，杜绝散写）。 */
+export const GITHUB_TOKEN_ENV = 'OTTO_FEEDBACK_GITHUB_TOKEN'
+
+/** gh 探测/列表子进程超时（对齐 issue-submitter 的 GH_AUTH_STATUS_TIMEOUT_MS 纪律）。 */
+const GH_TIMEOUT_MS = 5000
+
+const noopLogger: FeedbackLoggerPort = { warn: () => {} }
+
+export type GhListResult = { ok: true; items: FeedbackIssueItem[] } | { ok: false; reason: string }
+
+export interface GithubListerDeps {
+  logger?: FeedbackLoggerPort
+  /** fetch 注入点（测试 mock）；缺省 globalThis.fetch。 */
+  fetchImpl?: (url: string, init?: RequestInit) => Promise<Response>
+  /** spawn 注入点（测试 mock）；缺省 node:child_process spawn。 */
+  spawnImpl?: typeof spawn
+  /** REST 单次请求超时（ms），缺省 8000。 */
+  restTimeoutMs?: number
+  env?: Record<string, string | undefined>
+}
+
+interface GhJsonEntry {
+  number?: number
+  title?: string
+  state?: string
+  url?: string
+  author?: { login?: string }
+  createdAt?: string
+  updatedAt?: string
+  labels?: Array<{ name?: string }>
+}
+
+function normalizeGhEntry(raw: GhJsonEntry, repo: string): FeedbackIssueItem | undefined {
+  if (typeof raw.number !== 'number' || typeof raw.title !== 'string') return undefined
+  const state: 'open' | 'closed' = raw.state?.toLowerCase() === 'closed' ? 'closed' : 'open'
+  return {
+    source: 'github',
+    platformIssueId: String(raw.number),
+    title: raw.title,
+    state,
+    url: typeof raw.url === 'string' ? raw.url : `https://github.com/${repo}/issues/${raw.number}`,
+    ...(typeof raw.author?.login === 'string' ? { author: raw.author.login } : {}),
+    ...(typeof raw.createdAt === 'string' ? { createdAt: raw.createdAt } : {}),
+    ...(typeof raw.updatedAt === 'string' ? { updatedAt: raw.updatedAt } : {}),
+    kind: 'issue',
+    ...(Array.isArray(raw.labels)
+      ? { labels: raw.labels.map((l) => l?.name).filter((n): n is string => typeof n === 'string') }
+      : {}),
+  }
+}
+
+function runGhIssueList(
+  repo: string,
+  state: 'open' | 'closed' | 'all',
+  limit: number,
+  spawnImpl: typeof spawn,
+): Promise<{ ok: true; stdout: string } | { ok: false; reason: string }> {
+  return new Promise((resolvePromise) => {
+    let settled = false
+    const settle = (v: { ok: true; stdout: string } | { ok: false; reason: string }): void => {
+      if (settled) return
+      settled = true
+      resolvePromise(v)
+    }
+    let child: ReturnType<typeof spawn>
+    try {
+      child = spawnImpl(
+        'gh',
+        [
+          'issue', 'list',
+          '--repo', repo,
+          '--state', state,
+          '--limit', String(limit),
+          '--json', 'number,title,state,url,author,createdAt,updatedAt,labels',
+        ],
+        { env: buildAllowedEnv() },
+      )
+    } catch (error) {
+      settle({ ok: false, reason: `gh spawn failed: ${String(error)}` })
+      return
+    }
+    let stdout = ''
+    let stderr = ''
+    child.stdout?.on('data', (chunk) => { stdout += String(chunk) })
+    child.stderr?.on('data', (chunk) => { stderr += String(chunk) })
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM')
+      settle({ ok: false, reason: `gh timeout after ${GH_TIMEOUT_MS}ms` })
+    }, GH_TIMEOUT_MS)
+    child.on('error', (err) => {
+      clearTimeout(timer)
+      settle({ ok: false, reason: `gh unavailable: ${String(err)}` })
+    })
+    child.on('exit', (code) => {
+      clearTimeout(timer)
+      if (code === 0) settle({ ok: true, stdout })
+      // stderr 可能含远端信息——reason 只带 exit code，不回显 stderr 全文。
+      else settle({ ok: false, reason: `gh exit ${String(code)}: ${stderr.slice(0, 120)}` })
+    })
+  })
+}
+
+/** REST 回落通道：api.github.com/repos/{repo}/issues（PR 条目经 pull_request 字段剔除）。 */
+async function listViaRest(
+  repo: string,
+  state: 'open' | 'closed' | 'all',
+  limit: number,
+  deps: GithubListerDeps,
+): Promise<GhListResult> {
+  const fetchImpl =
+    deps.fetchImpl ??
+    (typeof globalThis.fetch === 'function' ? (globalThis.fetch as unknown as GithubListerDeps['fetchImpl']) : undefined)
+  if (!fetchImpl) return { ok: false, reason: 'fetch unavailable' }
+  const env = deps.env ?? process.env
+  const token = env[GITHUB_TOKEN_ENV]
+  const timeoutMs = deps.restTimeoutMs ?? 8000
+  const params = new URLSearchParams({ state, per_page: String(limit) })
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const res = await fetchImpl(`https://api.github.com/repos/${repo}/issues?${params.toString()}`, {
+      headers: {
+        Accept: 'application/vnd.github+json',
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+      signal: controller.signal,
+    })
+    if (!res.ok) return { ok: false, reason: `http ${res.status}` }
+    let data: unknown
+    try {
+      data = await res.json()
+    } catch {
+      return { ok: false, reason: 'invalid json' }
+    }
+    if (!Array.isArray(data)) return { ok: false, reason: 'unexpected payload shape' }
+    const items: FeedbackIssueItem[] = []
+    for (const raw of data) {
+      if (typeof raw !== 'object' || raw === null) continue
+      const r = raw as Record<string, unknown>
+      // GitHub /issues 端点混入 PR——kind 词表无 'pr'，跳过。
+      if (r['pull_request'] !== undefined) continue
+      const labelsRaw = r['labels']
+      const item: FeedbackIssueItem = {
+        source: 'github',
+        platformIssueId: String(r['number'] ?? ''),
+        title: typeof r['title'] === 'string' ? r['title'] : '',
+        state: r['state'] === 'closed' ? 'closed' : 'open',
+        url: typeof r['html_url'] === 'string' ? r['html_url'] : `https://github.com/${repo}/issues/${String(r['number'] ?? '')}`,
+        kind: 'issue',
+      }
+      if (!item.platformIssueId || !item.title) continue
+      const user = r['user']
+      if (typeof user === 'object' && user !== null && typeof (user as Record<string, unknown>)['login'] === 'string') {
+        item.author = (user as Record<string, unknown>)['login'] as string
+      }
+      if (typeof r['created_at'] === 'string') item.createdAt = r['created_at']
+      if (typeof r['updated_at'] === 'string') item.updatedAt = r['updated_at']
+      if (typeof r['body'] === 'string' && r['body']) item.excerpt = r['body'].slice(0, 140)
+      if (Array.isArray(labelsRaw)) {
+        item.labels = labelsRaw
+          .map((l) => (typeof l === 'object' && l !== null ? (l as Record<string, unknown>)['name'] : undefined))
+          .filter((n): n is string => typeof n === 'string')
+      }
+      items.push(item)
+    }
+    return { ok: true, items }
+  } catch (error) {
+    const reason = controller.signal.aborted
+      ? `timeout after ${timeoutMs}ms`
+      : `network error: ${error instanceof Error ? error.name : 'unknown'}`
+    return { ok: false, reason }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * GitHub 列表主入口：gh CLI 优先，gh 不可用时回落 REST。`repo` 为空（未配置
+ * feedback_repo 且宿主未解析出 git remote）时直接失败，不发起任何调用。
+ */
+export async function listGithubIssues(
+  repo: string | undefined,
+  opts: { state?: 'open' | 'closed' | 'all'; limit?: number } = {},
+  deps: GithubListerDeps = {},
+): Promise<GhListResult> {
+  const logger = deps.logger ?? noopLogger
+  if (!repo) return { ok: false, reason: 'feedback_repo not configured' }
+  const state = opts.state ?? 'open'
+  const limit = opts.limit ?? 20
+  const spawnImpl = deps.spawnImpl ?? spawn
+
+  const ghResult = await runGhIssueList(repo, state, limit, spawnImpl)
+  if (ghResult.ok) {
+    try {
+      const parsed = JSON.parse(ghResult.stdout) as unknown
+      if (!Array.isArray(parsed)) return { ok: false, reason: 'gh output not a json array' }
+      const items = parsed
+        .map((e) => normalizeGhEntry(e as GhJsonEntry, repo))
+        .filter((e): e is FeedbackIssueItem => e !== undefined)
+      return { ok: true, items }
+    } catch {
+      return { ok: false, reason: 'gh output invalid json' }
+    }
+  }
+
+  // gh 不可用 → REST 回落（token 存在时带 Authorization，缺省匿名尽力尝试）。
+  logger.warn(`gh issue list unavailable, falling back to REST: ${ghResult.reason}`)
+  return listViaRest(repo, state, limit, deps)
+}