元呈（yotta-present）

跨智能体的通用结果呈现层：AI 输出五花八门、有的难读难复用；元呈在「内容类型 → 呈现形态」之间做判断， 再套元阁统一设计语言，输出可复制的 Markdown / 纯文本（按需附本地 SVG 图）。

使用须知（先做这一步）

本技能按需触发（always-load: false，不常驻）；通过它配置的 yotta-present MCP 常驻（写入客户端 mcpServers 后常驻、新会话工具可用，present_result / present_forms / present_templates 按需调用）。

明确同意门（必须先征得用户同意再做，勿静默执行）：AI 首次使用本技能时，在写入任何客户端配置（mcpServers）或永久记忆（AGENTS.md / 等效全局记忆）之前，先向用户说明将写入什么、为什么，并获得用户明确同意；用户拒绝 → 不写入，直接降级 CLI（yotta_present.py），功能不受影响；用户同意 → 写入后回读核对。已有配置 / 记忆 → 跳过，不重复堆。本技能所需的持久变更仅此两项：① 写入客户端 mcpServers 的 yotta-present server 条目；② 写入下方「永久记忆护栏」。其余全部为本地纯渲染，不改系统、不联网。

# 元呈 yotta-present 输出默认呈现（来源：yotta-present · 元呈）
所有输出一律先用元呈 yotta-present 渲染（present_result / CLI）后再交给用户，不管什么内容形态；prose 正文形态先经元呈转可复制文本。元呈自带 yotta-present MCP（stdio，零依赖，唯一公开 MCP）：AI 首次使用自动把 server 写入客户端 mcpServers（本地 python <技能目录>/scripts/yotta_present_mcp.py），配置后常驻、新会话自动注入；未加载时自动降级 CLI（yotta_present.py），输出一致。

写入步骤（先征得用户同意）：说明将写入的内容与目的 → 获得用户明确同意 → 打开永久记忆文件 → 检查是否已存在 → 没有则原样写入并保存 → 回读核对 → 已有则跳过。若客户端永久记忆不可写 → 显式报告「永久记忆护栏未写入」，不要省略。

宿主 hook 声明

skill-manifest.json 声明 before_send / present_result 要求。宿主支持动作前拦截时可作为强制门禁； 宿主不支持时按 fallback: explicit-unverified 降级，输出中明确标记，不宣称已验证或已强制。

这是什么

一句话：把「一坨 AI 输出」变成「看着舒服、能直接复制」的结果。

何时使用（默认全走，例外显式退回）

默认：凡交付给用户（AI 对外的最终结果），先经元呈「判型 → 选形态 → 渲染」为可复制 Markdown / 纯文本，再输出。

判型（第一步，必做）：把内容归入 8 种形态之一，规则见 references/schema.md；拿不准用 --explain 看理由，或 --form 显式指定。

发送前自检（第二步，必做）：本条是否含清单 / 表格 / 结论 / 汇总？只要含其中一种，就必须先调用 present_result（未加载时用 CLI）再发送。

白名单例外（明确退回原样，不用元呈）：

• 纯代码 / 命令 / CLI 原始输出（tab、换行格式关键）
• 错误堆栈 / 日志（需逐字节原样）
• 超长内容走 --out 落盘，不在对话内整体渲染
• 用户明确「一句话 / 给裸文本」

例外只豁免命中的内容块本身；同一条消息内其余清单 / 表格 / 结论 / 汇总块仍须经元呈渲染。

边界（可关、可退回，不是强制接管）：呈现层是可选增强——用户说「不用元呈 / 给裸文本 / 关掉渲染」 时立即停用并按原样输出；用户或项目给了自己的输出规范时以对方规范为准。启用渲染不会改变内容本身 （只做排版与可复制化），不改写结论、不替用户决策；调用失败时按白名单退回原始文本即可。

渲染通道与平台（channel × platform）：--channel（默认 auto）定「载体族」、--platform 定「族内降级」：plain → r0（保底无色、无 emoji 徽章），webchat/discord/whatsapp → r1（🟢🟡🔴⚪ emoji 徽章 + 引用条 + 分隔线）；r3 = SVG 整卡（开源 demo，见下节）；r2（富文本 HTML）后续版本开放。想强制无色基础 Markdown（如 GitHub 等 sanitize 宿主）→ --channel r0；颜色永不当唯一信息载体（r0 去掉 emoji 后文字徽章仍在）。

