AgentServer/apps/server/src/api-reference/render.ts

// 把 API 协议参考渲染为独立的 HTML 文档（不引用任何外部资源）：后台页面内嵌显示，也用于生成 PDF
import { API_ERRORS, API_EVENTS, API_GROUPS, API_OVERVIEW, API_TYPES, type Endpoint, type Field } from './reference'

export interface RenderOptions {
  /** 文档中示例使用的服务地址 */
  baseUrl: string
  theme: 'light' | 'dark'
  version: string
  generatedAt: Date
}

const esc = (s: string) => s.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]!))
/** 行内代码：`xxx` → <code> */
const inline = (s: string) => esc(s).replace(/`([^`]+)`/g, '<code>$1</code>')
/** 概述条目：`代码`、**加粗**，$BASE 替换为服务地址 */
const marked = (s: string, base: string) => inline(s.replaceAll('$BASE', base)).replace(/\*\*([^*]+)\*\*/g, '<b>$1</b>')
/** "409 session_busy：说明" → 状态码加粗、错误码为代码样式 */
const errorItem = (x: string) => {
  const m = /^(\d{3}) ([a-z_]+)(.*)$/.exec(x)
  return m ? `<li><b>${m[1]}</b> <code>${m[2]}</code>${inline(m[3]!)}</li>` : `<li>${inline(x)}</li>`
}
const anchor = (e: Endpoint) => `${e.method}-${e.path}`.toLowerCase().replace(/[^a-z0-9]+/g, '-')

function fieldTable(fields: Field[], withRequired = true) {
  return `<table class="fields"><thead><tr><th>字段</th><th>类型</th>${withRequired ? '<th>必填</th>' : ''}<th>说明</th></tr></thead><tbody>${
    fields.map(f => `<tr><td><code>${esc(f.name)}</code></td><td><code class="type">${esc(f.type)}</code></td>${withRequired ? `<td>${f.required ? '是' : ''}</td>` : ''}<td>${inline(f.desc)}</td></tr>`).join('')
  }</tbody></table>`
}

function endpoint(e: Endpoint, base: string) {
  return `<section class="endpoint" id="${anchor(e)}">
  <h3><span class="method ${e.method.toLowerCase()}">${e.method}</span><code class="path">${esc(e.path)}</code><span class="summary">${esc(e.summary)}</span></h3>
  ${e.desc ? `<p>${inline(e.desc)}</p>` : ''}
  ${e.query?.length ? `<h4>查询参数</h4>${fieldTable(e.query)}` : ''}
  ${e.body?.length ? `<h4>请求体（JSON）</h4>${fieldTable(e.body)}` : ''}
  ${e.bodyNote ? `<h4>请求体</h4><p>${inline(e.bodyNote)}</p>` : ''}
  <h4>响应</h4><p><span class="status">${e.response.status}</span> <code class="type">${esc(e.response.type)}</code>${e.response.desc ? ` — ${inline(e.response.desc)}` : ''}</p>
  ${e.errors?.length ? `<h4>常见错误</h4><ul>${e.errors.map(errorItem).join('')}</ul>` : ''}
  ${e.example ? `<h4>示例</h4><pre>${esc(e.example.replaceAll('$BASE', base))}</pre>` : ''}
</section>`
}

export function renderApiReferenceHtml(o: RenderOptions): string {
  const base = o.baseUrl.replace(/\/+$/, '')
  const date = o.generatedAt.toISOString().slice(0, 10)
  const toc = [
    ['overview', '1. 概述'],
    ...API_GROUPS.map((g, i) => [g.id, `${i + 2}. ${g.title}`]),
    ['event-types', `${API_GROUPS.length + 2}. 事件类型`],
    ['types', `${API_GROUPS.length + 3}. 数据结构`],
    ['errors', `${API_GROUPS.length + 4}. 错误码`],
  ]
  return `<!doctype html>
