@niujiajie/freespec 0.0.0-stage → 1.15.0

package/skill-files//350/256/276/350/256/241/references//347/225/214/351/235/242.md

@@ -0,0 +1,18 @@
+# 有页面时的前端页面原型设计
+
+没有页面就不要写这一章。
+
+哪些页要单写一节，只按护栏里的「改到的页面」。不要凭页面看起来变没变来取舍。这一章放在哪、章号怎么排，只按 `references/类型.md`。
+
+每一页按这个顺序。框线简图留在表外。选项、规则、对应接口没有内容的那张表整张删掉，不要留空表。
+
+1. 谁从哪个菜单进入、哪几步、哪步可跳过。
+2. 模板里的「本页改动」表。
+3. ASCII 简图。用文本框线，标出这次的区域、字段、按钮、操作区。
+4. 选项表：控件、选项文案、存库的码。枚举挂在这一页下面。
+5. 规则表：编号、规则。
+6. 接口表：操作、方法、路径。查询用问号参数。纯前端调用已有接口时，也写在这张表里。
+
+页面长什么样以这一章为准。需求功能点里的草图只说明有哪些块。两处不一致时，先停下来问，不要各写各的。
+
+路由和前端文件写在变更方案的改动清单里，不要在这一章再抄一棵树。

package/skill-files//350/256/276/350/256/241/references//347/261/273/345/236/213.md

@@ -0,0 +1,19 @@
+# 涉及范围
+
+标题下先写一行「涉及：」，只留一个：纯前端、前后端、纯后端、仅数据或配置。拿不准就停下来问，不要默认写成前后端。
+
+- 纯前端：有页面。不改接口契约，不改服务，不改库和配置。页面调用的已有接口写在页面原型里。
+- 前后端：有页面，并且还改接口、服务、库、文件或配置里的至少一项。
+- 纯后端：没有页面。按实际改动留下数据、接口、服务这几章。
+- 仅数据或配置：只改表、文件、缓存、定时任务、开关、消息或线程池。没有页面，没有新的接口契约，没有要写步骤的服务。
+
+章节按这个顺序取，用到的才写。写出来的从第一章连续编号。节号跟着章号走。没用到的章和节整段删掉。
+
+1. 概述。每次都有。
+2. 变更方案。每次都有。没有取舍就删掉「取舍」这一节。
+3. 数据与配置。有表、文件、缓存、定时任务、开关、消息或线程池才有。章内只留有内容的节。
+4. 前端页面原型设计。哪些页算改到，只按护栏，不凭页面看起来变没变。一页都没有就整章删掉。放在数据与配置之后、接口设计之前。没有数据章时，紧接在变更方案后面。这一章里面怎么写，只看 `references/界面.md`。
+5. 接口设计。这次改接口契约才有。纯前端不单开这一章。
+6. 服务层设计。这次改服务步骤、定时任务或消息消费才有。纯转发且没有分支的方法不写方法细节。一个方法都不需要写步骤、映射也没有新内容时，整章删掉。
+
+不要改这些章名。不要出现缺了第二章却还有第三章。

package/skill-files//350/256/276/350/256/241/references//347/272/246/346/235/237.md

@@ -0,0 +1,25 @@
+# 约束
+
+这里只写尽量做到的事。必须项在 `references/护栏.md`，交卷前读护栏，并跑检查脚本。脚本会读下面的「脚本核对」，没做到只提示，不挡落盘。
+
+## 尽量
+
+- 影响与测试的每一行对上功能点原句。
+- 取舍写清怎么回滚。
+- 有页面时写清谁从哪个菜单进入、哪几步。
+- 旧数据要进新表时，写出怎么迁。
+
+## 脚本核对
+
+```json
+{
+  "核对": [
+    {
+      "说明": "影响与测试里「{列}」是空的",
+      "章": "变更方案",
+      "节": "影响与测试",
+      "列不能空": ["对应功能点"]
+    }
+  ]
+}
+```

package/skill-files//350/256/276/350/256/241/scripts/_smoke.mjs