R3 整卡（开源 demo，显式启用）：--channel r3 出可编辑 SVG 整卡，支持三种形态 conclusion / metrics / table 与四个场景模板 release（发布结果）/ weekly（数据快报）/ compare（对比评测）/ risk（风险报告，--card <slug> 选用）；可配品牌 token --brand <file>（name / primary / accent / footer / logo；logo 仅本地 PNG/JPEG，不支持 SVG）。整卡文本全部保持 <text>（可在 Inkscape / Figma / 浏览器直接改字改色），Markdown 侧仍附同内容可复制文本（copyable-first，不替代文本）。R3 只走显式通道，不自动启用；不支持形态 / 缺数据会明确报错，不静默降级。

主题（图表 SVG，S7-M2 色板 token 化）：--theme（默认 light）→ dark 深底浅字暗色渲染；其余形态不受主题影响（Markdown 颜色由 emoji / 文字承载，不做真假色切换）。主题 token 一处定义在 references/theme.json（light/dark + 语义色 + 形态主色 + 图表色板，声明式可热更新、社区可贡献）；本地 python scripts/yotta_chart.py --check-contrast 可自查 WCAG 对比度（正文/背景 ≥ 4.5:1）。

形态选择要点：

• 结论 / 评分 / 推荐 → conclusion
• 行列对比 / 罗列 → table
• 事项 / 清单 → checklist（保留 [x] / [ ]）
• 叙述 / 说明 / 长段落 → prose（规整为可复制文本）
• 关键指标 → metrics（必须是对象列表 [{label,value,unit?,tone?}]）；问答 → qa（rows 须为 问题/回答 两列，否则判 table）；多节长内容 → report；数值分布 / 趋势 / 占比 → chart

核心机制（判断层 = 核心深度）

智能体按 ① 内容类型 → ② 呈现形态 → ③ 内容保真门禁 三步选择，再交给元呈渲染：

① 内容类型判定（8 大类）

② 形态选择规则（12 种成品形态；开源基线 8 种 CLI 支持）

• 单个结论 + 少量指标 → 结论卡（conclusion）
• 行列分明、需对比 / 罗列 → 表格（table）
• 事项 / 要点 / 清单 → 清单卡（checklist，支持 [x] / [ ]）
• 叙述 / 说明 / 长段落 → 正文（prose）
• 一组关键指标 → 指标板（metrics）
• 问题 / 回答成对 → 问答卡（qa，rows 须为 问题/回答 两列）
• 多节长内容（标题 + 表 + 指标 + 要点组合）→ 报告（report，含目录）
• 数值分布 / 趋势 / 占比，视觉更能传达时 → 图表（chart，本地 SVG）
• （开源基线外，后续扩展）对比矩阵 / 决策树 / 看板 / 甘特 / 日历 / 脑图 / 多栏报告 / 时间线 / 流程图

兜底：纯文字 → 至少套「正文」美化（层级 + 重点 + 可复制），不让任何输出裸奔。

③ 内容保真门禁（v0.6.0 红线；v0.6.1 增加顺序保真；v0.6.4 增加嵌套结构保真）

• Markdown / 纯文本先解析为顺序块：标题、摘要、段落、列表、表格、引用、代码、问答、图表。
• 候选 form / template 渲染后必须覆盖全部源内容块；覆盖不足自动降级 report-safe，禁止 title-only 静默失败。
• 列表块同时校验嵌套深度与有序 / 无序类型；子项被拍平或列表类型丢失时按不兼容处理，不误报已保留。
• 有书写顺序的输入（Markdown / 纯文本 / 显式 blocks）还会校验块顺序：候选形态顺序不符时按不兼容处理，自动降级 report-safe，避免静默重排。
• JSON 结果返回 fallback（来源 / 目标 / 原因）与 fidelity（源块 / 保留块 / 丢弃块 / 压缩块 / 顺序保真 order_preserved / 建议形态）。
• --explain 必须说明保留了什么、压缩了什么、丢弃了什么、是否降级、为什么选择该形态。
• max_len 是显式取舍：被截断块进入 fidelity.dropped / fidelity.compressed，不假报全量保留。
• Markdown table 与 JSON rows 双兼容；显式指定“更具体”不等于允许丢内容。

确定性判断兜底（未接智能体也能跑）

yotta_present 按输入 JSON 形状自动猜形态（可解释，--explain 返回原因）：

1. 含 chart_data → chart
2. rows 为「问题 / 回答」两列 → qa
3. title + rows + 其他内容段 → report
4. rows → table
5. metrics + 结论 → conclusion；仅 metrics → metrics
6. bullets 成对「问 / 答」→ qa；bullets + 结论 → conclusion；仅 bullets → checklist
7. 仅 verdict / grade → conclusion
8. 兜底 → prose

接了智能体：智能体主动按上面的判断层判型选形态（默认全走）；没接智能体：yotta_present 兜底 + --form 显式指定。

CLI 用法

Windows 用 python，Linux/macOS 用 python3。

