@jspg-ai/coding-bb 0.0.1

package/cbb/lib/wiki/convert.js

@@ -0,0 +1,464 @@
+#!/usr/bin/env node
+
+/**
+ * Markdown → Confluence Storage XHTML 转换器。
+ *
+ * 将 design.md 风格的 Markdown 转换为 Confluence Storage Format XHTML，
+ * 支持 mermaid/plantuml 图表宏、代码块、表格、列表等常用元素。
+ *
+ * 采用"提取→处理→还原"的分阶段流水线架构：
+ *   1. 提取保护：代码块、行内代码 → 占位符
+ *   2. 结构转换：标题、表格、列表、分割线
+ *   3. 内联转换：粗体、斜体、链接、图片
+ *   4. 还原注入：占位符 → Confluence 宏 / XHTML 标签
+ *   5. 收尾：段落包裹、XHTML 清理
+ */
+
+const { applyMermaidGuard } = require('./mermaid-guard');
+
+// ── 语言映射表（参考 vai-cli extract-code.js） ─────────
+
+const LANG_MAP = {
+  json: 'js', jsonc: 'js', js: 'js', javascript: 'js', jsx: 'js', mjs: 'js', cjs: 'js',
+  ts: 'js', typescript: 'js', tsx: 'js', mts: 'js',
+  bash: 'bash', sh: 'bash', shell: 'bash', zsh: 'bash', dockerfile: 'bash', makefile: 'bash',
+  py: 'py', python: 'py', python3: 'py',
+  yml: 'yaml', yaml: 'yaml',
+  html: 'html', htm: 'html', xhtml: 'html', xml: 'xml', svg: 'xml', vue: 'html',
+  css: 'css', scss: 'css', sass: 'css', less: 'css',
+  java: 'java', kt: 'java', kotlin: 'java', groovy: 'groovy', gradle: 'groovy',
+  c: 'c++', cpp: 'c++', 'c++': 'c++', h: 'c++', hpp: 'c++',
+  cs: 'c#', csharp: 'c#', 'c#': 'c#',
+  rb: 'ruby', ruby: 'ruby',
+  php: 'php',
+  pl: 'perl', perl: 'perl',
+  sql: 'sql', mysql: 'sql', pgsql: 'sql', plsql: 'sql',
+  scala: 'scala',
+  vb: 'vb', vbnet: 'vb',
+  ps1: 'powershell', powershell: 'powershell', pwsh: 'powershell',
+  diff: 'diff', patch: 'diff',
+  md: 'none', markdown: 'none', txt: 'none', text: 'none',
+  go: 'none', golang: 'none', rust: 'none', rs: 'none', swift: 'none', dart: 'none',
+  r: 'none', lua: 'none', haskell: 'none', elixir: 'none',
+  terraform: 'none', tf: 'none', graphql: 'none',
+};
+
+function resolveLang(lang) {
+  const lower = (lang || '').toLowerCase();
+  return LANG_MAP[lower] || 'none';
+}
+
+// ── 工具函数 ──────────────────────────────────────────
+
+function escapeXml(str) {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function escapeCdata(str) {
+  // CDATA 不能包含 ]]> 序列
+  return str.replace(/]]>/g, ']]]]><![CDATA[>');
+}
+
+// ── 主转换函数 ────────────────────────────────────────
+
+/**
+ * 将 Markdown 转换为 Confluence Storage XHTML
+ * @param {string} markdown - Markdown 源码
+ * @returns {string} Confluence Storage XHTML
+ */
+function markdownToXhtml(markdown) {
+  // 统一换行符
+  let html = markdown.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+
+  // ── 阶段 1: 提取代码块 ──
+  const codeBlocks = [];
+  html = html.replace(/```(\w*)\n([\s\S]*?)```/g, (match, lang, code) => {
+    codeBlocks.push({ language: lang || '', content: code });
+    return `__CODE_BLOCK_${codeBlocks.length - 1}__`;
+  });
+
+  // ── 阶段 2: 提取行内代码 ──
+  const inlineCodes = [];
+  html = html.replace(/`([^`]+)`/g, (match, code) => {
+    inlineCodes.push(code);
+    return `__INLINE_CODE_${inlineCodes.length - 1}__`;
+  });
+
+  // ── 阶段 3: 提取链接和图片（保护 URL 中的特殊字符） ──
+  // 图片必须在链接之前提取，因为 ![...](...) 会先被链接正则匹配
+  const links = [];
+  html = html.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (match, alt, url) => {
+    links.push({ text: alt, url, type: 'image' });
+    return `__IMAGE_${links.length - 1}__`;
+  });
+  html = html.replace(/\[([^\]]*)\]\(([^)]+)\)/g, (match, text, url) => {
+    links.push({ text, url, type: 'link' });
+    return `__LINK_${links.length - 1}__`;
+  });
+
+  // ── 阶段 3.4: 提取 Confluence 安全 HTML 标签（白名单） ──
+  // Confluence Storage Format 支持少量行内 HTML 标签（如 <font>、<span>），
+  // 在 Stage 3.5 全量转义前先提取为占位符，避免被错误转义。
+  const SAFE_HTML_TAGS = ['font', 'span', 'b', 'i', 'strong', 'em', 'del', 'sub', 'sup', 'u', 'br', 'mark'];
+  const safeTags = [];
+  const safeTagRegex = new RegExp(`</?(?:${SAFE_HTML_TAGS.join('|')})(?:\\s[^>]*?)?/?>`, 'gi');
+  html = html.replace(safeTagRegex, (match) => {
+    safeTags.push(match);
+    return `__SAFE_HTML_${safeTags.length - 1}__`;
+  });
+
+  // ── 阶段 3.5: 转义原始文本中的 & 和 < ──
+  // 此时代码块、行内代码、链接、图片、安全 HTML 标签均已提取为占位符，
+  // 剩余文本中的 & 和 < 均为字面字符，需要转义
+  html = html.replace(/&/g, '&amp;');
+  html = html.replace(/</g, '&lt;');
+
+  // ── 阶段 3.5.1: 还原安全 HTML 标签 ──
+  for (let i = safeTags.length - 1; i >= 0; i--) {
+    html = html.split(`__SAFE_HTML_${i}__`).join(safeTags[i]);
+  }
+
+  // ── 阶段 3.6: 包裹 @ 注解（避免被 Confluence 解析为用户提及） ──
+  // 仅匹配行首或空白后的 @Word，避免误处理邮箱（name@domain 中的 @ 前是 . 或字母）
+  html = html.replace(/(^|\s)@([A-Za-z]\w*)/g, '$1<code>@$2</code>');
+
+  // ── 阶段 4: 处理表格 ──
+  html = processTables(html);
+
+  // ── 阶段 5: 粗体/斜体/删除线 ──
+  html = html.replace(/\*\*\*(.+?)\*\*\*/g, '<strong><em>$1</em></strong>');
+  html = html.replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>');
+  html = html.replace(/(?<!\*)\*([^*\n]+?)\*(?!\*)/g, '<em>$1</em>');
+  html = html.replace(/~~(.+?)~~/g, '<del>$1</del>');
+
+  // ── 阶段 6: 标题（# → <h1>） ──
+  html = html.replace(/^#### (.+)$/gm, '<h4>$1</h4>');
+  html = html.replace(/^### (.+)$/gm, '<h3>$1</h3>');
+  html = html.replace(/^## (.+)$/gm, '<h2>$1</h2>');
+  html = html.replace(/^# (.+)$/gm, '<h1>$1</h1>');
+
+  // ── 阶段 7: 列表 ──
+  html = processLists(html);
+
+  // ── 阶段 8: 分割线 ──
+  html = html.replace(/^[-*_]{3,}\s*$/gm, '<hr/>');
+
+  // ── 阶段 9: 还原链接和图片 ──
+  for (let i = links.length - 1; i >= 0; i--) {
+    const link = links[i];
+    if (link.type === 'image') {
+      html = html.split(`__IMAGE_${i}__`).join(`<ac:image><ri:url ri:value="${escapeXml(link.url)}"/></ac:image>`);
+    } else {
+      html = html.split(`__LINK_${i}__`).join(`<a href="${escapeXml(link.url)}">${escapeXml(link.text)}</a>`);
+    }
+  }
+
+  // ── 阶段 10: 还原行内代码 ──
+  for (let i = inlineCodes.length - 1; i >= 0; i--) {
+    html = html.split(`__INLINE_CODE_${i}__`).join(`<code>${escapeXml(inlineCodes[i])}</code>`);
+  }
+
+  // ── 阶段 11: 还原代码块为 Confluence 宏 ──
+  for (let i = codeBlocks.length - 1; i >= 0; i--) {
+    const block = codeBlocks[i];
+    const langLower = block.language.toLowerCase();
+    let macro;
+
+    if (langLower === 'mermaid') {
+      const guardResult = applyMermaidGuard(block.content.trim());
+      // 品牌主色：未自带 %%{init 时注入（尊重作者自定义）
+      const brandInit = "%%{init: {'themeVariables': {'primaryColor': '#2698F7'}}}%%";
+      const finalContent = guardResult.fixed.includes('%%{init')
+        ? guardResult.fixed
+        : `${brandInit}\n${guardResult.fixed}`;
+      macro = `<ac:structured-macro ac:name="mermaid-macro" ac:schema-version="1"><ac:plain-text-body><![CDATA[${escapeCdata(finalContent)}]]></ac:plain-text-body></ac:structured-macro>`;
+    } else if (langLower === 'plantuml') {
+      const content = block.content.trim();
+      const skinparamLine = 'skinparam backgroundColor #2698F7';
+      let finalContent;
+      if (content.includes('skinparam backgroundColor')) {
+        // 用户已自定义 skinparam，尊重作者选择
+        finalContent = content;
+      } else if (/@startuml\b/.test(content)) {
+        // 在 @startuml 之后插入品牌 skinparam
+        finalContent = content.replace(/(@startuml\b[^\n]*)/, `$1\n${skinparamLine}`);
+      } else {
+        // 无 @startuml，直接放顶部
+        finalContent = `${skinparamLine}\n${content}`;
+      }
+      macro = `<ac:structured-macro ac:name="plantuml" ac:schema-version="1"><ac:parameter ac:name="type">plantuml</ac:parameter><ac:plain-text-body><![CDATA[${escapeCdata(finalContent)}]]></ac:plain-text-body></ac:structured-macro>`;
+    } else {
+      const confluenceLang = resolveLang(block.language);
+      macro = `<ac:structured-macro ac:name="code" ac:schema-version="1"><ac:parameter ac:name="language">${confluenceLang}</ac:parameter><ac:parameter ac:name="theme">Midnight</ac:parameter><ac:parameter ac:name="linenumbers">true</ac:parameter><ac:plain-text-body><![CDATA[${escapeCdata(block.content.trim())}]]></ac:plain-text-body></ac:structured-macro>`;
+    }
+
+    html = html.split(`__CODE_BLOCK_${i}__`).join(macro);
+  }
+
+  // ─ 阶段 11.5: 块级元素隔离 ──
+  // 在列表、表格等块级元素前后加空行，防止段落包裹时 <p> 内嵌套块级元素
+  html = html.replace(/(<\/?(?:ul|ol|table|thead|tbody|tr|th|td)\b[^>]*>)/g, '\n$1\n');
+  html = html.replace(/\n{3,}/g, '\n\n');
+
+  // ─ 阶段 12: 段落包裹 ─
+  // 将剩余的非空行（未被其他标签包裹的）用 <p> 包裹
+  const lines = html.split('\n');
+  const resultLines = [];
+  let paraLines = [];
+
+  function flushPara() {
+    if (paraLines.length > 0) {
+      resultLines.push('<p>' + paraLines.join('\n') + '</p>');
+      paraLines = [];
+    }
+  }
+
+  let insideMacro = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // 在 ac:structured-macro 块内部，直接输出，不做段落包裹
+    if (insideMacro) {
+      resultLines.push(line);
+      if (trimmed.includes('</ac:structured-macro>')) {
+        insideMacro = false;
+      }
+      continue;
+    }
+
+    // 检测 ac:structured-macro 开标签
+    if (/^<ac:structured-macro\b/.test(trimmed)) {
+      flushPara();
+      resultLines.push(line);
+      if (!trimmed.includes('</ac:structured-macro>')) {
+        insideMacro = true;
+      }
+    } else if (/^<\/?(h[1-6]|table|thead|tbody|tr|th|td|ul|ol|li|hr|ac:image|blockquote|div|pre|ac:link)\b/.test(trimmed) ||
+        /^<hr\/>$/.test(trimmed)) {
+      // 已经是块级标签的行，直接输出并刷新段落缓冲
+      flushPara();
+      resultLines.push(line);
+    } else if (trimmed === '') {
+      flushPara();
+      resultLines.push('');
+    } else {
+      paraLines.push(line);
+    }
+  }
+  flushPara();
+
+  html = resultLines.join('\n');
+
+  // ─ 阶段 12.5: 去除标签间多余空白 ─
+  // Stage 11.5 为了避免 <p> 嵌套块级元素，强制在块级标签前后加换行
+  // 段落包裹完成后，需要把这些"占位换行"清掉，让 XHTML 输出更紧凑
+  html = html.replace(/>\s+</g, '><');
+  // 同时清理"行内文本\n<块级标签"之间的换行（如 <li>foo\n<ul>...）
+  html = html.replace(/(\S)\n+(<ul\b|<ol\b|<table\b)/g, '$1$2');
+
+  // ─ 阶段 13: XHTML 清理 ─
+  // 清理多余空行
+  html = html.replace(/\n{3,}/g, '\n\n');
+  // 确保 self-closing 标签正确
+  html = html.replace(/<hr>/g, '<hr/>');
+  html = html.replace(/<br>/g, '<br/>');
+
+  return html.trim();
+}
+
+// ── 表格处理 ──────────────────────────────────────────
+
+function processTables(html) {
+  // 匹配 Markdown 表格：至少一行表头 + 一行分隔符 + 零或多行数据
+  const tableRegex = /(?:^\|.+\|$\n?)+/gm;
+
+  return html.replace(tableRegex, (tableBlock) => {
+    const lines = tableBlock.trim().split('\n');
+    if (lines.length < 2) return tableBlock; // 至少需要表头和分隔行
+
+    // 检查是否有分隔行（第二行必须包含 |---| 模式）
+    const sepLine = lines[1] || '';
+    if (!/^\|[\s\-:]+\|/.test(sepLine) && !/^\|[-:\s|]+\|$/.test(sepLine)) {
+      return tableBlock;
+    }
+
+    // 解析对齐方式
+    const aligns = sepLine.split('|').filter(c => c.trim() !== '')
+      .map(c => {
+        const trimmed = c.trim();
+        if (trimmed.startsWith(':') && trimmed.endsWith(':')) return 'center';
+        if (trimmed.endsWith(':')) return 'right';
+        return 'left';
+      });
+
+    // 表头行
+    const headerCells = (lines[0] || '').split('|').filter(c => c.trim() !== '')
+      .map(c => c.trim());
+
+    // 数据行
+    const dataRows = lines.slice(2);
+
+    let tableHtml = '<table><thead><tr>';
+    headerCells.forEach((cell, idx) => {
+      const align = aligns[idx] ? ` style="text-align:${aligns[idx]}"` : '';
+      tableHtml += `<th${align}>${cell}</th>`;
+    });
+    tableHtml += '</tr></thead><tbody>';
+
+    dataRows.forEach(row => {
+      const cells = row.split('|').filter(c => c.trim() !== '').map(c => c.trim());
+      tableHtml += '<tr>';
+      cells.forEach((cell, idx) => {
+        const align = aligns[idx] ? ` style="text-align:${aligns[idx]}"` : '';
+        tableHtml += `<td${align}>${cell}</td>`;
+      });
+      tableHtml += '</tr>';
+    });
+
+    tableHtml += '</tbody></table>';
+    return tableHtml;
+  });
+}
+
+// ── 列表处理 ──────────────────────────────────────────
+
+/**
+ * 解析列表块为树形结构
+ * @param {string[]} blockLines - 列表块的所有行（含缩进）
+ * @returns {{type: string, items: object[]}|null}
+ */
+function parseListBlock(blockLines) {
+  // 栈：每个条目 { indent, container, listType }
+  // container 是父节点（item 或 root）
+  const root = { children: null };
+  const stack = [{ indent: -1, container: root }];
+  let currentParaIdx = -1;
+
+  for (const line of blockLines) {
+    if (line.trim() === '') {
+      // 空行：当前段结束
+      currentParaIdx = -1;
+      continue;
+    }
+
+    const itemMatch = line.match(/^(\s*)([-*+]|\d+\.)\s+(.*)$/);
+    if (itemMatch) {
+      const indent = itemMatch[1].length;
+      const marker = itemMatch[2];
+      const content = itemMatch[3];
+      const listType = /^\d+\.$/.test(marker) ? 'ol' : 'ul';
+
+      // 弹出缩进 ≥ 当前的所有栈帧
+      while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+        stack.pop();
+      }
+
+      const parent = stack[stack.length - 1].container;
+      // 复用或创建父节点的 list
+      let list = null;
+      if (parent.children && parent.children.type === listType) {
+        list = parent.children;
+      } else {
+        list = { type: listType, items: [] };
+        parent.children = list;
+      }
+
+      const item = { content, paragraphs: [], children: null };
+      list.items.push(item);
+
+      stack.push({ indent, container: item });
+      currentParaIdx = -1;
+    } else {
+      // 延续行（缩进但不是列表标记）
+      const indent = line.match(/^(\s*)/)[1].length;
+      const text = line.trim();
+
+      // 找最近一个 indent < current 的栈帧（其 container 是 item）
+      let target = null;
+      for (let k = stack.length - 1; k > 0; k--) {
+        if (stack[k].indent < indent) {
+          target = stack[k].container;
+          break;
+        }
+      }
+      if (!target) continue;
+
+      if (currentParaIdx === -1) {
+        target.paragraphs.push(text);
+        currentParaIdx = target.paragraphs.length - 1;
+      } else {
+        target.paragraphs[currentParaIdx] += '\n' + text;
+      }
+    }
+  }
+
+  return root.children;
+}
+
+function renderListHtml(list) {
+  if (!list) return '';
+  const items = list.items.map(item => {
+    let html = '<li>' + item.content;
+    if (item.paragraphs.length > 0) {
+      html += item.paragraphs.map(p => '<p>' + p + '</p>').join('');
+    }
+    if (item.children) {
+      html += renderListHtml(item.children);
+    }
+    html += '</li>';
+    return html;
+  }).join('');
+  return `<${list.type}>${items}</${list.type}>`;
+}
+
+function processLists(html) {
+  const lines = html.split('\n');
+  const result = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!/^\s*([-*+]|\d+\.)\s+/.test(line)) {
+      result.push(line);
+      i++;
+      continue;
+    }
+
+    // 收集整个列表块（含子项、延续行、空行）
+    const block = [line];
+    let j = i + 1;
+    while (j < lines.length) {
+      const l = lines[j];
+      if (l.trim() === '') {
+        // 空行：前看是否仍是列表（含延续行）
+        let k = j + 1;
+        while (k < lines.length && lines[k].trim() === '') k++;
+        if (k < lines.length && (/^\s*([-*+]|\d+\.)\s+/.test(lines[k]) || /^\s+\S/.test(lines[k]))) {
+          block.push(l);
+          j = k;
+        } else {
+          break;
+        }
+      } else if (/^\s*([-*+]|\d+\.)\s+/.test(l) || /^\s+\S/.test(l)) {
+        block.push(l);
+        j++;
+      } else {
+        break;
+      }
+    }
+
+    const list = parseListBlock(block);
+    result.push(list ? renderListHtml(list) : block.join('\n'));
+    i = j;
+  }
+
+  return result.join('\n');
+}
+
+module.exports = { markdownToXhtml };

package/cbb/lib/wiki/index.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+/**
+ * Wiki 发布命令 — 将 Markdown 文件发布到Confluence Wiki。
+ *
+ * 用法:
+ *   cbb wp <file> --page-id <id>               更新已有页面
+ *   cbb wp <file> --parent-id <id> --title "..." 创建新页面
+ *   cbb wp <file> --page-id <id> --dry-run      仅输出 XHTML，不发布
+ *
+ * 认证:
+ *   环境变量 CBB_WIKI_EMAIL + CBB_WIKI_TOKEN，或 ~/.cbb/wiki-config.json
+ *   凭据与 it-wiki-mcp / vai-wiki 相同（个人访问令牌 + 邮箱格式用户名）
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { markdownToXhtml } = require('./convert');
+const { getPage, createPage, updatePage, buildPageUrl } = require('./api-client');
+
+// ── 参数解析 ──────────────────────────────────────────
+
+function parseArgs(argv) {
+  // --help / -h 优先处理，避免误触发"缺少 file"或"未知选项"错误
+  if (argv.length === 1 && (argv[0] === '--help' || argv[0] === '-h')) {
+    return { help: true, pos: [], opts: {} };
+  }
+
+  const pos = [];
+  const opts = {};
+  let i = 0;
+
+  while (i < argv.length) {
+    const arg = argv[i];
+    // --flag=value 形式：单参数内同时包含名和值，避免下面误把 --page-id=value 中的 "=value" 当成位置参数
+    if (arg.startsWith('--') && arg.includes('=')) {
+      const eq = arg.indexOf('=');
+      const key = arg.slice(2, eq);
+      const value = arg.slice(eq + 1);
+      applyKnownOption(key, value, opts);
+      i++;
+      continue;
+    }
+    if (arg === '--page-id') {
+      opts.pageId = argv[++i];
+    } else if (arg === '--parent-id') {
+      opts.parentId = argv[++i];
+    } else if (arg === '--title') {
+      opts.title = argv[++i];
+    } else if (arg === '--file') {
+      opts.file = argv[++i];
+    } else if (arg === '--dry-run') {
+      opts.dryRun = true;
+    } else if (!arg.startsWith('--')) {
+      pos.push(arg);
+    } else {
+      // 未知选项：若像 --key=value 形式但 value 缺失，提示用户用空格分隔
+      if (arg.startsWith('--') && /=.?$/.test(arg)) {
+        const m = arg.match(/^--([\w-]+)=?$/);
+        const key = m ? m[1] : arg.slice(2);
+        log(`未知选项: ${arg}`, 'warn');
+        log(`提示：选项 --${key} 后面接的是另一个选项名或为空。`, 'warn');
+        log(`      --flag 的值必须用空格分隔：--${key} <value>（或写为 --${key}=<value>，但不要漏 value）`, 'warn');
+        log(`      执行 \`cbb wp --help\` 查看完整用法`, 'warn');
+        process.exit(1);
+      }
+      log(`未知选项: ${arg}`, 'warn');
+      log('提示：参数格式为 --flag <value> 或 --flag=<value>，执行 `cbb wp --help` 查看完整用法', 'warn');
+      process.exit(1);
+    }
+    i++;
+  }
+
+  // 位置参数 <file> 仅在用户未显式 --file 时生效，避免覆盖解析结果
+  if (opts.file === undefined) {
+    opts.file = pos[0];
+  }
+
+  if (!opts.file) {
+    log('用法: cbb wp <file> [--page-id <id> | --parent-id <id> --title "..."] [--dry-run]', 'warn');
+    log('提示：参数格式为 --flag <value> 或 --flag=<value>，执行 `cbb wp --help` 查看完整用法', 'warn');
+    process.exit(1);
+  }
+
+  return { pos, opts };
+}
+
+// 处理 --key=value 形式的非位置类选项（--file/page-id/parent-id/title 仍以位置形式解析，保持原行为）
+function applyKnownOption(key, value, opts) {
+  if (key === 'page-id') opts.pageId = value;
+  else if (key === 'parent-id') opts.parentId = value;
+  else if (key === 'title') opts.title = value;
+  else if (key === 'file') opts.file = value;
+  else if (key === 'dry-run') opts.dryRun = value === 'false' ? false : true;
+  else log(`未知选项: --${key}`, 'warn');
+}
+
+// ── 工具 ──────────────────────────────────────────────
+
+function showHelp() {
+  log(`cbb wp — 将 Markdown 发布到Confluence Wiki
+
+参数格式：
+  本工具同时支持两种写法，请按习惯任选其一：
+    --flag <value>     GNU 风格（推荐，shell 提示更友好）
+    --flag=<value>     等号风格
+
+  带值选项：--file / --page-id / --parent-id / --title
+  布尔开关：--dry-run（出现即视为 true，不能带值）
+
+用法：
+  cbb wp <file> --page-id <pageId>                     # 更新已有页面
+  cbb wp <file> --page-id=<pageId>                    # 等价写法
+  cbb wp <file> --parent-id <parentId> --title "..."  # 在父页面下创建新页面
+  cbb wp <file> --parent-id=<parentId> --title="..."  # 等价写法
+  cbb wp <file> --page-id <pageId> --dry-run          # 仅输出 XHTML，不发布
+
+示例：
+  cbb wp design.md --page-id 123456
+  cbb wp "D:\\path with space\\design.md" --page-id 123456 --dry-run
+
+认证：环境变量 CBB_WIKI_EMAIL + CBB_WIKI_TOKEN，或 ~/.cbb/wiki-config.json
+       令牌获取: https://wiki.amh-group.com/plugins/tokens/view.action`, 'info');
+}
+
+// ── 工具 ──────────────────────────────────────────────
+
+function log(msg, level) {
+  const colors = { warn: '\x1b[33m', error: '\x1b[31m', success: '\x1b[32m', info: '\x1b[36m' };
+  const prefix = { warn: '⚠', error: '✗', success: '✓', info: 'ℹ' };
+  const color = colors[level] || '';
+  const p = prefix[level] || '';
+  const reset = '\x1b[0m';
+  // 所有日志统一输出到 stderr，确保 stdout 可用于管道/dry-run 纯净输出
+  process.stderr.write(Buffer.from(`${color}${p} ${msg}${reset}\n`, 'utf8'));
+}
+
+// ── 主流程 ────────────────────────────────────────────
+
+async function publish(argv) {
+  const parsed = parseArgs(argv);
+  if (parsed.help) {
+    showHelp();
+    return;
+  }
+  const { opts } = parsed;
+
+  // 1. 验证参数
+  if (!opts.pageId && !(opts.parentId && opts.title)) {
+    log('必须指定 --page-id（更新）或 --parent-id + --title（创建）', 'error');
+    log('用法: cbb wp <file> [--page-id <id> | --parent-id <id> --title "..."] [--dry-run]', 'warn');
+    process.exit(1);
+  }
+
+  // 2. 读取 Markdown 文件
+  const filePath = path.resolve(opts.file);
+  if (!fs.existsSync(filePath)) {
+    log(`文件不存在: ${filePath}`, 'error');
+    process.exit(1);
+  }
+  const markdown = fs.readFileSync(filePath, 'utf-8');
+  if (!markdown.trim()) {
+    log(`文件为空: ${filePath}`, 'error');
+    process.exit(1);
+  }
+
+  // 3. 转换 Markdown → XHTML
+  log('转换 Markdown → Confluence Storage XHTML...', 'info');
+  const xhtml = markdownToXhtml(markdown);
+  log(`转换完成，${xhtml.length} 字符`, 'info');
+
+  // 4. Dry-run 模式：仅输出 XHTML
+  if (opts.dryRun) {
+    // 写入临时文件
+    const tmpFile = path.join(os.tmpdir(), `cbb-dryrun-${Date.now()}.xml`);
+    fs.writeFileSync(tmpFile, xhtml, 'utf-8');
+    process.stdout.write(Buffer.from(xhtml + '\n', 'utf8'));
+    log(`\nXHTML 已保存到: ${tmpFile}`, 'info');
+    return;
+  }
+
+  // 5. 发布
+  let result;
+  if (opts.pageId) {
+    // 更新模式
+    log(`获取页面 ${opts.pageId} 信息...`, 'info');
+    const pageInfo = await getPage(opts.pageId);
+    if (!pageInfo.success) {
+      log(`获取页面失败: ${pageInfo.error}`, 'error');
+      process.exit(1);
+    }
+
+    log(`更新页面: ${pageInfo.data.title} (v${pageInfo.data.version} → v${pageInfo.data.version + 1})`, 'info');
+    result = await updatePage(opts.pageId, pageInfo.data.version, pageInfo.data.title, xhtml);
+  } else {
+    // 创建模式
+    log(`创建页面 "${opts.title}" 在父页面 ${opts.parentId} 下...`, 'info');
+    result = await createPage(opts.title, opts.parentId, xhtml);
+  }
+
+  if (!result.success) {
+    log(`发布失败: ${result.error}`, 'error');
+    if (result.statusCode === 401 || result.statusCode === 403) {
+      log('认证失败。请检查 CBB_WIKI_EMAIL / CBB_WIKI_TOKEN 环境变量或 ~/.cbb/wiki-config.json 配置文件。', 'warn');
+      log('用户名应为邮箱格式（如 jinchuang.zhang@example.com），令牌从 https://wiki.amh-group.com/plugins/tokens/view.action 获取。', 'warn');
+    } else if (result.statusCode === 409) {
+      log('版本冲突 (409)，页面可能已被他人修改，请重试。', 'warn');
+    }
+    process.exit(1);
+  }
+
+  const url = buildPageUrl(result.data);
+  log(`发布成功！页面 ID: ${result.data.id}`, 'success');
+  log(`访问: ${url}`, 'success');
+}
+
+module.exports = { publish, parseArgs, applyKnownOption };