@longzai-intelligence-issues/ledger 0.0.1

package/src/prompts/prompts.commands.ts

@@ -0,0 +1,211 @@
+/**
+ * 推荐提示词（内置两模板 + extraDir 自定义加载）
+ *
+ * apex 两工作流提示词的泛化迁移：watch 域特有内容替换为 config 驱动的 scope
+ * 判定与 lzi-issues 命令面。CLI `prompts list / show` 消费；不动 MCP。
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * 提示词列举/展示选项
+ */
+export type PromptsOptions = {
+  /**
+   * 是否包含内置模板（默认 true）
+   */
+  builtin?: boolean;
+
+  /**
+   * 自定义模板目录绝对路径
+   */
+  extraDir?: string;
+};
+
+/**
+ * 提示词条目
+ */
+export type PromptEntry = {
+  /**
+   * 提示词 id（kebab-case）
+   */
+  id: string;
+
+  /**
+   * 一句话描述
+   */
+  description: string;
+
+  /**
+   * 正文全文（markdown）
+   */
+  content: string;
+
+  /**
+   * 来源（builtin / extra）
+   */
+  source: 'builtin' | 'extra';
+};
+
+/**
+ * 内置提示词：登记 + 治理全流程
+ */
+const ISSUE_CREATE_AND_PROCESS = `# issue-create-and-process：登记新问题并完成治理
+
+## 命令定位
+
+输入：问题原文（用户观察/描述的现象、报错、异常）。**问题原文必须逐字保留进 issue 文档，禁止转述改写**；调用未附带问题原文时立即停止并说明缺少原文。输入是既有 issue 引用时改走 issue-process，本命令不重复登记。
+
+两个职责顺序执行：**登记**（范围判定→查重→门禁取号→落盘骨架）→**治理**（核实→修复→测试→记账→回填）。
+
+## 一、登记
+
+- **范围判定先于建档**：按 lzi-issues.config.ts 的 scopes（paths 覆盖面）判定问题归属——跨项目/全局问题落全局 scope 注册表，项目/包专属问题落对应 scope；判定不了时列出全部 scope 请用户裁定。
+- **查重先于建档**：在目标注册表目录检索主题关键词、现象特征、涉及文件名；已存在同语义 issue 时走既有更新路径（回填现象与证据），禁止重复建档。
+- **门禁取号**：\`lzi-issues create --title <标题> --scope <key>\`（编号写入时刻确定，目录即编号命名空间）；落盘后跑 \`lzi-issues numbering check --dir <注册表目录>\` 自检。禁止手工定号。
+- 骨架即标准模板（\`lzi-issues template\`），正文四段：问题动机（原文逐字+客观证据）→现状与证据→处置方向（【1】备选方案和分析【2】推荐方案和分析）→处置结果/验证口径。
+
+## 二、治理
+
+- **证据先行**：现象在当前代码上复现或查证后才写入；根因经检索/调试/最小复现确认后才落盘；无法确认的如实标注「根因待治理时核实」。已被并行治理修复的，证据确认后归属写入并收口，不做重复修复。
+- **处理原则**：长期治理、最大工作量、最佳实践——按根因根治与体系化改进取舍，不选「恰好让报错消失」的最小改动。
+- **裁决门槛**：能自决的技术方案直接决定并执行；规格语义裁决、产品行为取舍、推翻既有裁决等重大分歧**停下**，正文提供【1】问题动机/背景【2】备选方案和分析【3】推荐方案和分析，等用户裁决。
+- **TDD**：先写复现/定义预期的失败测试（Red），再实现（Green）、重构（Refactor）。
+- **测试最小范围**：只运行与本次改动相关的测试文件；三层覆盖缺失则补齐。
+- **CHANGELOG**：变更落定即时 \`bun run changelog:add -- --added|--changed|--fixed "描述" --package <pkg>\`；纯文档/注释变更不入账。
+- **边界治理**：同类问题排查（rg 受影响链路）；命中不在本期边界的、治理中新暴露的遗留——按范围**单独建档**（同样走门禁取号），禁止混入本 issue；本 issue「处置结果/验证口径」逐条写明去向。
+- **单载体回填**：发现、决策、处置过程全部回填 issue 文档自身（状态行实时更新），禁止外写专题 records/findings。
+- **收口**：判据全绿后 \`lzi-issues verify-close --issue <文档>\`（缺省零执行证据收口；确须真跑加 --rerun，重度命令须 --confirm-heavy，仅人类明令）。
+- **git 全程只读**：仅 status/diff/log/show 服务于本任务；非本任务产出的文件不动。
+
+## 收尾
+
+状态行终态化（🟢 已处置 或如实保持 🔴/🟡 并写明原因）；处置结果/验证口径回填检查清单、测试结果、遗留去向；全部变更留工作区由用户审阅提交。`;
+
+/**
+ * 内置提示词：既有 issue 治理
+ */
+const ISSUE_PROCESS = `# issue-process：治理既有 issue
+
+## 命令定位
+
+输入：issue 引用（完整 NNNN-slug / 纯编号 / 不完整 slug 前缀）。**引用必须唯一定位**——编号命中不唯一（历史撞号）时停止并列出候选（含 scope 与完整 slug），要求重新指定；未指定 issue 时立即停止，禁止自行挑选。
+
+三个阶段：**读题核实**→**治理落地**→**回填归档**。
+
+## 一、读题核实
+
+- **终态拦截**：状态行已 🟢 的默认不处理（复审须明确要求）；⚪ 已冻结的先停下（解冻须「用户裁定」）。
+- **开工标注**：确认处理对象后状态行更新为 🟡 处理中（括注挂起原因）。
+- **现状优先于记载**：issue 是写入时刻快照——现象、根因、涉及文件逐项在当前代码上核实；漂移时先如实修订记载再治理；已被并行治理修复的，证据确认后归属写入并收口，不重复修复。
+
+## 二、治理落地
+
+- 处理原则、裁决门槛、TDD、测试最小范围、CHANGELOG、边界治理、单载体回填纪律与 issue-create-and-process 完全一致。
+- 治理中发现原方案实现层缺陷：有实证时把证据与修正方案记入「处置结果/验证口径」后继续；需变更已裁决规格语义时停下等用户裁定。
+
+## 三、回填归档
+
+- 状态行终态化；「处置结果/验证口径」记裁决内容（含否决备选与理由）、落地清单、检查与测试结果、遗留去向。
+- 落地形态与登记时不一致或根因被修正：证据与修正理由写进正文，保留排查链路，禁止静默偏离。
+- 收口走 \`lzi-issues verify-close\`（判据块 + 证据锚点；阻塞引用未全 🟢 会被门禁拒收）。`;
+
+/**
+ * 内置提示词全集
+ */
+const BUILTIN_PROMPTS: readonly PromptEntry[] = [
+  {
+    id: 'issue-create-and-process',
+    description:
+      '登记新问题到注册表并完成治理：范围判定、查重、门禁取号、证据先行、裁决门槛、TDD、单载体回填、verify-close 收口',
+    content: ISSUE_CREATE_AND_PROCESS,
+    source: 'builtin',
+  },
+  {
+    id: 'issue-process',
+    description:
+      '治理既有 issue：引用唯一定位消歧、终态拦截、现状核实、治理与回填、verify-close 收口',
+    content: ISSUE_PROCESS,
+    source: 'builtin',
+  },
+];
+
+/**
+ * 加载 extraDir 自定义提示词（frontmatter name/description + 正文）
+ *
+ * @param extraDir - 自定义模板目录绝对路径
+ * @returns 提示词条目列表（目录缺席为空列表）
+ */
+function loadExtraPrompts(extraDir: string): PromptEntry[] {
+  if (!existsSync(extraDir)) {
+    return [];
+  }
+
+  return readdirSync(extraDir)
+    .filter((file) => file.endsWith('.md'))
+    .map((file) => {
+      /**
+       * 模板全文
+       */
+      const raw = readFileSync(join(extraDir, file), 'utf8');
+
+      /**
+       * frontmatter 提取
+       */
+      const nameMatch = /^name:\s*(.+)$/m.exec(raw);
+
+      /**
+       * description 提取命中
+       */
+      const descMatch = /^description:\s*(.+)$/m.exec(raw);
+
+      return {
+        id: nameMatch?.[1]?.trim() ?? file.replace(/\.md$/, ''),
+        description: descMatch?.[1]?.trim() ?? '',
+        content: raw,
+        source: 'extra',
+      };
+    });
+}
+
+/**
+ * 列出全部提示词（内置 + extra；builtin 关闭时仅 extra）
+ *
+ * @param options - 列举选项
+ * @param options.builtin - 是否包含内置（默认 true）
+ * @param options.extraDir - 自定义模板目录
+ * @returns 提示词条目列表（id 去重，extra 覆盖同 id 内置）
+ */
+export function listPrompts(options: PromptsOptions): PromptEntry[] {
+  /**
+   * 汇总收集器
+   */
+  const collected: PromptEntry[] = [];
+
+  if (options.builtin !== false) {
+    collected.push(...BUILTIN_PROMPTS);
+  }
+
+  if (options.extraDir !== undefined) {
+    collected.push(...loadExtraPrompts(options.extraDir));
+  }
+
+  /**
+   * id 去重（后者覆盖前者——extra 优先）
+   */
+  const byId = new Map(collected.map((entry) => [entry.id, entry]));
+
+  return [...byId.values()];
+}
+
+/**
+ * 展示单个提示词
+ *
+ * @param id - 提示词 id
+ * @param options - 列举选项（与 listPrompts 一致）
+ * @returns 提示词条目；未命中为 null
+ */
+export function showPrompt(id: string, options: PromptsOptions): PromptEntry | null {
+  return listPrompts(options).find((entry) => entry.id === id) ?? null;
+}

