dsh-github-flow 0.6.0 → 0.7.1

package/lib/renderers/task.js

@@ -0,0 +1,120 @@
+/**
+ * `github_task` 的 Markdown 渲染器。
+ *
+ * 为什么单独渲染而不是 JSON 直出：原语的返回值是「给模型看的结论包」，
+ * 其中 `cost` 与 `truncated` 是审计信息、`facts` 是结构化事实。
+ * 直接 JSON.stringify 会把最重要的 `summary` 埋在括号里；
+ * 而只渲染 summary 又会丢掉「这次花了多少」——两者都要，但要有主次。
+ */
+import { appendDegradedNote } from './common.js';
+/** 把任意值渲染成紧凑的一行（对象/数组走 JSON，字符串原样） */
+function brief(v, max = 120) {
+    const text = typeof v === 'string' ? v : JSON.stringify(v);
+    const s = String(text ?? '');
+    return s.length > max ? s.slice(0, max) + '…' : s;
+}
+export function renderTaskMarkdown(args, value) {
+    if (!value || typeof value !== 'object')
+        return String(value ?? '');
+    const action = typeof args?.action === 'string' ? args.action : '';
+    const lines = [];
+    // 闸门拦截载荷必须最先渲染。
+    // 为什么：s8 新增 github_task 时漏了这条分支，write:true 但不传 confirm 会被
+    // 渲染成「### review_pr 完成」——模型据此向用户汇报「已提交评审」，而实际
+    // 一次 gh 调用都没发生（复核报告 C-02）。截断提示同理，都不能被 summary 吞掉。
+    if (value.status === 'AWAITING_CONFIRMATION') {
+        return [
+            `> ### ${value.warning || '⚠️ 高危操作拦截警告'}`,
+            `> - **影响评估**: ${value.impact || '该操作将改变远端仓库状态。'}`,
+            `> - **确认指引**: ${value.requiredAction || '如确认继续，请向用户核实并在参数中附加 `confirm: true` 重新调用。'}`,
+            '> - **副作用**: 已拦截，零 gh 调用。',
+        ].join('\n');
+    }
+    const summary = typeof value.summary === 'string' ? value.summary : '';
+    if (summary)
+        lines.push(summary);
+    else
+        lines.push(`### ${action || 'task'} 完成`);
+    // 裁剪必须显眼：这是「不要相信你看到的全部」的唯一提示
+    const t = value.truncated;
+    if (t && typeof t === 'object') {
+        lines.push(`\n> ⚠️ 已裁剪字段：${Array.isArray(t.fields) ? t.fields.join('、') : '-'}（${t.reason || '超出预算'}）` +
+            (t.totalUnknown ? '\n> ⚠️ 被裁部分连**总数都未知**，不要据此判断「就这些」。' : ''));
+    }
+    const facts = value.facts && typeof value.facts === 'object' ? value.facts : null;
+    if (facts) {
+        lines.push('\n**关键事实**');
+        if (facts.sha)
+            lines.push(`- 审查锚点: \`${facts.sha}\``);
+        if (facts.changedFiles !== undefined) {
+            lines.push(`- 变动文件: ${facts.files?.length ?? 0} / ${facts.changedFiles}` +
+                (facts.filesTruncated ? '（清单被 gh 的 100 条上限截断）' : ''));
+        }
+        if (facts.checks && typeof facts.checks === 'object') {
+            const c = facts.checks;
+            lines.push(`- CI: ✅ ${c.pass ?? 0} / ❌ ${c.fail ?? 0} / ⏳ ${c.pending ?? 0}${c.skipped ? ` / ⏭ ${c.skipped}` : ''}`);
+        }
+        if (Array.isArray(facts.files) && facts.files.length > 0) {
+            lines.push('- 已附 diff 的文件:');
+            for (const f of facts.files.slice(0, 12)) {
+                lines.push(`  - \`${f.path}\` (+${f.additions ?? 0}/-${f.deletions ?? 0})${f.patch ? '' : ' — 仅元信息'}`);
+            }
+            if (facts.files.length > 12)
+                lines.push(`  - …另有 ${facts.files.length - 12} 个`);
+        }
+        /*
+         * diff 正文必须渲染出来。
+         *
+         * 为什么：`review_pr` 的全部价值就是「让模型看到改动」——只列文件名等于给了目录
+         * 不给内容，模型还得再调一次 github_pr(diff) 才能审。预算在服务端已经算过，
+         * 这里原样铺开即可（超出预算的文件本来就不带 patch）。
+         */
+        const withPatch = Array.isArray(facts.files) ? facts.files.filter((f) => typeof f.patch === 'string' && f.patch) : [];
+        for (const f of withPatch) {
+            lines.push(`\n#### \`${f.path}\` (+${f.additions ?? 0}/-${f.deletions ?? 0})\n\`\`\`diff\n${f.patch}\n\`\`\``);
+        }
+        if (facts.rules && Array.isArray(facts.rules.sources) && facts.rules.sources.length > 0) {
+            lines.push(`- 仓库审查规则: ${facts.rules.sources.map((s) => `\`${s.path}\``).join('、')}`);
+        }
+        if (Array.isArray(facts.failedJobs) && facts.failedJobs.length > 0) {
+            lines.push('- 失败任务:');
+            for (const j of facts.failedJobs.slice(0, 8)) {
+                lines.push(`  - ${j.name}${j.conclusion ? ` (${j.conclusion})` : ''}${Array.isArray(j.steps) && j.steps.length ? ` — ${j.steps.join(' / ')}` : ''}`);
+            }
+        }
+        if (Array.isArray(facts.excerpts) && facts.excerpts.length > 0) {
+            lines.push('- 失败锚点:');
+            for (const e of facts.excerpts.slice(0, 8)) {
+                lines.push(`  - \`${e.file}:${e.line}\` ${brief(e.message, 160)}`);
+            }
+        }
+        if (Array.isArray(facts.suspectedFiles) && facts.suspectedFiles.length > 0) {
+            lines.push(`- 疑似相关文件: ${facts.suspectedFiles.slice(0, 8).map((f) => `\`${f}\``).join('、')}`);
+        }
+        if (facts.suggestedVersion) {
+            lines.push(`- 建议版本: **v${facts.suggestedVersion}**（${facts.bumpReason || ''}）`);
+        }
+        if (facts.groups && typeof facts.groups === 'object') {
+            const g = facts.groups;
+            lines.push(`- 提交归类: feat ${g.feat?.length ?? 0} / fix ${g.fix?.length ?? 0} / perf ${g.perf?.length ?? 0} / breaking ${g.breaking?.length ?? 0} / other ${(g.other?.length ?? 0) + (g.refactor?.length ?? 0) + (g.docs?.length ?? 0)}`);
+        }
+        if (typeof facts.notes === 'string' && facts.notes.trim()) {
+            // Release notes 草稿是 prepare_release 的主产物，必须直接可见（而不是藏在 JSON 里）
+            lines.push('\n**Release notes 草稿**\n```markdown\n' + facts.notes + '\n```');
+        }
+        if (facts.health && typeof facts.health === 'object') {
+            const h = facts.health;
+            lines.push(`- 发版体检: 工作区${h.clean ? '干净' : '**有未提交变更**'} / 同步${h.synced ? '正常' : '**落后远端**'} / CI ${h.ciGreen === true ? '绿' : h.ciGreen === false ? '**红**' : '未知'}`);
+        }
+    }
+    if (Array.isArray(value.nextActions) && value.nextActions.length > 0) {
+        lines.push('\n**建议下一步**');
+        for (const a of value.nextActions)
+            lines.push(`- ${a}`);
+    }
+    const cost = value.cost;
+    if (cost && typeof cost === 'object') {
+        lines.push(`\n> cost: ${cost.chars} 字符 · ${cost.ghCalls} 次 gh 调用 · ${cost.elapsedMs}ms`);
+    }
+    return lines.join('\n') + appendDegradedNote(value);
+}

package/lib/review-rules.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 仓库审查规则（AGENTS.md）与严重度前缀：纯函数模块。
+ *
+ * 为什么单独一个模块：
+ * 1. 规则必须来自**仓库自身**（Codex 的做法），不是插件内置偏好——内置偏好等于
+ *    把作者的品味强加给每个仓库；
+ * 2. 纯函数才能被测试真正覆盖：只有 `readReviewRules` 一处 I/O，截取与归一化全部可单测；
+ * 3. 本文件只被服务端工具层消费（不在 `lib/ui/` 里，不参与客户端 bundle 内联），
+ *    因此可以正常使用 node 内置模块。
+ */
+/** 严重度档位。缺省视为 P2——「没说优先级」不等于「不重要」，但也不该冒充 P0 */
+export type Severity = 'P0' | 'P1' | 'P2';
+/**
+ * 从 Markdown 里截取指定二级标题下的内容。
+ *
+ * 边界规则（这是本函数存在的全部理由）：
+ * - 标题行必须是 `## <title>` 或 `## <title> ...`（大小写不敏感，允许尾随空格）；
+ * - 内容到**下一个同级或更高级标题**（`## ` 或 `# `）为止；
+ * - 代码块里的 `## ` 不算标题（``` 围栏内跳过），否则规则里贴一段 diff 就会截断；
+ * - 找不到标题返回 null（调用方据此判定「该文件没有规则段」）。
+ */
+export declare function extractSection(md: string, title: string): string | null;
+/**
+ * 给审查意见补严重度前缀。
+ *
+ * 为什么「只补不删」：
+ * - 已有 `[P0]/[P1]/[P2]` 原样保留（作者/上游工具的判断优先，插件不覆盖）；
+ * - 缺失才前置 `[P2]`；
+ * - **绝不降级**：`[P0]` 永远不会被改成 `[P2]`。一条审查意见的优先级是写它的人的
+ *   语义判断，插件没有资格改写。
+ *
+ * 幂等：`normalizeSeverity(normalizeSeverity(x)) === normalizeSeverity(x)`。
+ */
+export declare function normalizeSeverity(body: string): string;
+/** 统计一组审查意见的严重度分布（返回给调用方做汇总，不改变内容） */
+export declare function summarizeSeverity(bodies: string[]): Record<Severity, number>;
+/** 一份规则文件（来源路径 + 原文） */
+export interface ReviewRuleSource {
+    /** 相对工作区的路径（`AGENTS.md` 或 `src/ui/AGENTS.md`） */
+    path: string;
+    /** 规则正文（已去掉标题行） */
+    content: string;
+}
+export interface ReviewRulesResult {
+    sources: ReviewRuleSource[];
+    /** 是否因体积上限被裁剪（裁剪本身必须显式，不能静默少给） */
+    truncated: boolean;
+}
+/**
+ * 读取工作区的审查规则。
+ *
+ * 查找顺序：仓库根 `AGENTS.md` → 每个变更文件所在目录就近 `AGENTS.md`（向上回溯，
+ * 去重）。就近规则排在后（越具体越靠后，便于人按顺序读）。
+ *
+ * 全部读不到时返回 `null`——调用方据此**不加** `reviewRules` 字段（而不是给个空对象），
+ * 这样「没规则」与「规则为空」在输出里可区分。
+ */
+export declare function readReviewRules(cwd: string, changedPaths?: string[]): ReviewRulesResult | null;
+/** 把规则渲染成人类与 Agent 都能读的 Markdown 段落（无规则时返回空串） */
+export declare function renderReviewRules(rules: ReviewRulesResult | null): string;

package/lib/review-rules.js

@@ -0,0 +1,204 @@
+/**
+ * 仓库审查规则（AGENTS.md）与严重度前缀：纯函数模块。
+ *
+ * 为什么单独一个模块：
+ * 1. 规则必须来自**仓库自身**（Codex 的做法），不是插件内置偏好——内置偏好等于
+ *    把作者的品味强加给每个仓库；
+ * 2. 纯函数才能被测试真正覆盖：只有 `readReviewRules` 一处 I/O，截取与归一化全部可单测；
+ * 3. 本文件只被服务端工具层消费（不在 `lib/ui/` 里，不参与客户端 bundle 内联），
+ *    因此可以正常使用 node 内置模块。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** 规则文件单个体积上限（字节）。超过即视为「不是给人看的规则」，只取前 8KB */
+const MAX_RULE_FILE_BYTES = 8 * 1024;
+/** 多份规则合计上限（字节） */
+const MAX_RULES_TOTAL_BYTES = 16 * 1024;
+/** 就近查找时向上回溯的目录层数上限，防止在 monorepo 里一路读到根 */
+const MAX_WALK_UP = 6;
+/**
+ * 从 Markdown 里截取指定二级标题下的内容。
+ *
+ * 边界规则（这是本函数存在的全部理由）：
+ * - 标题行必须是 `## <title>` 或 `## <title> ...`（大小写不敏感，允许尾随空格）；
+ * - 内容到**下一个同级或更高级标题**（`## ` 或 `# `）为止；
+ * - 代码块里的 `## ` 不算标题（``` 围栏内跳过），否则规则里贴一段 diff 就会截断；
+ * - 找不到标题返回 null（调用方据此判定「该文件没有规则段」）。
+ */
+export function extractSection(md, title) {
+    if (typeof md !== 'string' || !md)
+        return null;
+    const want = title.trim().toLowerCase();
+    if (!want)
+        return null;
+    const lines = md.split(/\r?\n/);
+    let inFence = false;
+    let start = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^\s*(```|~~~)/.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        if (start < 0) {
+            const m = /^##\s+(.+?)\s*$/.exec(line);
+            if (m && m[1].trim().toLowerCase() === want)
+                start = i + 1;
+            continue;
+        }
+        // 已进入规则段：遇到同级或更高级标题即结束
+        if (/^#{1,2}\s+/.test(line)) {
+            return lines.slice(start, i).join('\n').trim();
+        }
+    }
+    return start < 0 ? null : lines.slice(start).join('\n').trim();
+}
+/**
+ * 给审查意见补严重度前缀。
+ *
+ * 为什么「只补不删」：
+ * - 已有 `[P0]/[P1]/[P2]` 原样保留（作者/上游工具的判断优先，插件不覆盖）；
+ * - 缺失才前置 `[P2]`；
+ * - **绝不降级**：`[P0]` 永远不会被改成 `[P2]`。一条审查意见的优先级是写它的人的
+ *   语义判断，插件没有资格改写。
+ *
+ * 幂等：`normalizeSeverity(normalizeSeverity(x)) === normalizeSeverity(x)`。
+ */
+export function normalizeSeverity(body) {
+    const text = typeof body === 'string' ? body : String(body ?? '');
+    const trimmed = text.trim();
+    if (!trimmed)
+        return trimmed;
+    // 前缀判定必须锚在开头，且允许 `[P1]` 后面直接跟正文（无空格）——实测两种写法都有人用
+    if (/^\[P[012]\]/i.test(trimmed))
+        return trimmed;
+    return `[P2] ${trimmed}`;
+}
+/** 统计一组审查意见的严重度分布（返回给调用方做汇总，不改变内容） */
+export function summarizeSeverity(bodies) {
+    const out = { P0: 0, P1: 0, P2: 0 };
+    for (const b of Array.isArray(bodies) ? bodies : []) {
+        const m = /^\[(P[012])\]/i.exec(String(b ?? '').trim());
+        const key = (m ? m[1].toUpperCase() : 'P2');
+        out[key]++;
+    }
+    return out;
+}
+/**
+ * 从文件内容里取规则段；整文件没有 `## Code Review Rules` 时，退化为整份文件。
+ *
+ * 为什么允许退化：多数 AGENTS.md 就是一篇「该怎么干活」的散装文档，强制要求
+ * 二级标题会让绝大多数仓库一条规则都注入不了——那等于这个功能对多数人不存在。
+ */
+function extractRulesFromFile(md) {
+    const section = extractSection(md, 'Code Review Rules');
+    const text = section !== null ? section : md;
+    const trimmed = text.trim();
+    return trimmed ? trimmed : null;
+}
+/**
+ * 按 UTF-8 字节上限裁剪文本，**保证不切断多字节字符**。
+ *
+ * 为什么不能用 `Buffer.subarray(0, n).toString('utf8')`：那样会在字符中间切断，
+ * 产出 U+FFFD 替换符（中文规则文件 8KB ≈ 2700 字，切在边界上的概率不低）。
+ * 规则要原样注入上下文，出现乱码比少几个字更糟。
+ */
+function truncateToBytes(text, maxBytes) {
+    if (Buffer.byteLength(text, 'utf8') <= maxBytes)
+        return text;
+    let out = '';
+    let used = 0;
+    for (const ch of text) {
+        const size = Buffer.byteLength(ch, 'utf8');
+        if (used + size > maxBytes)
+            break;
+        out += ch;
+        used += size;
+    }
+    return out;
+}
+/**
+ * 读取工作区的审查规则。
+ *
+ * 查找顺序：仓库根 `AGENTS.md` → 每个变更文件所在目录就近 `AGENTS.md`（向上回溯，
+ * 去重）。就近规则排在后（越具体越靠后，便于人按顺序读）。
+ *
+ * 全部读不到时返回 `null`——调用方据此**不加** `reviewRules` 字段（而不是给个空对象），
+ * 这样「没规则」与「规则为空」在输出里可区分。
+ */
+export function readReviewRules(cwd, changedPaths) {
+    if (!cwd || !fs.existsSync(cwd))
+        return null;
+    const candidates = [];
+    const pushCandidate = (rel) => {
+        const normalized = rel.replace(/\\/g, '/');
+        if (normalized && !candidates.includes(normalized))
+            candidates.push(normalized);
+    };
+    pushCandidate('AGENTS.md');
+    for (const p of Array.isArray(changedPaths) ? changedPaths : []) {
+        if (typeof p !== 'string' || !p)
+            continue;
+        let dir = path.dirname(p.replace(/\\/g, '/'));
+        let depth = 0;
+        while (dir && dir !== '.' && dir !== '/' && depth < MAX_WALK_UP) {
+            pushCandidate(`${dir}/AGENTS.md`);
+            const next = path.posix.dirname(dir);
+            if (next === dir)
+                break;
+            dir = next;
+            depth++;
+        }
+    }
+    const sources = [];
+    let total = 0;
+    let truncated = false;
+    for (const rel of candidates) {
+        const abs = path.join(cwd, rel);
+        let stat;
+        try {
+            stat = fs.statSync(abs);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        let raw;
+        try {
+            raw = fs.readFileSync(abs, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (Buffer.byteLength(raw, 'utf8') > MAX_RULE_FILE_BYTES) {
+            raw = truncateToBytes(raw, MAX_RULE_FILE_BYTES);
+            truncated = true;
+        }
+        const content = extractRulesFromFile(raw);
+        if (!content)
+            continue;
+        if (total + Buffer.byteLength(content, 'utf8') > MAX_RULES_TOTAL_BYTES) {
+            truncated = true;
+            break;
+        }
+        total += Buffer.byteLength(content, 'utf8');
+        sources.push({ path: rel, content });
+    }
+    return sources.length > 0 ? { sources, truncated } : null;
+}
+/** 把规则渲染成人类与 Agent 都能读的 Markdown 段落（无规则时返回空串） */
+export function renderReviewRules(rules) {
+    if (!rules || rules.sources.length === 0)
+        return '';
+    const parts = ['\n## 仓库审查规则（AGENTS.md）'];
+    for (const s of rules.sources) {
+        parts.push(`> 源: \`${s.path}\`\n\n${s.content}`);
+    }
+    if (rules.truncated) {
+        parts.push('> ⚠️ 规则文件超出体积上限（单文件 8KB / 合计 16KB），已截断。');
+    }
+    return parts.join('\n\n');
+}

package/lib/shared/state-badges.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 状态 → 徽章的唯一映射（服务端 Markdown 与客户端 UI 共用）。
+ *
+ * 为什么必须共用：同一个状态（OPEN / MERGED / CI failure …）在 CLI 输出与右侧栏
+ * 面板上必须是同一套颜色与同一套文案。此前这条映射在 9 个文件里各写了一遍
+ * （服务端 5 个 `format*Badge`、客户端 6 处内联三元式），新增一个状态要改 12 处，
+ * 漏一处就出现「同一个 PR 在两处显示不同颜色」。
+ *
+ * 约束（构建期强依赖）：本文件必须**零依赖**。scripts/build.mjs 会把它的 import
+ * 行剥掉、整体内联进客户端 bundle；一旦这里 import 了别的东西，那些符号在 bundle
+ * 作用域里就是 undefined，表现是整个驾驶舱白屏。
+ *
+ * `tone` 直接就是 CSS class 后缀（`dsh-badge-${tone}`），客户端不再需要映射表。
+ */
+export type BadgeTone = 'green' | 'purple' | 'red' | 'yellow' | 'neutral';
+export interface StateBadge {
+    /** 前缀 Emoji；服务端 Markdown 用，客户端通常只用 tone+label */
+    icon: string;
+    /** 便于阅读的短标签（大写状态名或小写结论词） */
+    label: string;
+    /** 直接拼进 `dsh-badge-${tone}` 的色调名 */
+    tone: BadgeTone;
+}
+/** 服务端 Markdown 渲染用：`🟢 OPEN` / `OPEN` / `-` */
+export declare function badgeText(badge: StateBadge | null): string;
+/** PR / Issue 状态（空 state 优先于 draft，与旧实现判定顺序一致） */
+export declare function prStateBadge(state?: string, isDraft?: boolean): StateBadge | null;
+/** Issue 状态（没有 MERGED 这一档） */
+export declare function issueStateBadge(state?: string): StateBadge | null;
+/**
+ * CI 状态。
+ * 第二参数按调用域语义不同：run 域传 conclusion（success/failure/…），
+ * pr checks 域传 bucket（pass/fail/pending/…）——取值族不同但映射到同一组徽章；
+ * 第一参数兜底（in_progress/queued 等进行中态）。
+ */
+export declare function ciBadge(status?: string, conclusion?: string): StateBadge | null;
+/** 合并冲突状态 */
+export declare function conflictBadge(status?: string): StateBadge | null;
+/** Release 状态（Draft > Prerelease > Stable） */
+export declare function releaseBadge(isDraft?: boolean, isPrerelease?: boolean): StateBadge;
+/** 兜底：任意状态字符串转徽章（未知状态给 neutral，不猜颜色） */
+export declare function genericStateBadge(state?: string): StateBadge | null;

package/lib/shared/state-badges.js

@@ -0,0 +1,102 @@
+/**
+ * 状态 → 徽章的唯一映射（服务端 Markdown 与客户端 UI 共用）。
+ *
+ * 为什么必须共用：同一个状态（OPEN / MERGED / CI failure …）在 CLI 输出与右侧栏
+ * 面板上必须是同一套颜色与同一套文案。此前这条映射在 9 个文件里各写了一遍
+ * （服务端 5 个 `format*Badge`、客户端 6 处内联三元式），新增一个状态要改 12 处，
+ * 漏一处就出现「同一个 PR 在两处显示不同颜色」。
+ *
+ * 约束（构建期强依赖）：本文件必须**零依赖**。scripts/build.mjs 会把它的 import
+ * 行剥掉、整体内联进客户端 bundle；一旦这里 import 了别的东西，那些符号在 bundle
+ * 作用域里就是 undefined，表现是整个驾驶舱白屏。
+ *
+ * `tone` 直接就是 CSS class 后缀（`dsh-badge-${tone}`），客户端不再需要映射表。
+ */
+/** 服务端 Markdown 渲染用：`🟢 OPEN` / `OPEN` / `-` */
+export function badgeText(badge) {
+    if (!badge)
+        return '-';
+    return badge.icon ? `${badge.icon} ${badge.label}` : badge.label;
+}
+/** PR / Issue 状态（空 state 优先于 draft，与旧实现判定顺序一致） */
+export function prStateBadge(state, isDraft) {
+    const s = String(state || '').toUpperCase();
+    // 旧实现把 `if (!state) return '-'` 放在最前、draft 判定在其后。
+    // 顺序反了会让 formatStateBadge(undefined, true) 从 '-' 变成 '⚪ DRAFT'——那是行为变化。
+    if (!s)
+        return null;
+    if (isDraft)
+        return { icon: '⚪', label: 'DRAFT', tone: 'yellow' };
+    if (s === 'OPEN')
+        return { icon: '🟢', label: 'OPEN', tone: 'green' };
+    if (s === 'MERGED')
+        return { icon: '🟣', label: 'MERGED', tone: 'purple' };
+    if (s === 'CLOSED')
+        return { icon: '🔴', label: 'CLOSED', tone: 'red' };
+    return genericStateBadge(s);
+}
+/** Issue 状态（没有 MERGED 这一档） */
+export function issueStateBadge(state) {
+    const s = String(state || '').toUpperCase();
+    if (s === 'OPEN')
+        return { icon: '🟢', label: 'OPEN', tone: 'green' };
+    if (s === 'CLOSED')
+        return { icon: '🔴', label: 'CLOSED', tone: 'red' };
+    return genericStateBadge(s);
+}
+/**
+ * CI 状态。
+ * 第二参数按调用域语义不同：run 域传 conclusion（success/failure/…），
+ * pr checks 域传 bucket（pass/fail/pending/…）——取值族不同但映射到同一组徽章；
+ * 第一参数兜底（in_progress/queued 等进行中态）。
+ */
+export function ciBadge(status, conclusion) {
+    const conc = String(conclusion || '').toLowerCase();
+    const st = String(status || '').toLowerCase();
+    if (conc === 'success' || conc === 'pass')
+        return { icon: '✅', label: conc, tone: 'green' };
+    if (conc === 'failure' || conc === 'fail')
+        return { icon: '❌', label: conc, tone: 'red' };
+    if (conc === 'cancelled' || conc === 'cancel')
+        return { icon: '🚫', label: conc, tone: 'red' };
+    if (conc === 'skipped' || conc === 'skipping')
+        return { icon: '⏭️', label: conc, tone: 'neutral' };
+    if (conc === 'pending')
+        return { icon: '⏳', label: 'pending', tone: 'yellow' };
+    if (st === 'in_progress')
+        return { icon: '⏳', label: 'running', tone: 'yellow' };
+    if (st === 'queued')
+        return { icon: '⏱️', label: 'queued', tone: 'yellow' };
+    const fallback = conc || st;
+    if (!fallback)
+        return null;
+    return { icon: '', label: fallback, tone: 'neutral' };
+}
+/** 合并冲突状态 */
+export function conflictBadge(status) {
+    const s = String(status || '').toUpperCase();
+    if (s === 'CLEAN')
+        return { icon: '✅', label: 'CLEAN', tone: 'green' };
+    if (s === 'DIRTY' || s === 'CONFLICT')
+        return { icon: '⚠️', label: 'CONFLICT', tone: 'yellow' };
+    if (s === 'BLOCKED')
+        return { icon: '⛔', label: 'BLOCKED', tone: 'red' };
+    if (!s)
+        return null;
+    return { icon: '', label: s, tone: 'neutral' };
+}
+/** Release 状态（Draft > Prerelease > Stable） */
+export function releaseBadge(isDraft, isPrerelease) {
+    if (isDraft)
+        return { icon: '⚪', label: 'DRAFT', tone: 'yellow' };
+    if (isPrerelease)
+        return { icon: '🍼', label: 'PRE', tone: 'yellow' };
+    return { icon: '✅', label: 'STABLE', tone: 'green' };
+}
+/** 兜底：任意状态字符串转徽章（未知状态给 neutral，不猜颜色） */
+export function genericStateBadge(state) {
+    const s = String(state || '').toUpperCase();
+    if (!s)
+        return null;
+    return { icon: '', label: s, tone: 'neutral' };
+}

package/lib/task-primitives.d.ts

@@ -0,0 +1,109 @@
+/**
+ * 任务级原语的纯函数层：提交归类、SemVer 推导、预算裁剪、信封封装。
+ *
+ * 为什么单独成文件：
+ * 1. 这三个原语的价值是「一轮拿到可执行结论」，结论对不对完全取决于归类与裁剪
+ *    这些纯逻辑——它们必须能脱离网络单测，否则只能靠"跑一次看看"验证；
+ * 2. `cost` 是原语存在的唯一判据（是否真的比手动串步骤省钱），必须由代码计算，
+ *    不能手写常量；
+ * 3. 工具层只负责取数与编排，不承载判定规则。
+ */
+/** 任务原语的统一返回信封（见 s8 §2.1） */
+export interface TaskEnvelope<T> {
+    /** 一段人类可读的结论，≤1.5KB */
+    summary: string;
+    /** 结构化事实（字段受控） */
+    facts: T;
+    /** 任何裁剪都必须显式 */
+    truncated?: {
+        fields: string[];
+        reason: string;
+        /** 被裁掉的部分是否连总数都未知（true = 不要相信「就这些」） */
+        totalUnknown: boolean;
+    };
+    /** 建议的下一步（可执行的具体调用） */
+    nextActions: string[];
+    /** 审计三元组：让每次调用都能被事后核对 */
+    cost: {
+        chars: number;
+        ghCalls: number;
+        elapsedMs: number;
+    };
+}
+/** Conventional Commits 归类结果 */
+export interface CommitGroups {
+    breaking: string[];
+    feat: string[];
+    fix: string[];
+    perf: string[];
+    refactor: string[];
+    docs: string[];
+    other: string[];
+}
+/**
+ * 按 Conventional Commits 归类提交标题。
+ *
+ * 判定优先级：`!` 破坏性标记 > 类型关键字。为什么先判 `!`：
+ * `feat(api)!: drop v1` 既是 feat 也是 breaking，而它决定的是 **major** 版本，
+ * 归到 feat 会让版本号少跳一级——这是发版事故里最常见的一种。
+ */
+export declare function classifyCommits(subjects: string[], bodies?: string[]): CommitGroups;
+/** 解析 `v1.2.3` / `1.2.3` / `v1.2.3-rc.1` 形式的版本号 */
+export declare function parseSemver(tag: string | null | undefined): {
+    major: number;
+    minor: number;
+    patch: number;
+} | null;
+export type BumpKind = 'auto' | 'patch' | 'minor' | 'major';
+/**
+ * 推导下一个版本号。
+ *
+ * 无 tag 时按 `0.1.0` 起步（而不是 1.0.0）：新仓库的第一个版本不该被当成稳定 API。
+ * `auto` 的判据：breaking → major，feat → minor，其余 → patch。
+ */
+export declare function suggestVersion(currentTag: string | null, groups: CommitGroups, bump?: BumpKind): {
+    version: string;
+    bump: Exclude<BumpKind, 'auto'>;
+    reason: string;
+};
+/** 待裁剪的文件条目（patch 为可选 diff 正文） */
+export interface BudgetFile {
+    path: string;
+    additions: number;
+    deletions: number;
+    patch?: string;
+}
+/**
+ * 按字符预算挑选文件，保证「送进上下文的东西一定装得下」。
+ *
+ * 三条约束：
+ * 1. **按变更量降序**取——大改动更可能是问题的所在，小改动先丢；
+ * 2. 单个文件即使超预算也不硬塞（否则一个超大 diff 会把预算吃光，剩下的文件
+ *    一个都看不到）。超预算的文件只保留 path/增删行数，patch 留空并计入 omitted；
+ * 3. **条目数也要封顶**：60 个文件的元信息本身就有 3–4K 字符，只约束 patch 大小
+ *    等于把「固定开销」排除在预算之外（实测整包因此超预算 4.8K）。超出条目上限的
+ *    文件连元信息都不列，只计入 omitted。
+ */
+export declare function selectFilesByBudget(files: BudgetFile[], budgetChars: number, maxEntries?: number): {
+    selected: BudgetFile[];
+    omitted: number;
+    chars: number;
+};
+/**
+ * 封装信封并计算 `cost.chars`。
+ *
+ * `chars` 的口径是**最终返回给模型的那份 JSON 的字符数**（不含 cost 自身，
+ * 否则会自指）。这样「原语是否省钱」才有可比的数字。
+ */
+export declare function finalizeEnvelope<T>(summary: string, facts: T, nextActions: string[], meta: {
+    ghCalls: number;
+    elapsedMs: number;
+    truncated?: TaskEnvelope<T>['truncated'];
+}): TaskEnvelope<T>;
+/** 从日志片段里抽取 `path:line` 形态的定位锚点（供 diagnose_ci 汇总疑似文件） */
+export declare function extractFileAnchors(text: string): Array<{
+    file: string;
+    line: number;
+}>;
+/** 把归类结果渲染成 Release notes 草稿（按类型分组，breaking 置顶） */
+export declare function renderReleaseNotes(version: string, groups: CommitGroups): string;