🆕 v0.6.5：增加发送前自检和块级例外边界；fidelity 区分 requested_form_preserved（请求形态保真）与 content_preserved（最终内容保真）；present_result 默认 MCP schema 精简，高级参数放入 options，旧版顶层参数保持兼容。

30 秒上手

# 1. 喂一个标准内容对象 → 拿到可复制的结论卡
python3 scripts/yotta_present.py --content '{"title": "结论", "grade": "success", "verdict": "通过", "bullets": ["要点 1", "要点 2"]}'

# 2. 或直接喂一段文本，自动美化
python3 scripts/yotta_present.py --file result.txt

从「喂内容」到「拿可复制 Markdown」就这两步；更多命令见「命令一览」与「使用示例」。

这是什么

AI 输出的内容五花八门、有的难读难复用：纯文本堆砌、乱用表格、直接丢一坨 JSON。元呈 = 一个 「呈现判断 + 美化修饰」层：先决定这段内容用什么形态（卡片 / 表格 / 正文 / 图表 / 报告…）， 再套上元阁统一设计语言，输出可复制的 Markdown / 纯文本。用户拿到的是「看着舒服、能直接复制」的结果。

它只负责呈现：决定用什么形态并渲染，不改写内容、不替用户做价值判断。

核心价值

• 统一呈现——不管输入是 JSON / Markdown / 纯文本，输出都是元阁一致的设计语言（层级 / 徽章 / 指标 / 注记）。
• 内容保真门禁——先解析顺序内容块；显式形态无法完整保留或保持块顺序时自动降级 report-safe，不静默丢正文、不静默重排。
• copyable-first——Markdown（粘贴到任意 Markdown 编辑器）+ 纯文本（粘贴到 Word / 邮件）双输出。
• AI 自主选择——智能体按判断层（内容类型 → 形态）主动选形态；未接智能体时 yotta_present 确定性兜底 + --form 显式指定。
• 本地 SVG——数值分布 / 趋势 / 占比时，复用 12 图内核在本机生成 SVG，默认 Markdown 内嵌 data URI（自包含可复制）；显式 --svg 时写本地 SVG 并以路径引用。
• 判断可解释——--explain 返回「为什么用表格 / 卡片」，避免「AI 乱选」。
• 零依赖离线——Python 3.8+ 标准库；数据不出本机，不调远程渲染服务。

为什么用它

• 宿主 hook 声明——skill-manifest.json 声明 before_send / present_result；宿主不支持发送前拦截时明确降级为 explicit-unverified，不虚构强制能力。

| 优势 | 说明 | |---|---| | 通用 | 任何 AI 输出都能接：结论 / 对比 / 清单 / 教程 / 报告 / 图表 | | 可复制 | Markdown + 纯文本双输出；SVG 仅作增强，不阻塞复制 | | 本地离线 | 0 matplotlib / canvas / 远程渲染；数据不出本机 | | 判断层 | 内容类型 → 形态的规则在 SKILL.md（核心深度）；确定性兜底保证没接智能体也能跑 | | 可解释 | 判断原因可输出，用户知道为什么是这个形态 | | 生态分发 | GitHub + npm + ClawHub 三源同步；npx / git clone / Download ZIP / install.sh 四种安装方式 |

标准内容对象 schema

{
  "title": "安全扫描结果",
  "grade": "success",
  "verdict": "未发现高危风险",
  "metrics": [{"label": "检测点", "value": 8, "unit": "项"}],
  "bullets": ["全部 8 个检测点通过"],
  "notes": ["扫描仅在本机进行"]
}

字段：title / headline / grade|verdict / metrics[] / rows[] / bullets[] / body[] / notes[] / chart_data? / form? 完整说明见 references/schema.md（含 rows 四种形式、内容保真门禁、chart_data、判断规则、示例）。