package/src/template/issue-template.renderer.ts

@@ -0,0 +1,351 @@
+/**
+ * issue 标准模板渲染器（唯一真源）
+ *
+ * 标准格式三路共用本渲染器：template 命令（skeleton 骨架展示）、create 建档
+ * （instance 实际值骨架）、init 注册表 README 存根。正文四段占位文本以常量形态
+ * 由两种模式共享，结构漂移在构造上不可能发生；指南活样板与骨架的逐字一致由
+ * guide-fixture 测试守卫（零漂移五环之一）。
+ */
+
+import {
+  BLOCKING_LINE_KEY,
+  CANONICAL_STATUS_LABELS,
+  HISTORY_LINE_KEY,
+} from '@/parser/format.utils';
+
+/**
+ * issue 优先级（模板口径）
+ */
+export type IssueTemplatePriority = 'P1' | 'P2' | 'P3';
+
+/**
+ * 模板引用形态（沿革 / 阻塞行的引用条目）
+ */
+export type IssueTemplateRef = {
+  /**
+   * 引用编号（3-4 位零填充）
+   */
+  number: string;
+
+  /**
+   * 引用完整 slug（缺席时渲染为纯编号引用）
+   */
+  slug?: string;
+};
+
+/**
+ * instance 模式渲染入参
+ */
+export type IssueTemplateValues = {
+  /**
+   * 编号（4 位零填充，编号门禁取号分配）
+   */
+  number: string;
+
+  /**
+   * slug（kebab-case，默认禁数字）
+   */
+  slug: string;
+
+  /**
+   * 一句话标题（问题是什么，禁笼统词）
+   */
+  title: string;
+
+  /**
+   * 优先级
+   */
+  priority: IssueTemplatePriority;
+
+  /**
+   * 所属域（config 登记的 scope title）
+   */
+  scopeTitle: string;
+
+  /**
+   * 立案日期（YYYY-MM-DD）
+   */
+  date: string;
+
+  /**
+   * 来源（问题原文出处 + 日期）
+   */
+  source: string;
+
+  /**
+   * 沿革引用（缺席时省略沿革行）
+   */
+  historyRefs?: IssueTemplateRef[];
+
+  /**
+   * 阻塞引用（缺席时省略阻塞行；全部 🟢 后方可收口）
+   */
+  blockedByRefs?: IssueTemplateRef[];
+};
+
+/**
+ * 正文段「一、问题动机」模板（两模式共享）
+ */
+const MOTIVATION_SECTION = [
+  '## 一、问题动机',
+  '',
+  '> <问题原文逐字记录，禁止转述改写>',
+  '',
+  '客观证据（报错/复现步骤/涉及文件/日志路径）：',
+  '- <证据>',
+  '',
+].join('\n');
+
+/**
+ * 正文段「二、现状与证据」模板（两模式共享）
+ */
+const CURRENT_STATE_SECTION = [
+  '## 二、现状与证据',
+  '',
+  '<排查链路与实证；无法确认根因时如实标注「根因待治理时核实」>',
+  '',
+].join('\n');
+
+/**
+ * 正文段「三、处置方向」模板（两模式共享）
+ */
+const DIRECTION_SECTION = [
+  '## 三、处置方向',
+  '',
+  '【1】备选方案和分析',
+  '- <备选>：<分析>',
+  '',
+  '【2】推荐方案和分析',
+  '- <推荐>：<分析；能自决的直接执行，裁决类停下等用户裁定>',
+  '',
+].join('\n');
+
+/**
+ * 正文段「四、处置结果/验证口径」模板（两模式共享）
+ */
+const DISPOSITION_SECTION = [
+  '## 四、处置结果/验证口径',
+  '',
+  '<随治理进展回填；判据以 criteria 围栏块声明；收口由 verify-close 回填证据锚点>',
+  '',
+].join('\n');
+
+/**
+ * 渲染引用行内容
+ *
+ * 有 slug 渲染为 markdown 相对链接（`[0035](./0035-slug.md)`），无 slug 渲染为
+ * 纯编号引用（`[0035]`）；多条引用以「；」连接。
+ *
+ * @param refs - 引用列表
+ * @returns 引用行内容文本
+ */
+function renderRefList(refs: IssueTemplateRef[]): string {
+  /**
+   * 单条引用渲染结果列表
+   */
+  const rendered = refs.map((ref) =>
+    ref.slug ? `[${ref.number}](./${ref.number}-${ref.slug}.md)` : `[${ref.number}]`,
+  );
+
+  return rendered.join('；');
+}
+
+/**
+ * 渲染标准模板骨架（skeleton 模式）
+ *
+ * 占位符形态，供 template 命令展示与指南活样板消费。
+ *
+ * @returns 骨架全文（以单个换行结尾）
+ */
+export function renderIssueTemplateSkeleton(): string {
+  return [
+    '# <NNNN> - <一句话标题：问题是什么，禁笼统词>',
+    '',
+    '**优先级**: <P1|P2|P3>',
+    `**状态**: ${CANONICAL_STATUS_LABELS.red}`,
+    '**立案日期**: <YYYY-MM-DD>',
+    '**所属域**: <scope title>',
+    '**来源**: <问题原文出处（用户裁定/会话记录/自动巡检 + 日期）>',
+    '**沿革**: <可选：前序 issue 引用，如 [0035](./0035-<slug>.md)>',
+    '**阻塞**: <可选：被阻塞于哪些 issue；全部 🟢 后方可收口>',
+    '',
+    MOTIVATION_SECTION,
+    CURRENT_STATE_SECTION,
+    DIRECTION_SECTION,
+    DISPOSITION_SECTION,
+  ].join('\n');
+}
+
+/**
+ * 渲染标准模板实例（instance 模式）
+ *
+ * 头部元信息代入实际值；沿革 / 阻塞行按入参省略或渲染；正文四段保留占位指导
+ * 文本（建档即骨架，内容随治理进展回填——apex 同款语义）。
+ *
+ * @param values - 实际值入参
+ * @returns 可直接落盘的 issue 文档全文（以单个换行结尾）
+ */
+export function renderIssueTemplate(values: IssueTemplateValues): string {
+  /**
+   * 头部元信息行列表
+   */
+  const headerLines: string[] = [
+    `# ${values.number} - ${values.title}`,
+    '',
+    `**优先级**: ${values.priority}`,
+    `**状态**: ${CANONICAL_STATUS_LABELS.red}`,
+    `**立案日期**: ${values.date}`,
+    `**所属域**: ${values.scopeTitle}`,
+    `**来源**: ${values.source}`,
+  ];
+
+  if (values.historyRefs !== undefined && values.historyRefs.length > 0) {
+    headerLines.push(`**${HISTORY_LINE_KEY}**: ${renderRefList(values.historyRefs)}`);
+  }
+
+  if (values.blockedByRefs !== undefined && values.blockedByRefs.length > 0) {
+    headerLines.push(`**${BLOCKING_LINE_KEY}**: ${renderRefList(values.blockedByRefs)}`);
+  }
+
+  headerLines.push('');
+
+  return [
+    headerLines.join('\n'),
+    MOTIVATION_SECTION,
+    CURRENT_STATE_SECTION,
+    DIRECTION_SECTION,
+    DISPOSITION_SECTION,
+  ].join('\n');
+}
+
+/**
+ * 渲染 criteria 判据块示例（template --with-criteria 附带）
+ *
+ * 示例本身为解析器合法形态（照抄即通过机检），字段说明以 `#` 注释行承载。
+ *
+ * @returns 判据块示例全文
+ */
+export function renderCriteriaBlockExample(): string {
+  return [
+    '```criteria',
+    '# 一行一判据：label|channel|cwd|command（四段竖线分隔，段内禁竖线）',
+    '# channel 限字母数字起首的 [A-Za-z0-9._-]；cwd 相对仓库根；command 为退出码即判据的自动化命令',
+    '# summary 行唯一且非空——真跑收口 --criteria-from-issue 的机器可读载体',
+    'summary: 示例：单包测试全绿',
+    '单包测试|test|packages/demo|bun run test',
+    '```',
+    '',
+  ].join('\n');
+}
+
+/**
+ * 渲染注册表 README 格式存根（init 命令落盘）
+ *
+ * 一页式格式速览：建档入口、状态行五态、正文四段；完整规范指向格式真源指南。
+ *
+ * @param scopeTitle - scope 人类可读名
+ * @param guideRelPath - 格式指南相对本注册表目录的路径（如 `../../docs/guides/issue-file-format.md`）
+ * @returns README 存根全文
+ */
+export function renderRegistryReadmeStub(scopeTitle: string, guideRelPath: string): string {
+  return [
+    `# ${scopeTitle} issue 注册表`,
+    '',
+    '本目录是 lzi-issues 注册表（`NNNN-<slug>.md`，目录即编号命名空间，编号独立序列）。',
+    '',
+    '## 建档',
+    '',
+    '- `lzi-issues create --title <标题> --scope <key>`（编号走门禁取号，禁止手工定号）',
+    '- 标准模板：`lzi-issues template`；完整格式规范：[issue-file-format](' + guideRelPath + ')',
+    '',
+    '## 状态行（处理情况第一入口）',
+    '',
+    `- ${CANONICAL_STATUS_LABELS.red}：待处理`,
+    `- ${CANONICAL_STATUS_LABELS.yellow}（须括注 ≥4 字挂起原因）`,
+    `- ${CANONICAL_STATUS_LABELS.green}（须处置段 + 证据锚点；收口走 \`lzi-issues verify-close\`）`,
+    `- ${CANONICAL_STATUS_LABELS.frozen}（仅经 \`lzi-issues freeze\`，理由须含「用户裁定」）`,
+    `- ${CANONICAL_STATUS_LABELS.canceled}（须括注取消原因）`,
+    '',
+    '## 正文四段',
+    '',
+    '一、问题动机 → 二、现状与证据 → 三、处置方向（【1】备选方案和分析 / 【2】推荐方案和分析）→ 四、处置结果/验证口径',
+    '',
+  ].join('\n');
+}
+
+/**
+ * 模板字段说明条目（template --format json 载荷）
+ */
+export type TemplateFieldDoc = {
+  /**
+   * 字段名（渲染入参名或元信息键）
+   */
+  name: string;
+
+  /**
+   * 是否必填
+   */
+  required: boolean;
+
+  /**
+   * 字段说明
+   */
+  description: string;
+};
+
+/**
+ * 标准模板字段说明全集（供 agent / 使用者程序化消费）
+ */
+export const TEMPLATE_FIELDS: readonly TemplateFieldDoc[] = [
+  {
+    name: 'number',
+    required: true,
+    description: 'scope 内编号，4 位零填充，由编号门禁取号分配（写入时刻确定）',
+  },
+  {
+    name: 'slug',
+    required: true,
+    description:
+      'ASCII kebab slug（小写字母/数字/连字符，禁中文），slug 段默认禁数字（slugDigitPolicy）',
+  },
+  {
+    name: 'title',
+    required: true,
+    description: '一句话标题：问题是什么，禁笼统词',
+  },
+  {
+    name: 'priority',
+    required: true,
+    description: '优先级，P1 | P2 | P3',
+  },
+  {
+    name: 'status',
+    required: true,
+    description: '状态行五态；建档固定 🔴 待处理，流转走工具（verify-close / freeze 等）',
+  },
+  {
+    name: '立案日期',
+    required: true,
+    description: 'YYYY-MM-DD',
+  },
+  {
+    name: '所属域',
+    required: true,
+    description: 'config 登记的 scope title',
+  },
+  {
+    name: '来源',
+    required: true,
+    description: '问题原文出处（用户裁定 / 会话记录 / 自动巡检 + 日期）',
+  },
+  {
+    name: '沿革',
+    required: false,
+    description: '前序 issue 引用，markdown 相对链接或纯编号形态',
+  },
+  {
+    name: '阻塞',
+    required: false,
+    description: '被阻塞于哪些 issue；全部 🟢 后方可收口（blockingMustBeGreen 门禁）',
+  },
+] as const;