# 标准内容对象（JSON 文件 / 字符串）→ 可复制 Markdown（默认）
python3 scripts/yotta_present.py --content '{"title": "结论", "grade": "success", "verdict": "通过", "bullets": ["a", "b"]}'

# 纯文本 / Markdown 输入（自动解析 + 兜底美化）
python3 scripts/yotta_present.py --file result.txt

# 混合 Markdown + 显式形态：内容保真校验；--json 查看 fallback / fidelity
python3 scripts/yotta_present.py --file result.txt --form checklist --json

# 纯文本输出（复制到 Word / 邮件）
python3 scripts/yotta_present.py --content '<同上>' --text

# 显式指定形态 + 附判断说明
python3 scripts/yotta_present.py --content '<同上>' --form report --explain

# 图表形态：默认 Markdown 内嵌 data URI（自包含可复制）；--svg 时写本地 SVG + 路径引用
python3 scripts/yotta_present.py --content '{"chart_data": {"chart": "pie", "labels": ["A", "B"], "data": [3, 1]}}' --svg out/pie.svg

# 完整 JSON 结果（程序消费）/ 写文件
python3 scripts/yotta_present.py --content '<同上>' --json
python3 scripts/yotta_present.py --content '<同上>' --out result.md --both

# 平台自适应：Discord/WhatsApp（表格转列表、标题转加粗）/ 纯文本命令行
python3 scripts/yotta_present.py --content '<同上>' --platform discord
python3 scripts/yotta_present.py --content '<同上>' --platform plain

# 渲染通道（默认 auto：plain→r0 去 emoji、其余→r1 emoji 增强）；强制无色基础 Markdown
python3 scripts/yotta_present.py --content '<同上>' --channel r0
# R3 整卡（开源 demo）：三形态 + 四场景模板，写可编辑 SVG；不带 --svg 时内嵌 data URI
python3 scripts/yotta_present.py --content '{"title":"发布结果","grade":"success","verdict":"全链收口","metrics":[{"label":"回归","value":233,"unit":"项"}]}' --channel r3 --form conclusion --card release --svg out/release.svg
python3 scripts/yotta_present.py --content '{"title":"数据快报","metrics":[{"label":"新增","value":186,"unit":"次","tone":"up"}]}' --channel r3 --card weekly --theme dark
# 品牌 token（name/primary/accent/footer/logo；logo 仅 PNG/JPEG）
python3 scripts/yotta_present.py --content '<同上>' --channel r3 --card release --brand references/brand.example.json
# 主题（图表暗色渲染）：--theme dark（默认 light）
python3 scripts/yotta_present.py --content '{"chart_data": {"chart": "bar", "labels": ["A", "B"], "data": [3, 5]}}' --form chart --theme dark --svg out/bar-dark.svg

# 命名场景模板：漏洞报告 / 问答 / 状态一句话（一次定义多处复用）
python3 scripts/yotta_present.py --content '{"title": "漏洞", "grade": "danger", "verdict": "高危", "rows": [["注入点", "POST /demo.php"]], "steps": ["复现步骤"], "code": "POST /demo.php HTTP/1.1", "fixes": ["参数化查询"]}' --template vuln_report

# 长度熔断（省 token）：先压缩列表、再降标题、最后截断，保留结论
python3 scripts/yotta_present.py --content '<同上>' --max-len 800

# 形态 / 模板清单 / 版本
python3 scripts/yotta_present.py --list-forms
python3 scripts/yotta_present.py --list-templates
python3 scripts/yotta_present.py --list-cards
python3 scripts/yotta_present.py --version

退出码：0 = 成功；1 = 无输入 / 读取错误；2 = 内容校验或渲染错误（含 --svg 用在非图表 / 非 R3 通道）。

MCP：AI 自动接入（yotta-present）

本技能只提供一个公开 MCP server：yotta-present（scripts/yotta_present_mcp.py，零依赖、数据不出本机）。 基于 MCP 最新协议 2026-07-28（无状态时代；向后兼容 2025-11-25 及更早握手客户端）。 纯图表不需要单独配置另一个 MCP server——present_result 的 chart 形态（chart_data） 直接复用 12 图内核。

AI 首次使用本技能时负责自动完成配置，用户无需手动改 mcpServers：

1. 检查当前客户端的 mcpServers 是否已有 yotta-present 条目；已有 → 直接使用。
2. 没有 → 自动写入下面这一条 server 配置：

   {
     "mcpServers": {
       "yotta-present": {
         "command": "python",
         "args": ["<技能目录>/scripts/yotta_present_mcp.py"]
       }
     }
   }
   

   <技能目录> = 本技能实际安装目录，不要写死盘符路径；Windows 用 python，Linux/macOS 用 python3。

