@xiaobuyu/nodesign 0.0.1

package/server/lib/ingress/slot-probe.js

@@ -0,0 +1,130 @@
+/**
+ * lib/ingress/slot-probe.js — 模型插槽体检（08-22，探针脚本转正）。
+ *
+ * 配置页「体检」按钮打的就是它：对一行 API 模型，**穿过进程内入口**（model-ingress → 转换层 → 上游）
+ * 发五发最小请求，回一张红绿表。为什么必须穿入口而不是直打上游：quirk 表按上游写（gproxy 的
+ * network_error、refusal 映射、空体 5xx），用户自带的新端点踩的坑和内置行不一样，直打上游测不出转换层
+ * 那一段；而真会话里 CLI 发的就是经过入口的请求（body.model 是剥了 [1m] 的 sdkAlias）。
+ *
+ * 五项：text（非流式）/ stream（SSE）/ tool_use（工具调用 + 入参能解析）/ vision（64×64 纯红图问颜色）/
+ * count_tokens。vision 与 count_tokens 标 info：上游不支持不算这行不能当主力，但用户该知道。
+ *
+ * 订阅行不经入口（CLI 自己的登录态），这里不探，回一条说明。
+ */
+
+import sharp from 'sharp';
+import { getOrStartIngress } from '../model-ingress.js';
+import { registerIngressSession, unregisterIngressSession } from './session-routes.js';
+import { resolveModelRoute } from '../../engine/agent/model-context.js';
+
+const PEEK_TOOL = {
+  name: 'peek',
+  description: 'Return the secret number. Call it with a one-sentence reason.',
+  input_schema: { type: 'object', properties: { reason: { type: 'string' } }, required: ['reason'] },
+};
+
+async function redPng() {
+  return (await sharp({ create: { width: 64, height: 64, channels: 3, background: { r: 220, g: 20, b: 20 } } }).png().toBuffer()).toString('base64');
+}
+
+function parseSse(text) {
+  const events = [];
+  for (const chunk of text.split(/\n\n+/)) {
+    const line = chunk.split('\n').find((l) => l.startsWith('data:'));
+    if (!line) continue;
+    try { events.push(JSON.parse(line.slice(5).trim())); } catch { /* 非 JSON 行（ping 等）跳过 */ }
+  }
+  return events;
+}
+
+const textOf = (json) => (json?.content || []).filter((b) => b.type === 'text').map((b) => b.text).join('').trim();
+
+/**
+ * @param {string} appModel
+ * @param {{ timeoutMs?: number, vision?: boolean }} [opts]
+ * @returns {Promise<{ appModel: string, mode: 'api'|'subscription', checks: Array<{ id, label, ok: boolean|null, level: 'core'|'info', ms: number, note: string }> }>}
+ */
+export async function probeModel(appModel, { timeoutMs = 45_000, vision = true } = {}) {
+  const route = resolveModelRoute(appModel);
+  if (route.mode !== 'api') {
+    return { appModel, mode: 'subscription', checks: [{ id: 'subscription', label: '订阅/直连行', ok: null, level: 'info', ms: 0,
+      note: '这一行由 Claude Code 自己的登录态或 ANTHROPIC_API_KEY 驱动，不经入口，这里不探；开个项目发一句话就能验' }] };
+  }
+  const ingress = await getOrStartIngress();
+  const tag = `probe-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+  registerIngressSession(tag, appModel);
+  const model = route.sdkAlias.replace(/\[1m\]$/i, '');   // CLI 序列化时剥 [1m]，体检照它发
+  const base = `${ingress.baseUrl}/__nd/${encodeURIComponent(tag)}`;
+  const checks = [];
+
+  async function post(path, body) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    const t0 = Date.now();
+    try {
+      const res = await fetch(base + path, {
+        method: 'POST', signal: ac.signal,
+        headers: { 'content-type': 'application/json', 'x-api-key': 'nd-ingress-managed', 'anthropic-version': '2023-06-01' },
+        body: JSON.stringify({ model, ...body }),
+      });
+      const text = await res.text();
+      let json = null; try { json = JSON.parse(text); } catch { /* SSE 或非 JSON */ }
+      return { status: res.status, text, json, ms: Date.now() - t0 };
+    } catch (err) {
+      return { status: 0, text: '', json: null, ms: Date.now() - t0, error: err.name === 'AbortError' ? `超时 ${timeoutMs / 1000}s` : err.message };
+    } finally { clearTimeout(timer); }
+  }
+  const errNote = (r) => r.error || `HTTP ${r.status}${r.text ? `：${r.text.slice(0, 160)}` : ''}`;
+
+  try {
+    // 1 text
+    {
+      const r = await post('/v1/messages', { max_tokens: 32, messages: [{ role: 'user', content: 'Reply with exactly the word pong and nothing else.' }] });
+      const ok = r.status === 200 && !!textOf(r.json);
+      checks.push({ id: 'text', label: '非流式文本', ok, level: 'core', ms: r.ms,
+        note: ok ? `答「${textOf(r.json).slice(0, 40)}」 stop=${r.json.stop_reason} in/out=${r.json.usage?.input_tokens ?? '?'}/${r.json.usage?.output_tokens ?? '?'}` : errNote(r) });
+    }
+    // 2 stream
+    {
+      const r = await post('/v1/messages', { max_tokens: 32, stream: true, messages: [{ role: 'user', content: 'Reply with exactly the word pong and nothing else.' }] });
+      const ev = r.status === 200 ? parseSse(r.text) : [];
+      const types = new Set(ev.map((e) => e.type));
+      const delta = ev.filter((e) => e.type === 'content_block_delta' && e.delta?.type === 'text_delta').map((e) => e.delta.text).join('');
+      const ok = r.status === 200 && types.has('message_start') && types.has('message_stop') && !!delta.trim();
+      const errEv = ev.find((e) => e.type === 'error');
+      checks.push({ id: 'stream', label: '流式（SSE）', ok, level: 'core', ms: r.ms,
+        note: ok ? `${ev.length} 个事件，文本「${delta.trim().slice(0, 40)}」` : (r.status === 200 ? `事件类型 ${[...types].join(',') || '(空)'}${errEv ? ` error=${JSON.stringify(errEv.error || errEv).slice(0, 120)}` : ''}` : errNote(r)) });
+    }
+    // 3 tool_use
+    {
+      const r = await post('/v1/messages', { max_tokens: 200, tools: [PEEK_TOOL], tool_choice: { type: 'any' },
+        messages: [{ role: 'user', content: 'Call the peek tool now with a short reason. Do not answer in text.' }] });
+      const tu = (r.json?.content || []).find((b) => b.type === 'tool_use');
+      const ok = r.status === 200 && !!tu && tu.name === 'peek' && tu.input && typeof tu.input === 'object';
+      checks.push({ id: 'tool_use', label: '工具调用', ok, level: 'core', ms: r.ms,
+        note: ok ? `stop=${r.json.stop_reason} input=${JSON.stringify(tu.input).slice(0, 80)}` : (r.status === 200 ? `没发起 tool_use（stop=${r.json?.stop_reason}，内容=${textOf(r.json).slice(0, 80) || JSON.stringify(r.json?.content || []).slice(0, 80)}）` : errNote(r)) });
+    }
+    // 4 vision
+    if (vision) {
+      const png = await redPng();
+      const r = await post('/v1/messages', { max_tokens: 32, messages: [{ role: 'user', content: [
+        { type: 'image', source: { type: 'base64', media_type: 'image/png', data: png } },
+        { type: 'text', text: 'What color is this image? Answer with one English word.' },
+      ] }] });
+      const ans = textOf(r.json);
+      const ok = r.status === 200 && /red/i.test(ans);
+      checks.push({ id: 'vision', label: '看图', ok, level: 'info', ms: r.ms,
+        note: r.status === 200 ? `纯红图答「${ans.slice(0, 40)}」${ok ? '' : '（没认出 red：这行看不了图，截图自检会瞎）'}` : errNote(r) });
+    }
+    // 5 count_tokens
+    {
+      const r = await post('/v1/messages/count_tokens', { messages: [{ role: 'user', content: 'hello there' }] });
+      const ok = r.status === 200 && Number.isFinite(r.json?.input_tokens);
+      checks.push({ id: 'count_tokens', label: 'count_tokens', ok, level: 'info', ms: r.ms,
+        note: ok ? `input_tokens=${r.json.input_tokens}（上游没有该端点时入口本地估算，数会偏）` : errNote(r) });
+    }
+  } finally {
+    unregisterIngressSession(tag);
+  }
+  return { appModel, mode: 'api', upstream: route.upstreamId, wireModel: route.upstream && undefined, checks };
+}

package/server/lib/ingress/upstream-billing.js

@@ -0,0 +1,52 @@
+/**
+ * lib/ingress/upstream-billing.js —— 上游**自报**的费用/用量，按会话 × appModel 累加，供回合结账取走。
+ *
+ * 背景（08-21 晚）：Zen 的 /zen/go 入口每个响应带 `cost`（美元字符串；流式在 [DONE] 之后补一条
+ * {"choices":[],"cost":"…"}）和 usage.prompt_tokens_details.cached_tokens。我们原来的仪表是
+ * "SDK 按 alias 的 Claude 价目算 → reprice 按表价重算"，CLI 失败时还按字符估算 —— 假表。
+ * 上游报了真数就用真数：ingress 每次往返 note 一笔，session-loop 在 absorbResult 之后 take 走本轮累计，
+ * 覆盖 counters.modelUsage[appModel].costUsd（context.applyUpstreamBilling）。
+ *
+ * 只覆盖 cost，token 数仍以 SDK 的 modelUsage 差分为准（两边口径不同：OpenAI 的 prompt_tokens 含缓存命中）；
+ * SDK 没给该模型条目时（CLI 失败 / helper），用上游 token 数补一条，别让这笔钱无家可归。
+ * 上游没报 cost（cost 为 null）就不动任何东西 —— 假数据比没有更坏。
+ */
+
+export class UpstreamBilling {
+  constructor() { this.map = new Map(); }   // sid → Map<appModel, acc>
+  /**
+   * @param {string} sid
+   * @param {string} appModel
+   * @param {{ costUsd?: number|null, usage?: object|null }} info
+   */
+  note(sid, appModel, { costUsd = null, usage = null } = {}) {
+    if (!sid || !appModel) return;
+    const c = costUsd == null || !Number.isFinite(Number(costUsd)) ? null : Number(costUsd);
+    if (c == null && !usage) return;
+    let per = this.map.get(sid);
+    if (!per) { per = new Map(); this.map.set(sid, per); }
+    const acc = per.get(appModel) || { costUsd: null, responses: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, reasoningTokens: 0 };
+    acc.responses += 1;
+    if (c != null) acc.costUsd = (acc.costUsd || 0) + c;
+    if (usage) {
+      acc.promptTokens += Number(usage.prompt_tokens) || 0;
+      acc.completionTokens += Number(usage.completion_tokens) || 0;
+      acc.cachedTokens += Number(usage.prompt_tokens_details?.cached_tokens) || 0;
+      acc.reasoningTokens += Number(usage.completion_tokens_details?.reasoning_tokens) || 0;
+    }
+    per.set(appModel, acc);
+  }
+  /** 取走并清零该会话的累计：{ appModel → acc }；没有 → null */
+  take(sid) {
+    const per = sid ? this.map.get(sid) : null;
+    if (!per) return null;
+    this.map.delete(sid);
+    return Object.fromEntries(per);
+  }
+  peek(sid) { const per = this.map.get(sid); return per ? Object.fromEntries(per) : null; }
+  clear(sid) { if (sid) this.map.delete(sid); else this.map.clear(); }
+}
+
+export const upstreamBilling = new UpstreamBilling();
+export const noteUpstreamBilling = (sid, appModel, info) => upstreamBilling.note(sid, appModel, info);
+export const takeUpstreamBilling = (sid) => upstreamBilling.take(sid);

package/server/lib/ingress/upstream-fail-streak.js

@@ -0,0 +1,72 @@
+/**
+ * lib/ingress/upstream-fail-streak.js —— 每会话的上游连续失败计数（08-21 晚，僵尸 run 案）。
+ *
+ * 病：Zen 持续回 503 / network_error 时，我们按规矩发 5xx 或流内 error 事件，CLI 对 5xx 做**无上限**
+ * 指数退避重试（假上游实测：75s 内 16 次还在涨），每次又挂 Zen 50~185s —— 一个回合跑了一小时，
+ * 用户早断线，run 一直 running。流内 error 事件本身 CLI 只试 4 次就放弃，真正喂活循环的是
+ * 非流式兜底那一跳拿到的 502/503。
+ *
+ * 治法：同一会话连续 N 次上游失败后，ingress 对下一个请求直接回 **HTTP 400**（invalid_request_error）。
+ * 假上游 + 真 SDK 循环实测：400 不重试、回合以 is_error 的 result 收场、错误文本原样到用户、
+ * streamInput 会话不死（下一条消息照常处理）。消费掉上限后计数归零，用户再发就有新的 N 次机会。
+ *
+ * 什么算失败：上游 5xx / 转发层网络错 / 200 但零 choices / 私货 finish_reason 且零可见输出（流式与
+ * 非流式都算）。什么算成功：一次回应带可见内容（或透传路 2xx）。成功一次就清零。
+ * 超过 DECAY_MS 没有新失败也清零（别让昨天的坏账拦今天的人）。
+ */
+
+export const DEFAULT_MAX = 4;
+export const DECAY_MS = 30 * 60 * 1000;
+
+export function failStreakMax(env = process.env) {
+  const v = Number(env.NODESIGN_UPSTREAM_FAIL_STREAK);
+  return Number.isInteger(v) && v > 0 ? v : DEFAULT_MAX;
+}
+
+export class FailStreaks {
+  constructor({ max = null, decayMs = DECAY_MS, now = () => Date.now() } = {}) {
+    this.map = new Map();   // sid → { n, last, reason }
+    this.maxOverride = max;
+    this.decayMs = decayMs;
+    this.now = now;
+  }
+  get max() { return this.maxOverride ?? failStreakMax(); }
+  /** 记一次结果。ok=true 清零；ok=false 累加并记原因。返回当前计数。 */
+  note(sid, ok, reason = '') {
+    if (!sid) return 0;
+    if (ok) { this.map.delete(sid); return 0; }
+    const now = this.now();
+    const cur = this.map.get(sid);
+    const n = cur && now - cur.last < this.decayMs ? cur.n + 1 : 1;
+    this.map.set(sid, { n, last: now, reason: String(reason || '').slice(0, 160) });
+    return n;
+  }
+  /** 到上限了吗（含衰减判断） */
+  exhausted(sid) {
+    const cur = sid ? this.map.get(sid) : null;
+    if (!cur) return false;
+    if (this.now() - cur.last >= this.decayMs) { this.map.delete(sid); return false; }
+    return cur.n >= this.max;
+  }
+  /** 取走并清零：返回 { n, reason }，用于组拒绝话术；之后用户再发有新的 max 次机会 */
+  consume(sid) {
+    const cur = this.map.get(sid) || { n: 0, reason: '' };
+    this.map.delete(sid);
+    return cur;
+  }
+  clear(sid) { if (sid) this.map.delete(sid); else this.map.clear(); }
+}
+
+/** ingress 进程内单例 */
+export const failStreaks = new FailStreaks();
+
+/** 拒绝体（Anthropic error 形状；400 = CLI 不重试，实测） */
+export function exhaustedErrorBody({ label, n, reason }) {
+  return {
+    type: 'error',
+    error: {
+      type: 'invalid_request_error',
+      message: `${label} 连续 ${n} 次没有返回可用内容（最近一次：${reason || '未知'}），这轮先停了。稍后再发一次，或换个模型。`,
+    },
+  };
+}

package/server/lib/ingress/upstream-truncation.js

@@ -0,0 +1,48 @@
+/**
+ * lib/ingress/upstream-truncation.js —— 「上一次响应是不是半截」的会话级标记（08-21 晚）。
+ *
+ * 病：Zen 会在模型说到一半时把流掐了（无 finish_reason，或私货 finish 如 network_error），
+ * 而正文已经吐出来一部分。转换层照旧按 end_turn 收尾（这是对的，假上游实测：有可见输出后
+ * 再发 error 事件 CLI 不重试、只会把半截 + "Server error mid-response" 一起判 is_error 给用户），
+ * 于是**半截答案就成了最终答案** —— agent 说了半句话就收工，用户以为它答完了。
+ * 08-21 当天生产日志 4 次。
+ *
+ * 治法（对齐 OpenCode 1.18.21 对 unknown finish 的处理）：ingress 每次往返把「半截」标记记到
+ * 会话上，session-loop 收到 result 时取走；有标记就自动补一条续接消息再跑一轮，
+ * 半截那段原样留在对话历史里（跟 OpenCode 一样，不删不改，让模型自己接着说）。
+ *
+ * 只记**最近一次**，不累加：一个回合里有多次 API 往返（工具调用），我们关心的是收尾那次
+ * 是不是半截。任何一次完整收尾都把标记清掉。
+ */
+
+export class UpstreamTruncation {
+  constructor({ now = () => Date.now() } = {}) {
+    this.map = new Map();   // sid → { reason, appModel, at }
+    this.now = now;
+  }
+  /**
+   * 记一次往返的收尾形态。truncated 为 null/'' = 这次收得完整 → 清掉旧标记。
+   * @param {string} sid
+   * @param {string|null} truncated  半截原因串（openai-chat.js 的 truncationReason 产出）
+   * @param {{ appModel?: string }} [meta]
+   */
+  note(sid, truncated, { appModel = '' } = {}) {
+    if (!sid) return;
+    if (!truncated) { this.map.delete(sid); return; }
+    this.map.set(sid, { reason: String(truncated).slice(0, 120), appModel, at: this.now() });
+  }
+  /** 取走并清零：{ reason, appModel, at } 或 null */
+  take(sid) {
+    if (!sid) return null;
+    const cur = this.map.get(sid) || null;
+    this.map.delete(sid);
+    return cur;
+  }
+  clear(sid) { if (sid) this.map.delete(sid); else this.map.clear(); }
+}
+
+/** ingress 进程内单例 */
+export const upstreamTruncation = new UpstreamTruncation();
+
+export function noteUpstreamTruncation(sid, truncated, meta) { upstreamTruncation.note(sid, truncated, meta); }
+export function takeUpstreamTruncation(sid) { return upstreamTruncation.take(sid); }

package/server/lib/issues-store.js

@@ -0,0 +1,182 @@
+/**
+ * server/lib/issues-store.js — harness 问题库（2026-07-30）
+ *
+ * 两层写同一张表：
+ *
+ *   auto  —— PostToolUseFailure 钩子自动记的每次工具失败。**不依赖 agent 的自觉**，
+ *            抓得到"某个工具这周失败 40 次但从来没人提过"这种。agent 太会兜底了，
+ *            工具坏了它换个姿势就过去了，表面上活儿还是干完的。
+ *   agent —— report_friction 工具主动报的摩擦：为什么绕路、期望的接口长什么样。
+ *            这是 auto 层拿不到的那半句 —— "screenshot 超时 12 次"指不出修法，
+ *            "我只想要首屏但只能 fullPage 再自己裁"才指得出。
+ *
+ * 为什么是 SQLite 不是 issue 目录：要看的是"哪个问题最频繁"，那是聚合查询；
+ * 散文件每次都得自己数。同一类问题按 (source, tool_name, signature) 累加 count，
+ * 不是堆一万条重复记录。
+ */
+
+import crypto from 'node:crypto';
+import db from '../engine/runs/store.js';
+
+db.exec(`
+  CREATE TABLE IF NOT EXISTS issues (
+    id           TEXT PRIMARY KEY,
+    source       TEXT NOT NULL,          -- 'auto' | 'agent'
+    tool_name    TEXT,
+    signature    TEXT NOT NULL,          -- 归一化指纹，聚合键
+    summary      TEXT NOT NULL,
+    detail       TEXT,
+    expectation  TEXT,                   -- agent 期望的解决方案（自述层才有）
+    project_id   TEXT,
+    session_id   TEXT,
+    run_id       TEXT,
+    user_id      TEXT,
+    count        INTEGER NOT NULL DEFAULT 1,
+    status       TEXT NOT NULL DEFAULT 'open',   -- 'open' | 'ack' | 'ignored' | 'closed'
+    first_seen   TEXT NOT NULL DEFAULT (datetime('now')),
+    last_seen    TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE UNIQUE INDEX IF NOT EXISTS idx_issues_key ON issues(source, tool_name, signature);
+  CREATE INDEX IF NOT EXISTS idx_issues_count ON issues(status, count DESC);
+`);
+
+// kind 轴（2026-08-02，上报工具扩容）：bug=行为错了 / friction=能用但绕路 /
+// idea=改进想法（没坏也值得说）。老行回填：auto 全是工具失败事件 → bug；
+// agent 存量按原语义 → friction。回填只在加列那一次跑，之后 kind 归写入方管。
+{
+  const cols = new Set(db.prepare('PRAGMA table_info(issues)').all().map(c => c.name));
+  if (!cols.has('kind')) {
+    db.exec("ALTER TABLE issues ADD COLUMN kind TEXT NOT NULL DEFAULT 'friction'");
+    db.exec("UPDATE issues SET kind = 'bug' WHERE source = 'auto'");
+    console.log('[issues] kind column added (auto 存量回填为 bug)');
+  }
+}
+
+/**
+ * 错误指纹：把可变部分抹掉，留下问题的"类"。
+ * 不归一化的话同一个毛病会因为路径/行号/时间戳不同散成几十条，聚合就没意义了。
+ */
+export function signatureOf(text) {
+  const norm = String(text || '')
+    .replace(/[/~][\w.\-/@ 一-鿿]+/g, '<path>')   // 路径
+    .replace(/\b[0-9a-f]{8,}\b/gi, '<hash>')      // id / hash
+    .replace(/\d+/g, 'N')                          // 行号、字节数、耗时
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 300);
+  return crypto.createHash('sha1').update(norm).digest('hex').slice(0, 16);
+}
+
+function newId() {
+  return `iss_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+}
+
+/**
+ * 记一条（同类累加）。任何调用点都必须 fail-soft —— 记录问题这件事本身不能变成
+ * 新的故障源，所以这里吞掉一切异常。
+ * @returns {{ id: string, count: number } | null}
+ */
+const KINDS = new Set(['bug', 'friction', 'idea']);
+
+export function recordIssue({
+  source, toolName, summary, detail, expectation,
+  projectId, sessionId, runId, userId, signature, kind,
+}) {
+  try {
+    if (!summary) return null;
+    const k = KINDS.has(kind) ? kind : (source === 'auto' ? 'bug' : 'friction');
+    const sig = signature || signatureOf(`${toolName || ''}|${detail || summary}`);
+    const key = { source, toolName: toolName || null, sig };
+    const existing = db.prepare(
+      'SELECT id, count FROM issues WHERE source = ? AND tool_name IS ? AND signature = ?',
+    ).get(key.source, key.toolName, key.sig);
+
+    if (existing) {
+      db.prepare(`UPDATE issues
+                  SET count = count + 1, last_seen = datetime('now'),
+                      project_id = COALESCE(?, project_id),
+                      session_id = COALESCE(?, session_id),
+                      run_id = COALESCE(?, run_id),
+                      status = CASE WHEN status = 'closed' THEN 'open' ELSE status END
+                  WHERE id = ?`)
+        .run(projectId ?? null, sessionId ?? null, runId ?? null, existing.id);
+      return { id: existing.id, count: existing.count + 1 };
+    }
+
+    const id = newId();
+    db.prepare(`INSERT INTO issues
+        (id, source, kind, tool_name, signature, summary, detail, expectation,
+         project_id, session_id, run_id, user_id)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+      .run(id, source, k, key.toolName, key.sig,
+        String(summary).slice(0, 300),
+        detail ? String(detail).slice(0, 4000) : null,
+        expectation ? String(expectation).slice(0, 2000) : null,
+        projectId ?? null, sessionId ?? null, runId ?? null, userId ?? null);
+    return { id, count: 1 };
+  } catch (err) {
+    console.warn('[issues] record failed:', err.message);
+    return null;
+  }
+}
+
+function rowToIssue(r) {
+  if (!r) return null;
+  return {
+    id: r.id,
+    source: r.source,
+    kind: r.kind || 'friction',
+    toolName: r.tool_name,
+    signature: r.signature,
+    summary: r.summary,
+    detail: r.detail,
+    expectation: r.expectation,
+    projectId: r.project_id,
+    sessionId: r.session_id,
+    runId: r.run_id,
+    userId: r.user_id,
+    count: r.count,
+    status: r.status,
+    firstSeen: r.first_seen,
+    lastSeen: r.last_seen,
+  };
+}
+
+/**
+ * 默认按次数降序 —— 一眼看到最该修的那个。
+ * status/source 传 'all' 或空 = 不过滤：这两个字段直接当 SQL 值用过一次，
+ * `status:'all'` 匹配不到任何行却返空数组，读起来像"库里是干净的"（体检脚本
+ * 就这么漏过一条残留）。宁可在这里认掉这个词，不让空结果继续说谎。
+ */
+export function listIssues({ status, source, kind, limit = 200 } = {}) {
+  const where = [];
+  const args = [];
+  if (status && status !== 'all') { where.push('status = ?'); args.push(status); }
+  if (source && source !== 'all') { where.push('source = ?'); args.push(source); }
+  if (kind && kind !== 'all') { where.push('kind = ?'); args.push(kind); }
+  const sql = `SELECT * FROM issues${where.length ? ` WHERE ${where.join(' AND ')}` : ''}
+               ORDER BY count DESC, last_seen DESC LIMIT ?`;
+  return db.prepare(sql).all(...args, limit).map(rowToIssue);
+}
+
+const STATUSES = new Set(['open', 'ack', 'ignored', 'closed']);
+
+export function setIssueStatus(id, status) {
+  if (!STATUSES.has(status)) throw new Error(`invalid status: ${status}`);
+  const info = db.prepare('UPDATE issues SET status = ? WHERE id = ?').run(status, id);
+  return info.changes > 0 ? rowToIssue(db.prepare('SELECT * FROM issues WHERE id = ?').get(id)) : null;
+}
+
+export function removeIssue(id) {
+  return db.prepare('DELETE FROM issues WHERE id = ?').run(id).changes > 0;
+}
+
+/** 顶栏/概览用：open 状态下按工具聚合的次数 */
+export function issueStats() {
+  const rows = db.prepare(
+    `SELECT tool_name, source, SUM(count) AS total, COUNT(*) AS kinds
+     FROM issues WHERE status = 'open' GROUP BY tool_name, source ORDER BY total DESC`,
+  ).all();
+  return rows.map(r => ({ toolName: r.tool_name, source: r.source, total: r.total, kinds: r.kinds }));
+}

package/server/lib/kinds/deck.js

@@ -0,0 +1,72 @@
+/**
+ * kinds/deck.js — deck 形态（演示 / 长图 / 单页报告）
+ *
+ * 形态契约见 kinds/index.js。deck 是「源即产物」的退化形态：
+ * canvas.html 既是工作对象也是被导出的东西，产物根永远是任务根。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { isReservedFile } from '../task-scan.js';
+
+const ENTRY = 'canvas.html';
+
+export default {
+  id: 'deck',
+  entryFile: ENTRY,
+  view: 'deck',
+  injectFit: true,          // 导出 / 独立打开时注入整屏翻页 fit script
+  capabilities: ['browsable'],   // 入口是 html，能塞进 iframe / playwright
+  exportFormats: ['html', 'pdf', 'pptx', 'handoff'],
+  referenceDoc: { file: 'hybrid-reference', title: 'Hybrid deck 技术参考' },
+
+  // deck 没有构建这回事，产物根 = 任务根
+  artifactRoot: async () => '',
+
+  /**
+   * deck 实例发现（2026-07-29 多产物平权）：任务根顶层每个 .html 各是一份
+   * **平等的** deck，没有主次。canvas.html 只是常用名（判定证据 + 无提示时
+   * 的排序偏好），不再有"主 deck / 试作"等级。
+   *
+   * @param {boolean} [opts.rootSiteExists]  任务根是一个站点时，顶层散装
+   *        .html 是站点页面不是 deck —— 只有 canvas.html（范式保留名）除外
+   */
+  async discoverInstances(taskDir, _marker, opts = {}) {
+    let entries = [];
+    try { entries = await fs.readdir(taskDir, { withFileTypes: true }); } catch { /* */ }
+    return entries
+      .filter(e => e.isFile() && /\.html?$/i.test(e.name) && !e.name.startsWith('.'))
+      .filter(e => !isReservedFile(e.name))
+      .map(e => e.name)
+      .filter(f => !opts.rootSiteExists || f === ENTRY)
+      .sort((a, b) => (b === ENTRY) - (a === ENTRY) || a.localeCompare(b))
+      .map(f => ({ file: f }));
+  },
+
+  async instanceManifest(taskDir, _marker, inst) {
+    return {
+      kind: 'deck',
+      root: '',
+      srcRoot: '',
+      entry: inst.file,
+      entryRel: inst.file,
+      file: inst.file,
+      pages: null,
+      single: false,
+      title: inst.file === ENTRY ? null : inst.file.replace(/\.html?$/i, ''),
+    };
+  },
+
+  /** 每轮注入的产物清单里，这份 deck 的一行说明 */
+  async describe(taskDir, artifact) {
+    const entryAbs = path.join(taskDir, artifact.entryRel);
+    const label = `deck ${artifact.entryRel}`;
+    try {
+      const stat = await fs.stat(entryAbs);
+      if (stat.size > 512 * 1024) return `${label} · ${(stat.size / 1024).toFixed(0)}KB，Read 时配 limit 分段读`;
+      const raw = await fs.readFile(entryAbs, 'utf8');
+      const n = (raw.match(/<section\b[^>]*\bdata-page=/g) || []).length;
+      return n > 0 ? `${label} · ${n} 页` : `${label} · 还没有 <section data-page=> 分页结构`;
+    } catch { return `${label} · 入口读不到`; }
+  },
+};