@@ -0,0 +1,72 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const checker = path.join(path.dirname(fileURLToPath(import.meta.url)), 'check-design.mjs');
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'design-check-'));
+
+const tree = `订单\n├── 改  订单接口`;
+const list = (rows) => `### 2.1 改动清单\n\n\`\`\`text\n${tree}\n\`\`\`\n\n| 层 | 文件 | 新/改/不动 | 动什么 | 追溯自 | 对应页面节 |\n| :--- | :--- | :--- | :--- | :--- | :--- |\n${rows}\n`;
+const impact = (point) => `### 2.2 影响与测试关注\n\n| 影响谁 | 代码改没改 | 测试要盯什么 | 对应功能点 |\n| :--- | :--- | :--- | :--- |\n| 下单的人 | 改 | 能下单 | ${point} |\n`;
+const api = `## 第五章 接口设计\n\n### 5.1 接口清单\n\n| 请求方式 | 路径 | 作用 |\n| :--- | :--- | :--- |\n| POST | /order | 下单 |\n\n### 5.2 接口详细设计\n\n#### 接口 1：POST /order（修改）\n\n请求参数：\n\n| 字段 | 位置 |\n| :--- | :--- |\n| 无 | 无 |\n\n成功响应：\n\n| 字段 | 类型 | 说明 |\n| :--- | :--- | :--- |\n| 无 | 无 | 无 |\n\n业务错误：\n\n| 场景 | 错误码 |\n| :--- | :--- |\n| 无 | 无 |\n`;
+const page = `## 第四章 前端页面原型设计\n\n### 4.1 订单页\n\n谁从订单菜单进入，一步提交。\n\n| 本页改动 | 引用接口 | 接口本次变化 |\n| :--- | :--- | :--- |\n| 改提交按钮 | POST /order | 增加备注字段 |\n`;
+
+function doc(body) {
+  return `# 登录 · 设计说明\n\n涉及：纯后端\n\n## 第一章 概述\n\n### 1.1 技术现状\n\n现在这样。\n\n## 第二章 变更方案\n\n${body}\n`;
+}
+
+const cases = [
+  {
+    name: '纯后端只有控制层，应通过',
+    body: doc(`${list('| Controller | OrderController | 改 | 改入参 | 无 | 无 |')}\n${impact('用户可以提交订单')}\n${api}`),
+    code: 0,
+    absent: ['前端接口层', '组件'],
+  },
+  {
+    name: '纯后端没有控制层，应只报控制层',
+    body: doc(`${list('| 服务 | OrderService | 改 | 改入参 | 无 | 无 |')}\n${impact('用户可以提交订单')}\n${api}`),
+    code: 1,
+    present: ['追溯缺少控制层'],
+    absent: ['前端接口层', '组件'],
+  },
+  {
+    name: '有页面却没有前端接口层，应报接口层',
+    body: doc(`${list('| Controller | OrderController | 改 | 改入参 | 无 | 无 |\n| 组件 | OrderPage | 改 | 改按钮 | OrderController | 4.1 订单页 |')}\n${impact('用户可以提交订单')}\n${page}\n${api}`),
+    code: 1,
+    present: ['追溯缺少前端接口层'],
+    absent: ['追溯缺少控制层', '追溯缺少引用该接口的组件'],
+  },
+  {
+    name: '没有页面也没有接口时，功能点空着应通过',
+    body: doc(`${list('| 配置 | app.yml | 改 | 改开关 | 无 | 无 |')}\n${impact('')}`),
+    code: 0,
+  },
+  {
+    name: '有接口但功能点空着，应拦住',
+    body: doc(`${list('| Controller | OrderController | 改 | 改入参 | 无 | 无 |')}\n${impact('')}\n${api}`),
+    code: 1,
+    present: ['对应功能点'],
+  },
+];
+
+let failed = 0;
+for (const item of cases) {
+  const file = path.join(dir, `${item.name}.md`);
+  fs.writeFileSync(file, item.body);
+  const run = spawnSync(process.execPath, [checker, file], { encoding: 'utf8' });
+  const output = `${run.stdout}\n${run.stderr}`;
+  const problems = [];
+  if (run.status !== item.code) problems.push(`退出码 ${run.status}，期望 ${item.code}`);
+  for (const text of item.present ?? []) if (!output.includes(text)) problems.push(`缺少「${text}」`);
+  for (const text of item.absent ?? []) if (output.includes(text)) problems.push(`多报了「${text}」`);
+  if (problems.length) {
+    failed += 1;
+    console.error(`FAIL ${item.name}: ${problems.join('；')}\n${output}`);
+  } else {
+    console.log(`OK ${item.name}`);
+  }
+}
+fs.rmSync(dir, { recursive: true, force: true });
+if (failed) process.exit(1);