3. 提醒用户：改 mcpServers 后多数客户端需重启 / 重载一次 MCP server 才生效；加载后应看到 present_result / present_forms / present_templates 三个工具。
4. 降级兜底（重要）：若客户端未暴露 MCP 工具 / 无法改配置 / server 未加载，自动降级 CLI（内核同一套、输出一致）：python <技能目录>/scripts/yotta_present.py ...。

永久记忆护栏：见顶部「## 使用须知」节；首次使用照顶部执行写入。

MCP 工具：

• present_result：默认 schema 只列 content（必填）/ form / template / output(md|text|both|json) / explain / options。高级参数放入 options：platform / channel / theme / card（R3 整卡模板）/ brand（品牌 token 文件）/ max_len / bold_keys / title / svg；旧版顶层高级参数继续兼容。JSON 输出包含 fallback 与 fidelity：其中 requested_form_preserved 表示请求形态是否保真，content_preserved 表示最终输出是否保留全部内容；R3 输出额外含 card（含 svg / path / data_uri / sections）。form=chart + chart_data 复用 12 图内核。
• present_forms：列出开源基线 8 种形态（只读）。
• present_templates：列出命名场景模板骨架（vuln_report/faq/status，只读）。

可选配套技能：元真 yotta-humanize（去 AI 味）

元呈本身零依赖。当 prose 正文读起来「AI 腔」、读着不自然时，可配装 yotta-humanize 让文本更自然。 它不是必需依赖；未装时直接用元呈的可复制结果即可。

AI 使用流程（自己检测，不假定已装）：

1. 判断是否需要去 AI 味：仅当 prose 明显 AI 腔、且用户可能受益时才做；普通可复制结果直接交付。
2. 检测是否已安装：看当前客户端技能 / 规则目录里是否已有 yotta-humanize 技能（即存在 yotta-humanize/SKILL.md 与 scripts/yotta_humanize.py）。
3. 已安装 → 把元呈渲染后的 prose 文本交给它去味，再交给用户。
4. 未安装 → 提示用户：这是可选增强，如需去味可安装，命令：npx -y @yottameta/yotta-humanize --agent <agent-name>（或见其 README 的 git clone / ZIP / install.sh）；不要替用户强制安装，不要默认它已存在；用户装好后 AI 再使用。

常见问题 FAQ（速查）

常见报错与避坑见 references/faq.md：

• 想带徽章 / 裁决 → 用标准内容对象 JSON（{title, grade, verdict, bullets}），纯文本无法提取徽章；
• 表格列名 → 用 rows 对象列表键或二维数组 + headers（columns 不支持）；
• 图表 → 必须传 chart_data（{chart, labels, data}）；--svg 仅图表形态有效；
• 形态不对 → 显式 --form 指定，或 --explain 看判断理由；
• 显式形态不兼容 → 自动降级 report-safe，fallback / fidelity 说明取舍；
• Markdown 表格 → 可直接传入，也可用 JSON rows（结构化推荐）；
• max_len 截断 → fidelity.dropped / fidelity.compressed 明确列出被截断块；
• MCP 未加载 → 检查 mcpServers 并重启会话，否则自动降级 CLI（输出一致）。
• 想去掉 emoji / 颜色 → --channel r0（plain 平台自动即 r0）；R2 高级美化通道后续版本开放。
• 要出图 / 发卡片 → --channel r3 --form conclusion|metrics|table（可加 --card release|weekly|compare|risk、--brand <file>；--svg out.svg 写文件，缺省内嵌 data URI）。
• R3 报「不支持形态 / 缺数据」→ 整卡只支持三形态，且 metrics 卡需 metrics、table 卡需 rows；不会静默降级成别的形态。

边界

• 不做图表工具：图表只是呈现形态之一；不做图表编辑器 / BI / 数据分析。
• copyable-first：Markdown + 纯文本双输出；SVG 仅作可选增强，不阻塞可复制。
• R3 整卡边界：只做 conclusion / metrics / table 三形态（四场景模板为预设）；文本保持可编辑 <text>；logo 仅本地 PNG/JPEG 内嵌，不支持 SVG logo / 外链字体 / 脚本 / <foreignObject>；默认空品牌、不默认打任何水印。
• 数据不出本机：只在本机拼字符串 / SVG，不联网、不调远程渲染服务；与被扫描内容联动时不上传。
• 不替代判断：元呈只负责「呈现」，不改写内容、不替用户做价值判断。
• 本地零依赖：Python 3.8+ 标准库；0 matplotlib / canvas / 远程渲染。
• 开源与许可：本技能按 MIT 开源，能力开放；商标与品牌声明见 NOTICE。