Yanshi 试用手册(Trial Guide)
版本基线:2026-11-17(Content Studio Y0–Y10 全闭环 + 15 个内置生成器 + Tauri 桌面端 Yanshi Studio)
适用读者:想在日常研发、论文研读、技术分享与多模态内容生产中直接使用 Yanshi 的开发者与创作者
配套文档:当前全景状态见 CURRENT_STATUS.md;15 个内置工作流清单见 STUDIO_CATALOGUE.md
0. 先读:当前各入口成熟度总览
经过 V / W / X / Y 四轮收口,核心 CLI、Studio 生成器、服务端网关与桌面端均已打通端到端闭环:
| 状态 | 入口 / 路径 | 说明 |
|---|---|---|
| 🟢 | Studio 生成器(15 套模板) | yanshi workflow run examples/generators/<name>.yml --output-dir out,直出 .pptx、.pdf、.mp4、.xlsx、.mp3、.svg、.html |
| 🟢 | 桌面端 Yanshi Studio.app(macOS / Windows / Linux) | 免 PostgreSQL 零配置本地引擎,支持可视化单步调试、一键运行、内置价格表与交互式问答卡片 |
| 🟢 | Web Studio(/ui/app · /ui/studio · /ui/console) | yanshi-server 内嵌前端,支持模板运行、DAG 拓扑画布编辑、断点观测与 SSE 实时事件追踪 |
| 🟢 | 本地 DAG 工作流(workflow run / resume / validate / debug) | 支持并发调度、FlowValue::File 零 base64 流转、cost_limit_usd 成本上限与不重复计费断点续跑 |
| 🟢 | Skill + 工作流工具编排(skill run / chat / validate) | 支持 [[workflows]](如 examples/applications/content-studio)与双语 CJK BM25 知识检索 |
| 🟢 | Harness 治理会话与动态工作流 | 支持非幂等/发布类(Publish)/超预算审批门禁、DenyAndStop 立即停机与 ask_user 中断恢复 |
| 🟢 | 诊断与复盘(doctor / trace replay / trace tui) | 自动体检模型配置、价格表、沙箱等级与外部渲染二进制(ffmpeg / pandoc / typst / d2) |
1. 环境准备(5 分钟)
1.1 安装 CLI(或桌面端)
# 安装命令行工具 yanshi
cargo install --path yanshi-cli
yanshi --help
# (macOS 可选)一键构建并安装桌面端到 /Applications/Yanshi Studio.app
./scripts/install_desktop.sh --open
1.2 初始化模型与 API Key
yanshi config init
# 生成:
# ~/.yanshi/models.yml 用户模型覆盖配置(自动继承内置多模态模型库)
# ~/.yanshi/.env API Key 模板
编辑 ~/.yanshi/.env,填入至少一家厂商的 API Key:
OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY / MOONSHOT_API_KEY /
DASHSCOPE_API_KEY / STEP_API_KEY / GLM_API_KEY / DEEPSEEK_API_KEY / MINIMAX_API_KEY
运行体检确认配置与外部工具状态:
yanshi config validate
yanshi doctor --profile local
yanshi doctor 会逐项报告:LLM 模型注册表、计费价格表(PricingTable)、OS 沙箱后端,以及可选外部渲染工具(pandoc、typst、ffmpeg、ffprobe、d2)。即使未安装外部工具,纯 Rust 内嵌渲染器(原生 OOXML .pptx、.xlsx/.csv、思维导图 .svg/.png、闪卡/测验 .html)依然开箱可用。
2. 场景一:一句话生成日常成品(Content Studio,10 分钟)
examples/generators/ 提供了 15 套生产级模板(完整说明见 STUDIO_CATALOGUE.md)。推荐先试以下四条日常高频工作流:
2.1 精美插图技术演讲 PPT(.pptx + 16:9 .pdf + 交互 .html)
自动联网检索资料 → 规划大纲 → 按页智能分流生成 AI 概念插图(6 种艺术预设,严禁嵌入乱码文字)、编译校验的 D2 架构图与原生可编辑 PowerPoint 形状/表格/代码框:
yanshi workflow run examples/generators/illustrated_slides.yml \
--input subject "Rust 异步运行时 Tokio 调度器与工作窃取原理" \
--input style_preset editorial_tech \
--output-dir out/tokio-slides
2.2 论文双语精读与实验表格提取(arXiv / PDF → .pdf + .xlsx + 架构图)
yanshi workflow run examples/generators/paper_reader.yml \
--input source "https://arxiv.org/abs/1706.03762" \
--output-dir out/paper-digest
2.3 GitHub 仓库架构扫描与模块拓扑图(Repo → D2 .svg + .pdf)
yanshi workflow run examples/generators/repo_architecture.yml \
--input source "https://github.com/tokio-rs/axum" \
--output-dir out/axum-arch
2.4 交互式后端项目架构规划(多轮 ask_user 澄清 → 全套设计图 + PostgreSQL DDL + PDF)
yanshi workflow run examples/generators/backend_project_planner.yml \
--input idea "设计一个支持高并发秒杀与多租户库存隔离的订单履约后端系统" \
--output-dir out/order-spec
提示:在桌面端
Yanshi Studio或 Web/ui/app、/ui/studio中运行该模板时,画布与运行面板会自动弹出交互式问答卡片,回答后工作流无缝继续执行。
3. 场景二:自定义 DAG 流水线与断点续跑(20 分钟)
3.1 编写声明式 YAML 工作流
# my_pipeline.yml
name: "daily-brief"
cost_limit_usd: 0.25
inputs:
topic:
description: "简报主题"
default: "Rust WebAssembly 组件模型"
nodes:
- id: build_prompt
type: template
parameters:
template: "请围绕以下主题撰写一份结构化技术要点简报:{{ topic }}"
- id: draft
type: llm
dependencies: ["build_prompt"]
input_mapping:
prompt: "{{ nodes.build_prompt.outputs.output }}"
- id: brief_html
type: render_markdown
dependencies: ["draft"]
input_mapping:
markdown: "{{ nodes.draft.outputs.output }}"
parameters:
title: "每日技术简报"
校验并运行:
yanshi workflow validate my_pipeline.yml --strict
yanshi workflow run my_pipeline.yml \
--input topic "Rust 异步生态演进" \
--output-dir out/brief
输入优先级规则明确固定为:input_mapping > 工作流级 inputs > 节点静态 parameters(见 CONFIGURATION.md)。
3.2 成本上限与付费节点断点续跑
长耗时多模态流水线(例如 tech_slides_video.yml 演播级 1080p 课程视频)建议开启 --checkpoint:
yanshi workflow run examples/generators/tech_slides_video.yml \
--checkpoint --timeout 15m \
--input topic "Rust Traits 零成本抽象与动态分发" \
--output-dir out/traits-video
# 若中途因网络波动中断,直接续跑未完成节点(已完成节点跳过且不重复计费):
yanshi workflow resume <run_id> examples/generators/tech_slides_video.yml \
--output-dir out/traits-video
4. 场景三:可视化 Studio 与桌面端调试(10 分钟)
除了命令行,推荐打开可视化工作台体验单步断点调试与一键应用运行:
- 桌面端(零依赖推荐):直接启动
/Applications/Yanshi Studio.app(或cd yanshi-ui && cargo tauri dev)。 - Web 端(网关模式):运行
cargo run -p yanshi-server,浏览器打开:http://127.0.0.1:8080/ui/app—— App Runner:表单化输入,一键并发生成并在线预览幻灯片、1080p 视频与 PDF。http://127.0.0.1:8080/ui/studio—— Studio 调试台:在@xyflow/react拓扑画布上拖拽添加节点(含illustration、figure、render_slides等)、勾选「每步暂停观测」或点击节点断点,在右侧实时检视求值后的 Input / Output 与内联媒体产物。
5. 场景四:Skill 编排与 Harness 治理会话(20 分钟)
5.1 用 Planner Skill 一次调度多个生成器
examples/applications/content-studio 将多个生成器封装为 WorkflowTool,由 Agent 按需组合参数调用:
yanshi skill run examples/applications/content-studio \
--input url=https://example.org/article \
--input want=report,mindmap,flashcards \
--output-dir out/bundle
5.2 受治理的 Agent 会话(Harness Mode)
yanshi harness run "调研 ./docs 目录结构并总结模块边界" \
--skill examples/ecosystem/skills/research-assistant \
--approve cli \
--profile local \
--max-steps 12 \
--cost-limit-usd 0.50
- 非幂等工具、
Publish发布动作以及超出成本阈值的操作均会触发交互式审批(支持单次放行、按 SHA-256 参数摘要缓存或qDenyAndStop立即终止)。 skill.toml的[[knowledge]]支持files内联与rag索引(内置中英文/日文双字切分 BM25 与 MMR,亦可选chunk_strategy = "semantic")。
6. 诊断与 Trace 复盘
每次执行都会在 ~/.yanshi/traces(或 YANSHI_TRACE_DIR)留下包含 cost_usd 与工具策略决策的结构化轨迹:
yanshi workflow debug examples/generators/illustrated_slides.yml --visualize --analyze
yanshi trace replay <run_id>
yanshi trace tui <run_id> --filter tool --details
7. 常用命令速查
# 环境与模型体检
yanshi doctor --profile local
yanshi config validate
yanshi llm models
# 运行与续跑工作流(结果导出到 --output-dir)
yanshi workflow validate <yml> --strict
yanshi workflow run <yml> --input KEY VALUE --checkpoint --output-dir out
yanshi workflow resume <run_id> <yml> --output-dir out
# Skill 与多成品编排
yanshi skill validate <dir> && yanshi skill list-tools <dir>
yanshi skill run examples/applications/content-studio --input url=<url> --input want=report,slides --output-dir out
# 动态工作流(先 dry-run 审阅计划)
yanshi workflow dynamic --goal "..." -m <model> --allow-path ./docs --dry-run
# 桌面端打包与安装(macOS)
./scripts/install_desktop.sh --open