package/skill-files//350/256/276/350/256/241/scripts/check-design.mjs

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+/**
+ * 通用核对。条文在 references/护栏.md 和 references/约束.md 的 json 块里。
+ * 护栏未通过则退出码 1。约束里如果还有核对，只打印，不挡落盘。
+ * 用法：node check-design.mjs <设计文档.md>
+ *
+ * 一条规则可用：说明、仅当有章、章、节、范围内含、范围内不含、匹配则失败、要匹配、
+ * 表头要含、列不能空、拆块、每个标题、对账。
+ * 「至少各有一行」里的模式可以是字符串，也可以是 { 正则, 说明, 当有章 }。
+ * 说明里的 {标题} {文件} {列} {词} 会换成当前这一处。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const docPath = process.argv[2];
+if (!docPath) {
+  console.error('用法：node check-design.mjs <设计文档.md>');
+  process.exit(2);
+}
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const references = path.join(here, '..', 'references');
+
+function readRules(name) {
+  const rulePath = path.join(references, name);
+  if (!fs.existsSync(rulePath)) return [];
+  const raw = fs.readFileSync(rulePath, 'utf8');
+  const fence = raw.match(/```json\s*([\s\S]*?)```/);
+  if (!fence) return [];
+  try {
+    const data = JSON.parse(fence[1]);
+    return Array.isArray(data.核对) ? data.核对 : [];
+  } catch (error) {
+    console.error(`${name} 里的 json 读不了：${error.message}`);
+    process.exit(2);
+  }
+}
+
+const text = fs.readFileSync(docPath, 'utf8');
+
+function sliceAt(source, startRe, endRe) {
+  const match = startRe.exec(source);
+  if (!match) return null;
+  const rest = source.slice(match.index + match[0].length);
+  const next = rest.search(endRe);
+  return (next === -1 ? rest : rest.slice(0, next)).trim();
+}
+
+function chapter(source, name) {
+  return sliceAt(source, new RegExp(`^## .*${name}.*$`, 'm'), /^## /m);
+}
+
+function subsection(source, name) {
+  return sliceAt(source, new RegExp(`^### .*${name}.*$`, 'm'), /^### /m);
+}
+
+function scopeOf(source, rule) {
+  let scope = source;
+  if (rule.章) {
+    scope = chapter(source, rule.章);
+    if (scope == null) return null;
+  }
+  if (rule.节) {
+    scope = subsection(scope, rule.节);
+    if (scope == null) return null;
+  }
+  if (rule.范围内含 && !scope.includes(rule.范围内含)) return null;
+  if (rule.范围内不含 && scope.includes(rule.范围内不含)) return null;
+  return scope;
+}
+
+function tablesIn(section) {
+  const tables = [];
+  let header = null;
+  for (const line of section.split('\n')) {
+    if (!line.trim().startsWith('|')) {
+      header = null;
+      continue;
+    }
+    const cells = line.split('|').slice(1, -1).map((cell) => cell.trim());
+    if (cells.every((cell) => /^:?-+:?$/.test(cell))) continue;
+    if (!header) {
+      header = cells;
+      tables.push({ header, rows: [] });
+    } else {
+      tables[tables.length - 1].rows.push(cells);
+    }
+  }
+  return tables;
+}
+
+function cellOf(header, row, name) {
+  const index = header.findIndex((item) => item.includes(name));
+  if (index < 0) return null;
+  return (row[index] ?? '').trim();
+}
+
+function fill(template, vars) {
+  return String(template ?? '未通过').replace(/\{([^}]+)\}/g, (_, key) => vars[key] ?? '');
+}
+
+function headings(section, level) {
+  const mark = '#'.repeat(level);
+  return section.split(new RegExp(`^${mark} `, 'm')).slice(1).map((block) => ({
+    title: block.split('\n')[0].trim(),
+    body: block,
+  }));
+}
+
+function hasTableAfter(block, label) {
+  const at = block.indexOf(label);
+  if (at === -1) return false;
+  return /^\|.*\|/m.test(block.slice(at, at + 1200));
+}
+
+function headingMeta(title) {
+  const id = /^(\d+\.\d+)/.exec(title)?.[1] ?? '';
+  return { title, id, name: title.replace(/^\d+\.\d+\s*/, '').trim() };
+}
+
+function pointsAt(value, head, blanks) {
+  if (!value || blanks.includes(value)) return false;
+  if (head.id && new RegExp(`(?<![\\d.])${head.id.replace(/\./g, '\\.')}(?!\\d)`).test(value)) return true;
+  return Boolean(head.name) && value.includes(head.name);
+}
+
+function checkBlocks(scope, rule, found) {
+  const spec = rule.拆块;
+  const blocks = headings(scope, spec.级别 ?? 4);
+  if (blocks.length === 0) {
+    found.push(fill(spec.没有块说明 || rule.说明, {}));
+    return;
+  }
+  for (const block of blocks) {
+    const skip = spec.跳过当;
+    const head = `${block.title}\n${block.body.slice(0, 200)}`;
+    if (skip && head.includes(skip.含) && !block.body.includes(skip.且不含)) continue;
+    for (const word of spec.词后要有表 ?? []) {
+      if (!hasTableAfter(block.body, word)) {
+        found.push(fill(rule.说明, { 标题: block.title, 词: word }));
+      }
+    }
+  }
+}
+
+function checkHeadings(scope, rule, found) {
+  const spec = rule.每个标题;
+  const blocks = headings(scope, spec.级别 ?? 3);
+  if (blocks.length === 0 && spec.没有标题则失败) {
+    found.push(fill(rule.说明, {}));
+    return;
+  }
+  for (const block of blocks) {
+    if (spec.正文匹配则失败 && new RegExp(spec.正文匹配则失败, 'm').test(block.body)) {
+      found.push(fill(rule.说明, { 标题: block.title }));
+    }
+    const tableSpec = spec.要有表;
+    if (!tableSpec) continue;
+    const needed = tableSpec.表头含 ?? [];
+    const table = tablesIn(block.body).find((item) => needed.every((name) => item.header.some((cell) => cell.includes(name))));
+    if (!table || table.rows.length === 0) {
+      found.push(fill(tableSpec.缺表说明 || rule.说明, { 标题: block.title }));
+      continue;
+    }
+    for (const row of table.rows) {
+      for (const column of tableSpec.列不能空 ?? []) {
+        const value = cellOf(table.header, row, column);
+        if (value == null || value === '') {
+          found.push(fill(tableSpec.空列说明 || rule.说明, { 标题: block.title, 列: column }));
+        }
+      }
+      for (const [column, pattern] of Object.entries(tableSpec.列不能整格匹配 ?? {})) {
+        const value = cellOf(table.header, row, column) ?? '';
+        const source = typeof pattern === 'string' ? pattern : pattern.模式;
+        const message = typeof pattern === 'string' ? tableSpec.整格说明 || rule.说明 : pattern.说明 || rule.说明;
+        if (new RegExp(source).test(value)) found.push(fill(message, { 标题: block.title, 列: column }));
+      }
+    }
+  }
+}
+
+function leastGate(text, least) {
+  if (!least) return false;
+  const chapterHit = (least.当有章 ?? []).some((name) => chapter(text, name) != null);
+  const textHit = Object.entries(least.或章匹配 ?? {}).some(([name, pattern]) => {
+    const body = chapter(text, name);
+    return body != null && new RegExp(pattern, 'm').test(body);
+  });
+  return (least.当有章 || least.或章匹配) ? (chapterHit || textHit) : true;
+}
+
+function listTable(text, spec, found, missingMessage) {
+  const listChapter = chapter(text, spec.清单章);
+  const list = listChapter && subsection(listChapter, spec.清单节);
+  if (!list) {
+    found.push(fill(missingMessage, {}));
+    return null;
+  }
+  const needed = spec.表头要含 ?? [];
+  const table = tablesIn(list).find((item) => needed.every((name) => item.header.some((cell) => cell.includes(name))));
+  if (!table) {
+    found.push(fill(spec.缺表说明 || missingMessage, {}));
+    return null;
+  }
+  return table;
+}
+
+function checkLeast(text, table, least, blanks, found) {
+  if (!leastGate(text, least)) return;
+  const rows = table.rows.filter((row) => row.some((cell) => cell && !blanks.includes(cell)));
+  const values = rows.map((row) => cellOf(table.header, row, least.列) ?? '');
+  least.模式.forEach((pattern, index) => {
+    const source = typeof pattern === 'string' ? pattern : pattern.正则;
+    const needChapters = typeof pattern === 'string' ? null : pattern.当有章;
+    if (Array.isArray(needChapters) && !needChapters.some((name) => chapter(text, name) != null)) return;
+    if (!values.some((value) => new RegExp(source, 'i').test(value))) {
+      const message = typeof pattern === 'object' && pattern.说明
+        ? pattern.说明
+        : (Array.isArray(least.说明) ? least.说明[index] : least.说明);
+      found.push(fill(message, { 模式: source }));
+    }
+  });
+}
+
+function checkRows(text, spec, found) {
+  const pages = chapter(text, spec.页面章);
+  const least = spec.至少各有一行;
+  const leastOn = leastGate(text, least);
+  if (pages == null && !leastOn) return;
+
+  const blanks = spec.空值 ?? ['', '无'];
+  const table = listTable(
+    text,
+    spec,
+    found,
+    pages == null ? (spec.缺表说明 || '改动清单里还没有追溯要用的表') : (spec.说明 || '清单和页面章对不上')
+  );
+  if (!table) return;
+
+  if (pages != null) {
+    const heads = headings(pages, spec.标题级别 ?? 3).map((block) => headingMeta(block.title));
+    const rows = table.rows.filter((row) => row.some((cell) => cell && !blanks.includes(cell)));
+
+    for (const rowRule of spec.行 ?? []) {
+      const rowBlanks = rowRule.空值 ?? blanks;
+      for (const row of rows) {
+        const when = rowRule.当列匹配 ?? {};
+        const matched = Object.entries(when).every(([column, pattern]) => new RegExp(pattern, 'i').test(cellOf(table.header, row, column) ?? ''));
+        if (!matched) continue;
+        if (rowRule.列要有字 && !cellOf(table.header, row, rowRule.列要有字)) continue;
+        const file = cellOf(table.header, row, rowRule.列要有字 || '文件') ?? '';
+        if (rowRule.列要指向标题) {
+          const value = cellOf(table.header, row, rowRule.列要指向标题) ?? '';
+          if (!heads.some((head) => pointsAt(value, head, rowBlanks))) {
+            found.push(fill(rowRule.说明, { 文件: file, 标题: value }));
+          }
+        }
+        for (const [column, banned] of Object.entries(rowRule.列不能是 ?? {})) {
+          const value = cellOf(table.header, row, column) ?? '';
+          if (banned.includes(value)) found.push(fill(rowRule.说明, { 文件: file, 列: column }));
+        }
+      }
+    }
+
+    const link = spec.每个标题要被指向;
+    if (link) {
+      for (const head of heads) {
+        const linked = rows.some((row) => pointsAt(cellOf(table.header, row, link.列) ?? '', head, blanks));
+        if (!linked) found.push(fill(link.说明, { 标题: head.title }));
+      }
+    }
+  }
+
+  checkLeast(text, table, least, blanks, found);
+}
+
+function checkColumns(scope, rule, found) {
+  const tables = tablesIn(scope).filter((item) => rule.列不能空.every((name) => item.header.some((cell) => cell.includes(name))));
+  if (tables.length === 0) {
+    if (rule.缺列说明) {
+      for (const column of rule.列不能空) found.push(fill(rule.缺列说明, { 列: column }));
+    }
+    return;
+  }
+  for (const table of tables) {
+    for (const row of table.rows) {
+      if (!row.some((cell) => cell)) continue;
+      for (const column of rule.列不能空) {
+        if (!(cellOf(table.header, row, column) ?? '')) {
+          found.push(fill(rule.说明, { 列: column }));
+        }
+      }
+    }
+  }
+}
+
+function apply(source, rule, found) {
+  if (Array.isArray(rule.仅当有章) && !rule.仅当有章.some((name) => chapter(source, name) != null)) return;
+  if (rule.对账) {
+    checkRows(source, { ...rule.对账, 说明: rule.对账.说明 || rule.说明 }, found);
+    return;
+  }
+  const scope = scopeOf(source, rule);
+  if (scope == null) return;
+  if (rule.匹配则失败 && new RegExp(rule.匹配则失败, 'm').test(scope)) found.push(fill(rule.说明, {}));
+  if (rule.要匹配 && !new RegExp(rule.要匹配, 'm').test(scope)) found.push(fill(rule.说明, {}));
+  if (rule.表头要含) {
+    const ok = tablesIn(scope).some((item) => rule.表头要含.every((name) => item.header.some((cell) => cell.includes(name))));
+    if (!ok) found.push(fill(rule.说明, {}));
+  }
+  if (rule.列不能空) checkColumns(scope, rule, found);
+  if (rule.拆块) checkBlocks(scope, rule, found);
+  if (rule.每个标题) checkHeadings(scope, rule, found);
+}
+
+const must = [];
+const hints = [];
+for (const rule of readRules('护栏.md')) apply(text, rule, must);
+for (const rule of readRules('约束.md')) apply(text, rule, hints);
+
+if (hints.length > 0) {
+  console.log(`尽量未做到 ${hints.length} 项：`);
+  for (const item of hints) console.log(`- ${item}`);
+}
+if (must.length > 0) {
+  console.error(`未通过 ${must.length} 项：`);
+  for (const item of must) console.error(`- ${item}`);
+  process.exit(1);
+}
+console.log('通过');