Markdown 表格与 JSON rows 双兼容。显式 --form / --template 会先过内容保真校验（覆盖 + 顺序）；不兼容时安全降级 report-safe，并在 JSON 结果中返回 fallback 与 fidelity。

形态清单（开源基线 8 种）

| 形态 | CLI 名 | 何时用 | |---|---|---| | 结论卡 | conclusion | 单个结论 / 评分 / 推荐 → 徽章 + 指标 + 要点 | | 表格交付 | table | 行列分明、需对比 / 罗列的数据 | | 清单卡 | checklist | 事项 / 要点 / 清单（支持 [x] / [ ]） | | 正文 | prose | 叙述 / 说明 / 长段落 | | 指标板 | metrics | 一组关键指标 | | 问答卡 | qa | 问题 / 回答成对 | | 报告 | report | 多节长内容（卡片 + 表 + 文组合 + 目录） | | 图表 | chart | 数值分布 / 趋势 / 占比（本地 SVG，复用 12 图内核） |

命令一览

| 命令 | 说明 | |---|---| | --content <JSON\|文本> | 直接传入内容（JSON 标准对象或 Markdown / 纯文本） | | --file <路径> | 从文件读取内容（UTF-8） | | --form <形态> | 显式指定形态（缺省自动判断） | | --template <key> | 命名场景模板：vuln_report / faq / status（优先于 --form） | | --platform <p> | 平台自适应：webchat（默认）/ discord / whatsapp（表格转列表、标题转加粗）/ plain（去 Markdown 符号） | | --channel <c> | 渲染通道（默认 auto 按平台映射）：r0 保底无色（无 emoji）/ r1 emoji 增强；r2/r3 后续版本开放 | | --theme <t> | 图表 SVG 主题（默认 light）：light 亮色 / dark 暗色（深底浅字） | | --max-len <n> | 长度熔断（字符数）：先压缩列表 → 再降标题 → 最后截断，保留结论 | | --md / --text / --both / --json | 输出 Markdown（默认）/ 纯文本 / 两者 / 完整 JSON | | --out <路径> | 写文件（--both 时写 .md 与 .txt；目录按形态命名） | | --svg <路径> | 图表形态：本地 SVG 输出路径 | | --explain | 附判断说明（可解释性） | | --list-forms / --list-templates / --version | 形态清单 / 模板清单 / 版本 |

使用示例

Windows 用 python，Linux/macOS 用 python3。

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

# 纯文本输入（自动解析 + 兜底美化）
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

# 图表形态：本地 SVG + Markdown 引用
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
# 主题（图表暗色渲染）：--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": "SQL 注入", "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

退出码：0 = 成功；1 = 无输入 / 读取错误；2 = 内容校验或渲染错误。

MCP 用法（present_result）

本技能只提供一个公开 MCP server：yotta-present（零依赖、数据不出本机）。纯图表不需要单独配置 另一个 MCP server——present_result 的 chart 形态（chart_data）直接复用 12 图内核。 AI 首次使用本技能时自动完成配置（把 server 写入 mcpServers 并把护栏写入 永久记忆），每项持久变更前都会先征得你的明确同意；你拒绝则不写入，自动降级 CLI，输出一致、功能不受影响。 工具：present_result（支持 form / template / platform / channel / theme / max_len / bold_keys / output / svg / explain）、 present_forms、present_templates。

{
  "mcpServers": {
    "yotta-present": {
      "command": "python",
      "args": ["<绝对路径>/scripts/yotta_present_mcp.py"]
    }
  }
}

• present_result：content（JSON / Markdown / 纯文本）+ 可选 form / title / output(md|text|both|json) / svg / explain；form=chart + chart_data 复用 12 图内核（bar / line / pie / radar / scatter / histogram / funnel / waterfall / word_cloud / sankey / spreadsheet / treemap），本地 SVG 或 data URI。
• present_forms：列出开源基线 8 种形态（只读）。

安装

