Instructor Structured Output

Instructor：声明 Pydantic BaseModel 即可从 20 个 LLM provider 拿到类型化实例。核心是 monkey-patch（instructor.patch / from_*）拦截 create()，注入 schema-aware kwargs，tenacity 重试 + In...

Security Scan

The skill's name/description claim a generic 'Instructor' LLM-to-Pydantic adapter, but the included runtime seed.yaml and human summary are a finance-specific blueprint that asks the host to run Python checks, access workspace paths, and require ZVT data — this mismatch and unexpected host interaction are concerning.

Purpose & Capability

The skill title/description advertises an LLM->Pydantic 'Instructor' adapter across 20 providers. However the bundled seed.yaml and human_summary are a compiled finance blueprint (finance-bp-139) focused on ZVT backtests, data directories, and domain-specific preconditions. Requiring ZVT, K-data, and backtest preconditions is not coherent with a generic 'instructor structured output' utility.

Instruction Scope

SKILL.md instructs the host AI to read references/seed.yaml and follow its execution protocol. seed.yaml contains explicit runtime actions that direct the host to run shell/python commands (e.g., import zvt checks, filesystem writes, sqlite write permission tests), reload seed.yaml on execute, and consult local files (LATEST.yaml / LATEST.jsonl). Those instructions expand scope to performing host-side checks and file access unrelated to the advertised LLM schema-mapping purpose.

Install Mechanism

No install spec or code is provided (instruction-only), which is low risk in itself. However seed.yaml references an install_trigger (resources.host_adapter.install_recipes[]) and a host verification step; there are no concrete install recipes included in the package, making the runtime behavior ambiguous — the host may attempt to run installs or import checks based on the blueprint instructions.

Credentials

The skill declares no required env vars, yet seed.yaml preconditions and checks reference ZVT_HOME and expect writable data directories and Python package availability. The blueprint implicitly requires filesystem and Python environment access (and potentially network access to fetch data/providers) that are not declared or justified by the skill's stated purpose.

Persistence & Privilege

The skill is not always:true and is user-invocable (normal). Still, seed.yaml defines workspace paths (scripts_path, skills_path, trace_path) and mandates reloading and writing to host workspace. This gives the skill potential to read/write files in the host workspace during execution, which is a privilege the README/metadata did not clearly surface.

What to consider before installing

This package is internally inconsistent: the name/description promise a generic LLM->Pydantic adapter, but the included seed.yaml/human_summary are a finance blueprint that will ask the host to run Python checks, access/write workspace files, and rely on ZVT data. Before installing or enabling this skill: (1) don't allow it to run on a production agent or with broad filesystem access — use an isolated sandbox; (2) inspect references/seed.yaml and human_summary.md yourself to confirm the intended purpose; (3) if you expected a pure 'instructor' utility, ask the publisher why a finance blueprint and ZVT preconditions are bundled; (4) if you must run it, restrict agent permissions (no arbitrary shell/python execution, no write access to important dirs) and be prepared to manually supply any data instead of allowing the skill to probe your environment. If you are not comfortable with host-side Python commands and filesystem writes triggered by a skill whose metadata does not disclose them, do not install or enable it.

这个 skill 适合什么用户？能做哪些任务？

概览

Instructor 是把 Pydantic BaseModel 直接绑到 LLM 输出的 Python 框架（github.com/jxnl/instructor）。核心机制：monkey-patch（instructor.patch / instructor.from_*）拦截 provider client 的 create() 调用，注入 schema-aware kwargs，在 tenacity 重试循环里跑，验证 JSON 响应到模型，ValidationError 时把 failed_attempts 作为 XML 重写 prompt 再试。

支持 20 个 provider...

Doramagic 晶体页: https://doramagic.ai/zh/crystal/instructor-structured-output

知识规模

• 47 条约束 (4 fatal + 43 non-fatal)
• 上游源码: jxnl/instructor @ commit 3f1d6ddb
• 蓝图 ID: finance-bp-139

用法

Host AI（Claude Code / Cursor / OpenClaw）读 references/seed.yaml，按其中的：

• intent_router 匹配用户意图
• architecture 理解项目架构
• constraints 应用 anti-pattern 约束
• business_decisions 参考核心设计决策

FAQ 摘要

这个 skill 适合什么用户？能做哪些任务？

适合需要从 LLM 拿到强类型结构化输出的工程师：信息抽取、表单解析、JSON API 直接返回 Pydantic 模型、agent 工具调用参数解析等。20 个 provider 一致 API。访问 doramagic.ai/r/instructor 查看完整用例。

需要准备什么环境？依赖什么？

Python 3.9+（instructor 在 pyproject 中声明 >=3.9）。Pydantic v2 事实上必须（function_calls.py 用 model_validate_json + TypeAdapter，都是 v2-only，v1 在 Partial 路径上 AttributeError）。

会踩哪些坑？这个 skill 怎么防护？

本 skill 内置 47 条约束（4 条 fatal）。典型踩坑：(1) failed_attempts XML 每次重试线性增长，max_retries=5 可超 context window；(2) from_openai 的 mode 验证用 assert，python -O 下静默剥离；

---

完整文档: 见 references/seed.yaml (v6.1 schema). 浏览页: https://doramagic.ai/zh/crystal/instructor-structured-output