package/skill-files//351/234/200/346/261/202/references//346/212/244/346/240/217.md

@@ -0,0 +1,26 @@
+# 护栏
+
+护栏挂在动作上，不靠回头翻清单。落盘前运行 `scripts/check-requirements.mjs`，脚本退出码不是 0，就不能交。必须项只在这一份。`references/约束.md` 只是尽量项。
+
+## 写每节时查
+
+1. 四个二级标题只用模板那四个，顺序不换，不加别的二级标题。脚本查。
+2. 需求背景只写现在谁办不到什么，不超过五句。这次打算怎么改不写进来。说不清时写「现状还没单独说明」，并在需求待定里留一行。句数和「谁看见什么」人看，脚本不查。
+3. 需求描述写了动哪一块、大致做成什么样、旁边这次不动的，不超过五句。句数人看，脚本不查。
+4. 每个功能点动词开头，写了做成什么样、谁看见什么。一点不超过三句，单句不超过 40 个字。写不出的放需求待定，不编结果。动词、句数、字数人看，脚本不查。
+5. 功能点只写人能感知的事。文风里禁止的词不出现。脚本只查围栏和「」外面的禁词。
+
+## 遇到这些，按这个走
+
+| 遇到什么 | 怎么办 |
+|---|---|
+| 深思记录里有未决 | 写进需求待定，不写成已经说清，不替人拍板 |
+| 深思记录里已定的结论 | 写进背景、描述或功能点，不重问 |
+| 功能点缺口会改做法，但还没定 | 写进需求待定，把这份文档写完。不停下来重问 |
+| 返回的 template 说明和文风不一致 | 以文风和需求待定为准 |
+
+## 落盘前查
+
+1. 跑 `node scripts/check-requirements.mjs <需求文档.md>`，退出码是 0。
+2. 需求待定没有项时写了「无」。
+3. 对话只报路径和需求待定里还要人拍板的条目。不说「接下来写设计」。