<html lang="zh-CN" data-theme="${o.theme}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>AgentServer API 协议 ${esc(o.version)}</title>
<style>
:root { --bg:#ffffff; --fg:#1f2328; --muted:#59636e; --border:#d1d9e0; --code-bg:#f6f8fa; --link:#0969da;
  --get:#1a7f37; --post:#0969da; --patch:#9a6700; --delete:#cf222e; }
[data-theme="dark"] { --bg:#1f1f1f; --fg:#cccccc; --muted:#9d9d9d; --border:#3c3c3c; --code-bg:#2b2b2b; --link:#4daafc;
  --get:#3fb950; --post:#58a6ff; --patch:#d29922; --delete:#f85149; }
* { box-sizing: border-box; }
html, body { margin: 0; background: var(--bg); color: var(--fg); }
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Noto Sans CJK SC", "Microsoft YaHei", sans-serif;
  font-size: 13.5px; line-height: 1.65; padding: 32px 40px 64px; max-width: 980px; margin: 0 auto; }
h1 { font-size: 26px; margin: 0 0 4px; }
h2 { font-size: 19px; margin: 36px 0 12px; padding-bottom: 6px; border-bottom: 1px solid var(--border); }
h3 { font-size: 15px; margin: 0 0 8px; display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
h4 { font-size: 12.5px; margin: 14px 0 6px; color: var(--muted); }
p, ul { margin: 6px 0; }
a { color: var(--link); text-decoration: none; }
code, pre { font-family: "JetBrains Mono", "Cascadia Code", Menlo, Consolas, "Noto Sans Mono CJK SC", monospace; font-size: 12px; }
code { background: var(--code-bg); padding: 1px 5px; border-radius: 4px; }
code.type { color: var(--muted); }
pre { background: var(--code-bg); padding: 10px 12px; border-radius: 6px; overflow-x: auto; white-space: pre-wrap; word-break: break-all; margin: 6px 0; }
.meta { color: var(--muted); margin-bottom: 20px; }
.toc { columns: 2; padding-left: 18px; margin: 8px 0 0; }
table { border-collapse: collapse; width: 100%; margin: 6px 0; }
th, td { border: 1px solid var(--border); padding: 5px 8px; text-align: left; vertical-align: top; }
th { background: var(--code-bg); font-weight: 600; white-space: nowrap; }
td code { white-space: nowrap; }
td code.type { white-space: normal; }
.endpoint { border: 1px solid var(--border); border-radius: 8px; padding: 14px 16px; margin: 14px 0; }
.method { font: 700 11.5px/1 sans-serif; color: #fff; padding: 4px 7px; border-radius: 4px; }
.method.get { background: var(--get); } .method.post { background: var(--post); } .method.patch { background: var(--patch); } .method.delete { background: var(--delete); }
code.path { font-size: 13px; background: none; padding: 0; font-weight: 600; }
.summary { color: var(--muted); font-weight: 500; }
.status { font-weight: 700; }
.group-desc { color: var(--muted); }
.no { color: var(--muted); }
@page { size: A4; margin: 14mm 12mm; }
@media print {
  :root, [data-theme="dark"] { --bg:#ffffff; --fg:#1f2328; --muted:#59636e; --border:#d1d9e0; --code-bg:#f6f8fa; --link:#0969da;
    --get:#1a7f37; --post:#0969da; --patch:#9a6700; --delete:#cf222e; }
  body { padding: 0; max-width: none; font-size: 11.5px; -webkit-print-color-adjust: exact; print-color-adjust: exact; }
  .endpoint, table, pre { break-inside: avoid; }
  h2 { break-after: avoid; }
}
</style>
</head>
<body>
<h1>AgentServer 对外 API 协议</h1>
<div class="meta">版本 ${esc(o.version)} · 服务地址 <code>${esc(base)}</code> · 生成于 ${date}</div>

<h2>目录</h2>
<ol class="toc">${toc.map(([id, t]) => `<li><a href="#${id}">${esc(t!.replace(/^\d+\. /, ''))}</a></li>`).join('')}</ol>

<h2 id="overview">1. 概述</h2>
<ul>${API_OVERVIEW.points.map(x => `<li>${marked(x, base)}</li>`).join('')}</ul>
<h4>典型流程</h4>
<ol>${API_OVERVIEW.flow.map(x => `<li>${marked(x, base)}</li>`).join('')}</ol>

${API_GROUPS.map((g, i) => `<h2 id="${g.id}">${i + 2}. ${esc(g.title)}</h2>
${g.desc ? `<p class="group-desc">${inline(g.desc)}</p>` : ''}
${g.endpoints.map(e => endpoint(e, base)).join('\n')}`).join('\n')}

<h2 id="event-types">${API_GROUPS.length + 2}. 事件类型</h2>
<p>事件信封见"数据结构 › AgentEvent"。"落库"为否的事件只在实时事件流中推送，历史事件中只保留对应的 completed 事件。</p>
<table><thead><tr><th>type</th><th>payload</th><th>说明</th><th>落库</th></tr></thead><tbody>
${API_EVENTS.map(e => `<tr><td><code>${esc(e.type)}</code></td><td><code class="type">${esc(e.payload)}</code></td><td>${inline(e.desc)}</td><td>${e.persisted ? '是' : '<span class="no">否</span>'}</td></tr>`).join('\n')}
</tbody></table>

<h2 id="types">${API_GROUPS.length + 3}. 数据结构</h2>
${API_TYPES.map(t => `<h3 id="type-${t.name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}"><code class="path">${esc(t.name)}</code></h3>
${t.desc ? `<p class="group-desc">${inline(t.desc)}</p>` : ''}${fieldTable(t.fields, false)}`).join('\n')}

<h2 id="errors">${API_GROUPS.length + 4}. 错误码</h2>
<table><thead><tr><th>HTTP</th><th>code</th><th>说明</th></tr></thead><tbody>
${API_ERRORS.map(e => `<tr><td>${e.status}</td><td><code>${esc(e.code)}</code></td><td>${inline(e.desc)}</td></tr>`).join('\n')}
</tbody></table>
</body>
</html>`
}