package/src/triage/triage.classify.ts

@@ -0,0 +1,93 @@
+/**
+ * 黄灯分诊分类（B > C > A 优先级，全文关键词扫描）
+ *
+ * B = 判据依赖环境（真机 / 合作方 / 人工确认等）→ 诚实保持黄灯；
+ * C = 被并行在途线阻断（在途 / 并行线 / 待补跑等）→ 待落地后复跑；
+ * A = 判据全部机器可跑 → verify-close 补跑收口。
+ */
+
+import type { IssueDocRecord } from '@/parser/registry.parser';
+
+/**
+ * 分诊类别
+ */
+export type TriageCategory = 'A' | 'B' | 'C';
+
+/**
+ * 分诊结果
+ */
+export type TriageClassification = {
+  /**
+   * 类别
+   */
+  category: TriageCategory;
+
+  /**
+   * 分类依据（中文说明）
+   */
+  reason: string;
+};
+
+/**
+ * B 类关键词（环境依赖）
+ */
+const CATEGORY_B_KEYWORDS = [
+  '真机',
+  '雪场',
+  '合作方',
+  '回执',
+  '技术支持',
+  'REAL_DEVICE',
+  '人工确认',
+  '环境不具备',
+];
+
+/**
+ * C 类关键词（并行在途）
+ */
+const CATEGORY_C_KEYWORDS = ['在途', '并行线', '待并行', '让锁', '待落地', '待补跑', '待复跑'];
+
+/**
+ * 黄灯分诊分类
+ *
+ * @param record - 解析产物
+ * @returns 分诊结果
+ */
+export function classifyIssue(record: IssueDocRecord): TriageClassification {
+  /**
+   * B 类命中关键词
+   */
+  const bHit = CATEGORY_B_KEYWORDS.find((keyword) => record.rawContent.includes(keyword));
+
+  if (bHit !== undefined) {
+    return {
+      category: 'B',
+      reason: `判据依赖环境（命中「${bHit}」）——诚实保持黄灯，环境具备后再收口`,
+    };
+  }
+
+  /**
+   * C 类命中关键词
+   */
+  const cHit = CATEGORY_C_KEYWORDS.find((keyword) => record.rawContent.includes(keyword));
+
+  if (cHit !== undefined) {
+    return {
+      category: 'C',
+      reason: `被并行在途线阻断（命中「${cHit}」）——待在途线落地后复跑收口`,
+    };
+  }
+
+  /**
+   * 判据命令数（0 条提示补录）
+   */
+  const criteriaCount = record.criteria?.criteria.length ?? 0;
+
+  return {
+    category: 'A',
+    reason:
+      criteriaCount > 0
+        ? `判据全部机器可跑（${criteriaCount} 条）——verify-close 补跑收口`
+        : '判据清单为空，需人工核对后补录 criteria 块再收口',
+  };
+}