package/skill-files//351/234/200/346/261/202/references//346/226/207/351/243/216.md

@@ -0,0 +1,23 @@
+# 需求文风
+
+正文必须是简体中文、白话。四个二级标题按这个顺序，不要多也不要少：需求背景、需求描述、需求功能点拆分、需求待定。
+
+会改功能点但还没定的，写进需求待定，把这份文档写完。不要停下来重问，也不要编一句结果填进功能点。
+
+需求背景只写现状：现在谁办不到什么。不超过五句。不写目标口号，不写这次打算怎么改。说不清就写「现状还没单独说明」，并在需求待定里留一行。
+
+需求描述写三件事：这次动哪一块，大致做成什么样，旁边这次不动的。不超过五句。不动的相邻块写在这里。
+
+功能点用动词开头。对得上的就用：新增、修改、查询、删除、启用、停用。一次通知、一次导入也各算一点。一点只写一件用户能感知的事，并写做成什么样、谁看见什么。一个功能点不超过三句。单句不超过 40 个字。
+
+校验、落库、接口路径、类名、表名、错误码不写进功能点。
+
+某个功能点需要给人看页面或交接时，把简图直接放在该功能点下面。第一行写「草图（附注，不作为依据）」。没有图就不要留空图。句子和图不一致时，以该功能点的句子为准。没有页面就不要画按钮。
+
+几个系统之间交接时，用功能点写谁交给谁、交完看见什么，最多六行。配置、开关、定时、修数据，写谁触发、跑完怎样、不跑时怎样。
+
+禁止：优化、提升、赋能、闭环、拉通、大概、可能、后续再看、给定-当-则。不要把对话过程写进正文。专业词第一次出现，后面补半句白话。
+
+能量化的写数字。不能量化又会改变功能点的，放进需求待定，不要编一个数。
+
+「看见什么」必须来自已经说清的话。还写不出结果，就放进需求待定，不要在落文档时补一句。