四种方式任选（推荐方式一）：

方式一：npx 一行装（走 npm 源）

npx -y @yottameta/yotta-present --agent <智能体名>     # 按智能体默认用户级目录安装（推荐）
npx -y @yottameta/yotta-present --dir <路径>          # 装到指定目录（改过目录的智能体）
npx -y @yottameta/yotta-present --list                # 查看 智能体 -> 默认目录

方式二：git clone

git clone https://github.com/YottaMeta/yotta-present.git

方式三：Download ZIP

GitHub 仓库页 → Code → Download ZIP，解压后放入智能体技能目录。

方式四：install.sh

bash install.sh --agent <智能体名>    # 按智能体默认用户级目录安装
bash install.sh --dir <路径>          # 装到指定目录
bash install.sh --list                # 查看 智能体 -> 默认目录

安装后即可在智能体中使用：加载技能后按 SKILL.md 判断层选形态，用 yotta_present CLI 或 MCP present_result 输出可复制结果。

效果展示（输入 → 输出）

输入（一段纯文本）：

扫描了 8 个检测点，全部通过，没有发现高危风险。

输出（自动判为结论卡 + 可复制 Markdown）：

# 扫描结果

> 🟢 **通过** — 未发现高危风险

**要点**

- 全部 8 个检测点通过

输入（带数据想用图表）：

{"chart_data": {"chart": "pie", "labels": ["A", "B"], "data": [3, 1]}}

输出：本地生成的 SVG 图表（默认 Markdown 内嵌 data URI，可复制自包含）。

使用技巧

| 技巧 | 命令 / 参数 | |---|---| | 想掌控形态 | 显式 --form conclusion / table / checklist / prose / metrics / qa / report / chart | | 看判断理由 | --explain | | 查看内容取舍 | --json 返回 fallback 与 fidelity；--explain 列出保留 / 压缩 / 丢弃块与顺序状态 | | 省 token | --max-len 800（先压列表、再降标题、最后截断，保留结论） | | 适配平台 | --platform discord / whatsapp / plain | | 复制到 Word / 邮件 | --text 纯文本输出 | | 关键字段加粗 | bold_keys: ["title", "verdict"] | | 场景模板复用 | --template vuln_report / faq / status（定义见 references/templates.json） |

错误处理

• 退出码：0 = 成功；1 = 无输入 / 读取错误；2 = 内容校验或渲染错误。
• 出错时 stderr 会给出原因 + 修复建议（人话版），照着提示改即可。
• 常见问题与避坑详见 references/faq.md。

常见问题 FAQ（速查）

| 问题 | 答案（详见 references/faq.md） | |---|---| | 想带徽章却没输出徽章？ | 用标准内容对象 JSON（{title, grade, verdict, bullets}） | | 表格 columns 不生效？ | 用 rows 对象列表键或二维数组 + headers | | 图表报「需要 chart_data」？ | 补 chart_data（chart/labels/data） | | --svg 报错？ | 仅图表形态支持；去掉 --svg 走默认 data URI | | 输出形态不对？ | 显式 --form；用 --explain 看理由 | | 显式形态会丢内容吗？ | 不会静默丢、也不会静默重排；不兼容时降级 report-safe，并返回 fallback / fidelity | | Markdown 表格能直接传吗？ | 可以；JSON rows 仍是结构化推荐格式 | | MCP 没加载？ | 检查 mcpServers + 重启会话；否则降级 CLI |

边界（红线）

• 不做图表工具：图表只是呈现形态之一。
• copyable-first：Markdown + 纯文本双输出；SVG 仅增强，不阻塞可复制。
• 数据不出本机：不联网、不调远程渲染服务。
• 不替代判断：只负责呈现，不改写内容、不替用户做价值判断。
• 开源与许可：MIT 开源、能力开放；商标与品牌声明见 NOTICE。

许可证

MIT。商标与品牌声明见 NOTICE。