nx-sk 0.9.2 → 0.11.0

package/src/core/fields.js

@@ -3,7 +3,27 @@
 //
 // type 取值：text | textarea | number | date | month | bool | select | tags | secret | file
 
-export const FIELD_TYPES = ['text', 'textarea', 'number', 'date', 'month', 'bool', 'select', 'tags', 'secret', 'file'];
+export const FIELD_TYPES = ['text', 'textarea', 'number', 'date', 'month', 'bool', 'select', 'tags', 'secret', 'file', 'md'];
+
+/**
+ * 类型的人读标签 —— 只用于**面板下拉框**。
+ *
+ * 下拉框此前直接渲染 `md` / `tags` 这种内部 id，选类型的人得先知道内部分类。
+ * 这里给中文名，渲染成「图文（可贴图）（md）」：既看得懂，也不丢 id（排查时用得上）。
+ */
+export const FIELD_TYPE_LABELS = {
+  text: '单行文本',
+  textarea: '多行文本',
+  number: '数字',
+  date: '日期',
+  month: '月份',
+  bool: '是/否',
+  select: '单选',
+  tags: '多值标签',
+  secret: '密文',
+  file: '附件',
+  md: '图文（可贴图）',
+};
 
 /**
  * 字段的**填写策略**——回答「这个字段值不值得填」，与 type 正交。
@@ -176,6 +196,45 @@ const CAMPUS_FIELDS = [
   f('duties', '职责描述', 'textarea', 'main'),
 ];
 
+// —— 部署配置（Docker / K8s）——
+//
+// 一个条目 = **一份可复用的配置文件**。设计目标不是"存文件"（附件就能存），
+// 而是"下次能在别的项目里照着用"：所以除了正文，还要有「放哪」「哪些值要替换」
+// 「什么场景用」。缺了后三项，正文就只是一段没有上下文的 YAML。
+//
+// 明文密钥不进这里：`content` 里只写 `${VAR}` 占位，真值放「密钥」栏目
+// （那里是密文落盘）。这条写进字段 hint，而不是靠人自觉 —— 配置文件是最容易
+// 被整份复制粘贴分享出去的东西。
+const DEPLOY_FIELDS = [
+  f('name', '资源名', 'text', 'main', { hint: '一眼能看出是什么，如「node-web 多阶段 Dockerfile」' }),
+  f('kind', '资源类型', 'select', 'main', {
+    options: [
+      'Dockerfile', 'docker-compose', 'dockerignore',
+      'k8s-deployment', 'k8s-service', 'k8s-ingress', 'k8s-configmap', 'k8s-secret', 'k8s-kustomization',
+      'helm', '其他',
+    ],
+  }),
+  f('stack', '适用技术栈', 'text', 'main', { fill: 'optional', hint: 'node / go / python / 任意' }),
+  f('path', '建议落盘路径', 'text', 'main', { fill: 'optional', hint: '如 deploy/Dockerfile、deploy/k8s/base/deployment.yaml' }),
+  f('tags', '标签', 'tags', 'main', { fill: 'optional', hint: '如 prod、多阶段、健康检查、SSE' }),
+  f('content', '文件正文', 'textarea', 'body', {
+    hint: '整份文件原文。密钥一律写 ${VAR} 占位，真值放「密钥」栏目，别写明文',
+  }),
+  f('vars', '需替换的变量', 'textarea', 'body', {
+    fill: 'optional',
+    hint: '每行一个「变量 = 说明」。复用前先替换这些，别指望正文里的值直接能用',
+  }),
+  f('usage', '何时用 / 关键取舍', 'textarea', 'use', {
+    fill: 'optional',
+    hint: '为什么这么写、坑在哪（例如 ingress 关 buffering 才能保住 SSE）',
+  }),
+  f('sop', '操作步骤（图文）', 'md', 'use', {
+    fill: 'optional',
+    hint: '截屏 + 说明混排：直接 Ctrl+V 粘图，图片会统一列在下方，点开可放大看细节',
+  }),
+  f('files', '原件附件', 'file', 'use', { fill: 'optional', hint: '要连真实文件一起留档时挂这里（可选）' }),
+];
+
 const TEMPLATES = {
   job: {
     id: 'job',
@@ -237,6 +296,21 @@ const TEMPLATES = {
     groups: [{ id: 'main', title: '职务信息' }],
     fields: CAMPUS_FIELDS,
   },
+  deploy: {
+    id: 'deploy',
+    label: '部署配置（Docker / K8s）',
+    description:
+      '一份配置文件一个条目：正文即文件原文，配「放哪」「哪些值要替换」「什么场景用」，' +
+      '好让它在别的项目里能照着用。明文密钥不放这里（用 ${VAR} 占位，真值进「密钥」栏目）。',
+    titleField: 'name',
+    titleLabel: '资源名',
+    groups: [
+      { id: 'main', title: '基本信息' },
+      { id: 'body', title: '文件内容' },
+      { id: 'use', title: '使用说明' },
+    ],
+    fields: DEPLOY_FIELDS,
+  },
 };
 
 export function templateIds() {
@@ -286,6 +360,7 @@ export function seedSections(stamp) {
     { ...instantiateTemplate('internships', { id: 'internships', title: '实习/工作经历', order: 12 }), createdAt: stamp, updatedAt: stamp },
     { ...instantiateTemplate('campus', { id: 'campus', title: '校内职务/实践', order: 13 }), createdAt: stamp, updatedAt: stamp },
     { ...instantiateTemplate('secret', { id: 'secret', title: '密钥', order: 20 }), createdAt: stamp, updatedAt: stamp },
+    { ...instantiateTemplate('deploy', { id: 'deploy', title: '部署配置', order: 30 }), createdAt: stamp, updatedAt: stamp },
   ];
 }
 
@@ -320,6 +395,34 @@ export function syncSectionGroups(groups, fields) {
   return out;
 }
 
+/**
+ * 同一 key 的字段在「栏目 vs 模板」之间哪些属性不同；空数组 = 定义一致。
+ *
+ * 比较前先**归一**：`fill` 缺省就是 `normal`（`validateFieldDef` 只在非 normal 时落盘），
+ * `options`/`maxItems` 缺失与空数组/空值等价。不归一的话，一份「模板里没写 fill、
+ * 栏目里写了 fill:normal」的等价定义会被报成漂移，噪音会淹没真正的差异。
+ */
+const FIELD_CMP_KEYS = ['label', 'type', 'group', 'hint', 'options', 'maxItems', 'sensitive', 'fill'];
+
+function normalizedFieldDef(f) {
+  return {
+    label: String(f?.label ?? f?.key ?? ''),
+    type: f?.type || 'text',
+    group: f?.group || 'other',
+    hint: f?.hint ? String(f.hint) : '',
+    options: Array.isArray(f?.options) ? f.options.map(String) : [],
+    maxItems: Number.isFinite(f?.maxItems) ? f.maxItems : null,
+    sensitive: f?.sensitive === true,
+    fill: f?.fill || 'normal',
+  };
+}
+
+export function fieldDrift(sectionField, templateField) {
+  const a = normalizedFieldDef(sectionField);
+  const b = normalizedFieldDef(templateField);
+  return FIELD_CMP_KEYS.filter((k) => JSON.stringify(a[k]) !== JSON.stringify(b[k]));
+}
+
 /**
  * 模板增量合并：把模板里**尚未出现在栏目**的分组与字段补进去（只增，绝不改/删）。
  *
@@ -333,12 +436,17 @@ export function syncSectionGroups(groups, fields) {
  *     模板没有的自定义分组原顺序附在后面。
  *   - 字段：栏目已有的字段原样保留（含用户改过的 label/hint/fill）；缺的模板字段
  *     插到「模板顺序里它前一个字段」之后，未在模板中的自定义字段保持原位。
+ *
+ * 另外回传 `changedFields`：**同名字段定义已分叉**的清单（只报告，绝不自动改）。
+ * 光有「只增不改」的话，模板改了默认 label/hint 是**完全无声**的 ——
+ * 用户会以为「同步过了 = 跟模板一致」，实际不一致。把差异摆出来，改不改由人定。
  */
 export function mergeTemplate(section, template) {
   const existingGroups = section?.groups || [];
   const existingFields = section?.fields || [];
   const groupById = new Map(existingGroups.map((g) => [g.id, g]));
   const fieldKeys = new Set(existingFields.map((f) => f.key));
+  const fieldByKey = new Map(existingFields.map((f) => [f.key, f]));
 
   const groups = [];
   const seenGroup = new Set();
@@ -352,8 +460,14 @@ export function mergeTemplate(section, template) {
   const tplOrder = new Map((template?.fields || []).map((f, i) => [f.key, i]));
   const fields = [...existingFields];
   const addedFields = [];
+  const changedFields = [];
   for (const tf of template?.fields || []) {
-    if (fieldKeys.has(tf.key)) continue;
+    if (fieldKeys.has(tf.key)) {
+      // 同名 = 定义归栏目；只算差异用于提示
+      const diff = fieldDrift(fieldByKey.get(tf.key), tf);
+      if (diff.length) changedFields.push({ key: tf.key, diff });
+      continue;
+    }
     // 插到第一个「模板序更靠后」的既有字段之前；找不到就追加到末尾
     const ti = tplOrder.get(tf.key);
     let insertAt = fields.length;
@@ -366,7 +480,7 @@ export function mergeTemplate(section, template) {
     addedFields.push(tf.key);
   }
 
-  return { groups, fields, addedGroups, addedFields };
+  return { groups, fields, addedGroups, addedFields, changedFields };
 }
 
 export function fieldByKey(section, key) {

package/src/core/mdimages.js

@@ -0,0 +1,65 @@
+// 图文字段（`type: 'md'`）里图片引用的解析与重写 —— **Node 侧唯一实现**。
+//
+// 语法就是普通 markdown：`![说明](f_xxx)`，不加 `![[…]]` 这种方言。
+// 理由：这段文字经常要原样流出去（导出成 md、贴进仓库 README、发给同事），
+// 标准语法才不挑渲染器；方言只有本工具的编辑器认得。
+//
+// 前端不能 import core，`fieldEditor.jsx` 里自带一份同口径的正则
+// （与 `toIds` 复制 `fileIdsOf` 是同一类取舍，两处必须一起改）。
+
+// 附件 id 形如 `f_lq3k2j9a1b2c3d4`（core/ids.js 的 newId）。放宽到任意 token，
+// 认不出的就当普通文字：任务正文里写 `![图](https://…)` 也不该被改写。
+const IMAGE_RE = /!\[([^\]]*)\]\(\s*([^)\s]+)\s*\)/g;
+
+/** 外链图片：`![说明](https://…)` 引的是网上的图，不在附件库里。 */
+export function isHttpUrl(value) {
+  return /^https?:\/\//i.test(String(value ?? '').trim());
+}
+
+/** 解析出全部图片引用（保序，含重复）。 */
+export function parseMdImages(text) {
+  const src = String(text ?? '');
+  const out = [];
+  if (!src) return out;
+  IMAGE_RE.lastIndex = 0;
+  let m;
+  while ((m = IMAGE_RE.exec(src)) !== null) {
+    out.push({ alt: m[1], id: m[2].trim(), raw: m[0], index: m.index });
+  }
+  return out;
+}
+
+/** 正文引用到的**附件** id（去重、保序）—— 用来建 `files` 表与做完整性检查。
+ *  外链图片不在附件库里，不进去：否则每张网图都要白查一次台账。 */
+export function mdImageIds(text) {
+  const seen = new Set();
+  const out = [];
+  for (const { id } of parseMdImages(text)) {
+    if (isHttpUrl(id) || seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out;
+}
+
+/**
+ * 把正文里的图片引用改写成**人能读的一行**（CLI / 导出用）：
+ *   `![发票截图](f_abc)` → `[图片: 发票截图] ~/nx-sk/files/other/发票截图.png`
+ *
+ * `lookup(id)` 返回 `{ name, path }` 或 null。null 表示附件已不在库里 ——
+ * 这时**保留**一条醒目的「图片缺失」，而不是静默删掉：删了等于让读者以为这里本来没图。
+ */
+export function rewriteMdImages(text, lookup) {
+  const src = String(text ?? '');
+  if (!src) return '';
+  IMAGE_RE.lastIndex = 0;
+  return src.replace(IMAGE_RE, (raw, alt, id) => {
+    const ref = String(id).trim();
+    // 外链图片不查附件库：查了必然是「缺失」，但图其实在（只是要联网）。
+    if (isHttpUrl(ref)) return `[外链图片: ${alt || ref}] ${ref}`;
+    const rec = lookup(ref);
+    if (!rec) return `[图片缺失: ${ref}]`;
+    const label = alt || rec.name || ref;
+    return rec.path ? `[图片: ${label}] ${rec.path}` : `[图片: ${label}] ${rec.name}`;
+  });
+}

package/src/core/zip.js

@@ -0,0 +1,198 @@
+// 极简 ZIP 读写（store / deflate），零依赖。
+//
+// 为什么自己写：nx-sk 的运行时**不装任何 npm 包**（镜像、离线、审计都靠这一点）。
+// 这里只需要「打一个包 / 解一个包」：条目上限 2000、单文件上限 100MB，
+// 足够栏目导出（JSON + 截图 + PDF）。不支持 Zip64 / 加密 —— 遇到就报清晰的错，
+// 而不是解出半个包。
+//
+// 写：默认 store（不压缩）。图片/PDF 本来就是压缩格式，再 deflate 省不了多少，
+// 反而让「用系统工具打开 zip 排查」变复杂。`compress: true` 时才 deflate 文本。
+import { deflateRawSync, inflateRawSync } from 'node:zlib';
+
+const SIG_LOCAL = 0x04034b50;
+const SIG_CENTRAL = 0x02014b50;
+const SIG_EOCD = 0x06054b50;
+const FLAG_UTF8 = 0x0800;
+
+const MAX_ENTRIES = 2000;
+const MAX_FILE_BYTES = 100 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 300 * 1024 * 1024;
+
+const CRC_TABLE = (() => {
+  const t = new Int32Array(256);
+  for (let i = 0; i < 256; i += 1) {
+    let c = i;
+    for (let k = 0; k < 8; k += 1) c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+    t[i] = c;
+  }
+  return t;
+})();
+
+export function crc32(buf) {
+  let c = ~0;
+  for (let i = 0; i < buf.length; i += 1) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (~c) >>> 0;
+}
+
+/** DOS 时间戳：ZIP 只存到 2 秒精度；用导出时刻，方便按时间排序。 */
+function dosDateTime(d = new Date()) {
+  const time = ((d.getHours() & 31) << 11) | ((d.getMinutes() & 63) << 5) | ((d.getSeconds() >> 1) & 31);
+  const date = (((d.getFullYear() - 1980) & 127) << 9) | (((d.getMonth() + 1) & 15) << 5) | (d.getDate() & 31);
+  return { time, date };
+}
+
+/**
+ * zip 内路径必须**相对且干净**：绝对路径、盘符、`..` 段一律拒绝。
+ * 这不是洁癖——导入时我们会按这个路径写文件，放过去就是任意文件写入。
+ */
+export function assertSafeZipName(name) {
+  const n = String(name ?? '');
+  if (!n || n.includes('\0')) throw new Error('ZIP 条目名为空或含非法字符');
+  if (n.startsWith('/') || n.startsWith('\\') || /^[A-Za-z]:/.test(n)) {
+    throw new Error(`ZIP 条目不能是绝对路径: ${n}`);
+  }
+  const parts = n.replace(/\\/g, '/').split('/');
+  if (parts.some((p) => p === '..')) throw new Error(`ZIP 条目不能包含 ..: ${n}`);
+  return n;
+}
+
+/**
+ * 生成 ZIP。
+ * @param {Array<{name: string, data: Buffer|string}>} entries
+ * @param {{compress?: boolean, mtime?: Date}} [opts]
+ * @returns {Buffer}
+ */
+export function createZip(entries, { compress = false, mtime = new Date() } = {}) {
+  const list = (entries || []).map((e) => {
+    const name = assertSafeZipName(e.name);
+    const data = Buffer.isBuffer(e.data) ? e.data : Buffer.from(String(e.data ?? ''), 'utf8');
+    const body = compress ? deflateRawSync(data) : data;
+    return { name, nameBuf: Buffer.from(name, 'utf8'), data, body, method: compress ? 8 : 0, crc: crc32(data) };
+  });
+  if (list.length > MAX_ENTRIES) throw new Error(`ZIP 条目过多（${list.length} > ${MAX_ENTRIES}）`);
+
+  const { time, date } = dosDateTime(mtime);
+  const locals = [];
+  const centrals = [];
+  let offset = 0;
+
+  for (const e of list) {
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(SIG_LOCAL, 0);
+    local.writeUInt16LE(20, 4); // version needed
+    local.writeUInt16LE(FLAG_UTF8, 6);
+    local.writeUInt16LE(e.method, 8);
+    local.writeUInt16LE(time, 10);
+    local.writeUInt16LE(date, 12);
+    local.writeUInt32LE(e.crc, 14);
+    local.writeUInt32LE(e.body.length, 18);
+    local.writeUInt32LE(e.data.length, 22);
+    local.writeUInt16LE(e.nameBuf.length, 26);
+    local.writeUInt16LE(0, 28);
+    locals.push(local, e.nameBuf, e.body);
+
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(SIG_CENTRAL, 0);
+    central.writeUInt16LE(20, 4); // version made by
+    central.writeUInt16LE(20, 6); // version needed
+    central.writeUInt16LE(FLAG_UTF8, 8);
+    central.writeUInt16LE(e.method, 10);
+    central.writeUInt16LE(time, 12);
+    central.writeUInt16LE(date, 14);
+    central.writeUInt32LE(e.crc, 16);
+    central.writeUInt32LE(e.body.length, 20);
+    central.writeUInt32LE(e.data.length, 24);
+    central.writeUInt16LE(e.nameBuf.length, 28);
+    central.writeUInt16LE(0, 30); // extra
+    central.writeUInt16LE(0, 32); // comment
+    central.writeUInt16LE(0, 34); // disk
+    central.writeUInt16LE(0, 36); // internal attrs
+    central.writeUInt32LE(0, 38); // external attrs
+    central.writeUInt32LE(offset, 42);
+    centrals.push(central, e.nameBuf);
+
+    offset += local.length + e.nameBuf.length + e.body.length;
+  }
+
+  const centralBuf = Buffer.concat(centrals);
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(SIG_EOCD, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(list.length, 8);
+  eocd.writeUInt16LE(list.length, 10);
+  eocd.writeUInt32LE(centralBuf.length, 12);
+  eocd.writeUInt32LE(offset, 16);
+  eocd.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...locals, centralBuf, eocd]);
+}
+
+/**
+ * 解 ZIP，返回 `[{ name, data }]`（目录条目不返回）。
+ * 只支持 store / deflate；加密、Zip64、超大包都明确报错。
+ */
+export function readZip(buf, { maxEntries = MAX_ENTRIES, maxTotalBytes = MAX_TOTAL_BYTES } = {}) {
+  const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf || []);
+  if (b.length < 22) throw new Error('不是有效的 ZIP：文件太小');
+
+  // EOCD 可能被注释顶到后面；从尾部往前找，最多 64KB 注释
+  const min = Math.max(0, b.length - 22 - 0xffff);
+  let eocd = -1;
+  for (let i = b.length - 22; i >= min; i -= 1) {
+    if (b.readUInt32LE(i) === SIG_EOCD) { eocd = i; break; }
+  }
+  if (eocd < 0) throw new Error('不是有效的 ZIP：找不到目录结尾（EOCD）');
+
+  const total = b.readUInt16LE(eocd + 10);
+  const cdSize = b.readUInt32LE(eocd + 12);
+  const cdOff = b.readUInt32LE(eocd + 16);
+  if (total === 0xffff || cdOff === 0xffffffff) throw new Error('暂不支持 Zip64（条目或体积超过 4GB）');
+  if (total > maxEntries) throw new Error(`ZIP 条目过多（${total} > ${maxEntries}）`);
+  if (cdOff + cdSize > b.length) throw new Error('ZIP 目录区越界：文件可能被截断');
+
+  const out = [];
+  let totalBytes = 0;
+  let p = cdOff;
+
+  for (let i = 0; i < total; i += 1) {
+    if (p + 46 > b.length || b.readUInt32LE(p) !== SIG_CENTRAL) throw new Error('ZIP 目录项损坏');
+    const flags = b.readUInt16LE(p + 8);
+    if (flags & 0x1) throw new Error('ZIP 已加密，暂不支持');
+    const method = b.readUInt16LE(p + 10);
+    const crc = b.readUInt32LE(p + 16);
+    const compSize = b.readUInt32LE(p + 20);
+    const uncompSize = b.readUInt32LE(p + 24);
+    const nameLen = b.readUInt16LE(p + 28);
+    const extraLen = b.readUInt16LE(p + 30);
+    const commentLen = b.readUInt16LE(p + 32);
+    const localOff = b.readUInt32LE(p + 42);
+    if (p + 46 + nameLen > b.length) throw new Error('ZIP 目录项越界');
+
+    const name = b.slice(p + 46, p + 46 + nameLen).toString('utf8');
+    p += 46 + nameLen + extraLen + commentLen;
+    if (name.endsWith('/')) continue; // 目录条目
+
+    const safe = assertSafeZipName(name);
+    if (uncompSize > MAX_FILE_BYTES) throw new Error(`ZIP 内单文件过大: ${safe}（${uncompSize} 字节）`);
+    totalBytes += uncompSize;
+    if (totalBytes > maxTotalBytes) throw new Error('ZIP 解压后总体积过大');
+
+    if (localOff + 30 > b.length || b.readUInt32LE(localOff) !== SIG_LOCAL) throw new Error(`ZIP 条目头损坏: ${safe}`);
+    const lNameLen = b.readUInt16LE(localOff + 26);
+    const lExtraLen = b.readUInt16LE(localOff + 28);
+    const dataStart = localOff + 30 + lNameLen + lExtraLen;
+    if (dataStart + compSize > b.length) throw new Error(`ZIP 条目被截断: ${safe}`);
+
+    const raw = b.slice(dataStart, dataStart + compSize);
+    let data;
+    if (method === 0) data = raw;
+    else if (method === 8) data = inflateRawSync(raw);
+    else throw new Error(`不支持的压缩方式 ${method}: ${safe}`);
+    if (data.length !== uncompSize) throw new Error(`ZIP 条目长度不符: ${safe}`);
+    if (crc32(data) !== crc) throw new Error(`ZIP 条目校验失败（CRC 不符）: ${safe}`);
+
+    out.push({ name: safe, data });
+  }
+  return out;
+}

package/src/modules/entries/service.js

@@ -9,11 +9,12 @@ import { loadStore, mutateStore, snapshotStore } from '../../core/store.js';
 import { assertFieldKey } from '../../core/paths.js';
 import { badInput, conflict, notFound } from '../../core/errors.js';
 import { BOOL_FALSE, BOOL_TRUE, findKvSection, findSection, isSensitiveField, sectionNames } from '../../core/fields.js';
-import { completeness, displaySensitive, serializeEntry } from '../../core/render.js';
+import { completeness, displaySensitive, isBlank, serializeEntry } from '../../core/render.js';
 import { newId, nowIso } from '../../core/ids.js';
 import { decryptValue, encryptValue, isCipherBlob, maskValue } from '../../core/crypto.js';
 import { resolveVaultKey, sensitiveViewer } from '../../core/vault.js';
 import * as att from '../../core/attachments.js';
+import { mdImageIds, rewriteMdImages } from '../../core/mdimages.js';
 import { displayPath } from '../../core/paths.js';
 
 export function mustFindSection(store, ref) {
@@ -225,21 +226,30 @@ export async function getEntry(ref, { mask, section } = {}) {
   if (!sec) throw notFound(`条目 ${entry.id} 指向的栏目已不存在: ${entry.section}`);
   const decrypt = await sensitiveViewer(sec, [entry]);
   const serialized = serializeEntry(sec, entry, { mask: !!mask, decrypt });
-  // 附带 file 字段引用的附件信息：键 = 字段值（附件 id / 文件名），值为名称 / 路径 / 链接。
-  // 一个字段可挂多个附件，所以逐个 id 建表。
+  // 附带附件信息：键 = 附件 id / 文件名，值为名称 / 路径 / 链接。
+  // 两个来源：`file` 字段挂的附件，以及**图文字段正文里内嵌的图片**（`![说明](f_x)`）——
+  // 后者不进来的话，`entry get` 只能打印一串 f_xxx，而人/agent 要的是「这份文件在磁盘哪」。
   const files = {};
+  const putFile = (ref) => {
+    if (!ref || files[ref]) return;
+    const rec = att.findFileRecord(store, ref);
+    if (!rec) return;
+    const links = att.fileLinks(rec);
+    files[ref] = {
+      id: rec.id, name: rec.name, ext: rec.ext, isImage: att.isImageExt(rec.ext),
+      path: displayPath(att.fileRecordAbs(rec)), url: links.url, downloadUrl: links.downloadUrl,
+    };
+  };
   for (const f of sec.fields.filter((x) => x.type === 'file')) {
-    for (const ref of att.fileIdsOf(serialized.values[f.key])) {
-      const rec = att.findFileRecord(store, ref);
-      if (!rec) continue;
-      const links = att.fileLinks(rec);
-      files[ref] = {
-        id: rec.id, name: rec.name, ext: rec.ext, isImage: att.isImageExt(rec.ext),
-        path: displayPath(att.fileRecordAbs(rec)), url: links.url, downloadUrl: links.downloadUrl,
-      };
-    }
+    for (const ref of att.fileIdsOf(serialized.values[f.key])) putFile(ref);
+  }
+  for (const f of sec.fields.filter((x) => x.type === 'md')) {
+    for (const id of mdImageIds(serialized.values[f.key])) putFile(id);
   }
-  return { ...serialized, sectionTitle: sec.title, mask: !!mask, files };
+  // 字段类型随读出来：CLI 渲染要知道哪个值是「图文」，才能把 f_xxx 换成文件名/路径
+  const fieldTypes = {};
+  for (const f of sec.fields) fieldTypes[f.key] = f.type;
+  return { ...serialized, sectionTitle: sec.title, mask: !!mask, files, fieldTypes };
 }
 
 export async function addEntry({ section, title, set, data, tags, 'dry-run': dryRun } = {}) {
@@ -532,8 +542,11 @@ export function renderEntryList(d) {
     lines.push(`  ${e.id}  ${(e.title || '（无名）').padEnd(16)} ${String(e.completeness.ratio).padStart(3)}% 完整度　[${e.section}]`);
     const missing = e.missing.slice(0, 6).map((m) => m.label).join('、');
     if (missing) lines.push(`      未填: ${missing}${e.missing.length > 6 ? ` 等 ${e.missing.length} 项` : ''}`);
-    if (e.completeness?.excluded) {
-      lines.push(`      不填: ${e.excluded.map((m) => m.label).join('、')}（主动跳过，不计入完整度）`);
+    // 「不填」只报**真的空着**的可选字段。可选字段填了值还列出来，会让人以为
+    // 这份数据缺东西（`excluded` 是策略标记，不是空值清单）。
+    const skipped = (e.excluded || []).filter((m) => isBlank(e.values?.[m.key]));
+    if (skipped.length) {
+      lines.push(`      不填: ${skipped.map((m) => m.label).join('、')}（主动跳过，不计入完整度）`);
     }
   }
   lines.push('', '看全部字段: nx-sk entry get <id> --json　或　nx-sk entry fields --section <id>');
@@ -545,26 +558,36 @@ export function renderEntryList(d) {
  * - 附件（`file` 字段，值可能是 id 列表）：解析成「附件名　物理路径」，**几个占几行**
  * - 其它数组（tags 之类）：仍旧一行、顿号连接——不要顺手把它们也拆成多行
  */
-function valueLines(d, v) {
+function valueLines(d, v, type) {
   const asFile = (x) => (d.files && d.files[x] ? `${d.files[x].name}　${d.files[x].path}` : null);
   if (Array.isArray(v) && v.length && v.every((x) => asFile(x))) return v.map(asFile);
   const one = asFile(v);
   if (one) return [one];
   if (Array.isArray(v)) return [v.join('、')];
   if (typeof v === 'boolean') return [v ? '是' : '否'];
-  return [String(v)];
+  // 图文字段：`![说明](f_x)` → `[图片: 说明] 本地路径`。不换的话 CLI 只会吐一串 id，
+  // 而「这个 id 对应哪个文件」正是读的人唯一想知道的。缺附件时保留醒目的「图片缺失」。
+  const s = String(v);
+  const text = type === 'md' ? rewriteMdImages(s, (id) => d.files?.[id] || null) : s;
+  // 多行正文（YAML / Dockerfile / 一段说明）按行拆开再回填缩进。
+  // 不拆的话只有第一行带着键名列宽，后面每一行都从第 0 列开始 ——
+  // 一段 40 行的清单打印出来像"掉出了表格"，人眼完全没法对。
+  return text.includes('\n') ? text.split('\n') : [text];
 }
 
 export function renderEntryGet(d) {
   const c = d.completeness || {};
+  // 只算**真的空着**的可选字段：填了值的可选字段不属于「跳过」，
+  // 否则一份填满的资料会被报成「另有 7 项已标不填」，自相矛盾。
+  const skipped = (d.excluded || []).filter((m) => isBlank(d.values?.[m.key]));
   const lines = [
     `${d.title || d.id}（${d.id}）· 栏目 ${d.section} · 完整度 ${c.filled}/${c.total} = ${c.ratio}%`
-    + (c.excluded ? ` · 另有 ${c.excluded} 项已标不填` : '')
+    + (skipped.length ? ` · 另有 ${skipped.length} 项已标不填` : '')
     + `${d.mask ? ' · 已打码' : ''}`,
   ];
   for (const [k, v] of Object.entries(d.values)) {
     if (v === null) continue;
-    const rendered = valueLines(d, v);
+    const rendered = valueLines(d, v, d.fieldTypes?.[k]);
     lines.push(`  ${k.padEnd(24)} ${rendered[0]}`);
     for (const extra of rendered.slice(1)) lines.push(`  ${' '.repeat(24)} ${extra}`);
   }
@@ -573,9 +596,9 @@ export function renderEntryGet(d) {
   }
   // 「不填」和「未填」必须分开说：混在一起会让人以为这些字段还欠着，
   // 而它们恰恰是用户主动决定跳过的。
-  if (d.excluded?.length) {
-    lines.push('', `不填（${d.excluded.length}）· 主动跳过、不计入完整度: `
-      + d.excluded.map((m) => `${m.label}(${m.key}｜${m.fillLabel || m.fill})`).join('、'));
+  if (skipped.length) {
+    lines.push('', `不填（${skipped.length}）· 主动跳过、不计入完整度: `
+      + skipped.map((m) => `${m.label}(${m.key}｜${m.fillLabel || m.fill})`).join('、'));
   }
   return lines.join('\n');
 }