package/skill-files//351/234/200/346/261/202/references//346/267/261/346/200/235/346/221/204/345/205/245.md

@@ -0,0 +1,21 @@
+# 有深思记录时怎么写
+
+变更目录里如果有 `深思/registry.json`，先读它，也读 `深思/记录.md`。不要把整份 JSON 贴进对话。没有这些文件也可以写需求。
+
+若只有上一版的 `追问/`，把它当作 `深思/` 来读。
+
+已定、沿用材料：写进需求描述或对应功能点，不要再问。`记录.md` 的答案是材料，按四个标题重写，不要整篇搬过去。
+
+未决：写进需求待定。不要重问，也不要在正文里猜成某一种。
+
+页面不适用时，不要画草图，也不要单开一节。
+
+对照：
+
+- 现状和问题写进需求背景，只写已经说清的事实
+- 动哪一块、这次不动的相邻块写进需求描述
+- 要做的每一件事写成一条功能点，动词开头，并写看见什么
+- 会改功能点但还没定的，只放需求待定
+- 三方核对已定的页面、表、接口，按结论写进对应功能点。对不上且还没选定的，放需求待定，不要把原句照抄成已经说清
+
+功能点里的「看见什么」必须来自已经说清的话。记录里没有结果，就留在需求待定，不要补一句。

package/skill-files//351/234/200/346/261/202/references//347/272/246/346/235/237.md

@@ -0,0 +1,8 @@
+# 约束
+
+这里只写尽量做到的事。必须项在 `references/护栏.md`。
+
+## 尽量
+
+- 能量化的写数字。编不出的数放进需求待定，不要编一个。
+- 功能点对得上时，动词用：新增、修改、查询、删除、启用、停用。

package/skill-files//351/234/200/346/261/202/references//351/234/200/346/261/202/345/276/205/345/256/232.md

@@ -0,0 +1,13 @@
+# 需求待定
+
+这一节不能删。没有项时只写：无。
+
+写需求时，会改功能点但还没定的放在这里，然后把文档写完。不要为了这些项停下来问，也不要在功能点里猜一个结果来躲开这一节。
+
+只写会改功能点、还没接上的事。例如：有启用没有停用，失败时看见什么还没定，两个功能点对不上，历史数据要不要改还没定。
+
+库表、接口路径、错误码、字段怎么摆，不写在这一节，留给设计。
+
+写设计、写任务、写代码时读到这些项，停下来问，不要补。
+
+用户确认之后，把结论写进需求描述或对应功能点，删掉这一行。

package/skill-files//351/234/200/346/261/202/scripts/check-requirements.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * 核对需求文档的结构。句子长短和「谁看见什么」仍由 references/护栏.md 人工对。
+ * 用法：node check-requirements.mjs <需求文档.md>
+ */
+import fs from 'node:fs';
+
+const docPath = process.argv[2];
+if (!docPath) {
+  console.error('用法：node check-requirements.mjs <需求文档.md>');
+  process.exit(2);
+}
+
+const text = fs.readFileSync(docPath, 'utf8');
+const prose = text.replace(/```[\s\S]*?```/g, '').replace(/「[^」]*」/g, '');
+const errors = [];
+const expected = ['需求背景', '需求描述', '需求功能点拆分', '需求待定'];
+const headings = [...text.matchAll(/^##\s+(.+)$/gm)].map((match) => match[1].trim());
+
+if (headings.join('\n') !== expected.join('\n')) {
+  const now = headings.length ? headings.join('、') : '（没有）';
+  errors.push(`二级标题必须按顺序只有这四个：${expected.join('、')}。现在是：${now}`);
+}
+
+function section(name) {
+  const start = text.search(new RegExp(`^##\\s+${name}\\s*$`, 'm'));
+  if (start < 0) return '';
+  const rest = text.slice(start).split('\n').slice(1).join('\n');
+  const next = rest.search(/^##\s+/m);
+  return (next < 0 ? rest : rest.slice(0, next)).trim();
+}
+
+if (headings.includes('需求待定') && !section('需求待定')) {
+  errors.push('需求待定是空的。没有项就写「无」。');
+}
+
+const points = section('需求功能点拆分');
+if (headings.includes('需求功能点拆分') && !/^\s*\d+[.、．]/m.test(points)) {
+  errors.push('功能点拆分里没有编号的功能点。不要用一段话代替。');
+}
+
+const banned = ['本变更不涉及', 'SHALL', '赋能', '闭环', '拉通', '后续再看', '给定-当-则'];
+for (const word of banned) {
+  if (prose.includes(word)) errors.push(`正文里有不能出现的「${word}」。`);
+}
+if (/\bGiven\b|\bWhen\b|\bThen\b/.test(prose)) {
+  errors.push('正文里有 Given、When 或 Then。');
+}
+
+const leftovers = ['（谁）', '（旁边哪些）', '（一件事）', '（什么）', '（什么样）', '（哪里）', '（现在谁办不到什么'];
+for (const token of leftovers) {
+  if (text.includes(token)) errors.push(`模板提示还在：${token}`);
+}
+
+if (errors.length) {
+  for (const error of errors) console.error(error);
+  process.exit(1);
+}
+
+console.log('通过');

package/skill-files//351/252/214/346/224/266/references//346/212/244/346/240/217.md

@@ -0,0 +1,27 @@
+# 护栏
+
+护栏挂在动作上，不靠回头翻清单。必须项只在这一份。`references/约束.md` 只是尽量项。
+
+## 开工前查
+
+1. 只读。缺的文件点名，不当成失败，也不当成已经覆盖。
+2. 核对对象想清楚：审Java 只评代码质量，审文档只评文档质量，验收对照两边。这次问的是哪一种，就做哪一种。
+
+## 核对时查
+
+1. `references/核对.md` 里的三块都写了：做完的、缺证据的、和文档不一致的。
+2. 任务勾了但代码里找不到改动的，不算做完。
+3. 实现和设计里写明的做法、接口、表或状态相反，才算不一致。设计没写的不算。没有设计就写「没有设计可对照」。
+4. 每条问题写清文件，能定位到行的写行，并写可以怎么改。没有证据不升成严重。
+
+## 报结论时查
+
+结论只用：通过、有条件通过、不通过。
+
+- 不通过：实现和文档里写明的做法、接口、表或状态相反，或者任务勾了但代码里没有改动。
+- 有条件通过：没有和文档相反，但有缺证据。
+- 通过：已有文档都能对上，也没有缺证据。
+
+缺了某份文档，点名即可，单独不构成不通过。
+
+结论摘要 3 到 6 句，非研发读完能懂风险。先说人话，不贴文档全文，不说「接下来改代码」「接下来归档」。