taxue-dsh-artisan · taxue 画师
taxue-dsh-artisan
DeepSeek Harness 的一体化视觉创作工具链：提示词反推、确定性色卡提取、审计优化、多供应商生图。基于原反推提示词插件完善而来，并原生整合了多供应商生图能力，成为可灵活组装的单插件。
解决什么问题
原来要「反推一张图 → 生成一张图」需要先后调用两个互不相识的插件：一个只出提示词、一个只生图，模型要自己把结构化的 meta_prompt 手动搬运成生图的 prompt，中间承接全靠试错。
整合后十一个工具在同一插件内，可单个调用、也可按需串联：反推 → 色卡/优化 → 生图；风格库 / 修图 / 质量审计为创作全程兜底；另有四个技能桥工具把 taxue-imagegen 的模板与验收能力接进来，同样按需串联。
十一个工具
原生工具（自带实现，不依赖外部技能；后三条吸纳自 taxue 五技能的精华）：
| 工具 | 作用 | 是否调远程 |
|---|
reverse_prompt | 反推图像/视频提示词并直出可直接生图的完整提示词，附带优化方向、画幅建议与同规格同风格新图引导 | 否（本地纯函数） |
optimize_prompt | 对候选提示词做本地结构审计：信息量、相机冲突、构图/动作缺失、硬冲突（风格机制互斥）、模仿/IP 风险、单变量优化建议 | 否（本地纯函数） |
extract_palette | 对 PNG 参考图做确定性色卡提取：主色/辅色/点缀色 hex 与占比、暗部/高光锚点色；同一张图永远同一结果 | 否（本地像素算法） |
generate_image | 用配置的供应商生成一张图：Google Gemini / OpenAI / 字节 Seedream / xAI Grok / ChatGPT 订阅；支持参考图对比预览与可选图控图 | 是 |
artisan_styles | 创作风格库：半调海报 12 种（taxue-halftone）+ 创意风格 14 家族（taxue-creative-style）+ 节气推演模板 4 张（taxue-solar-polaroid），每条带可直接生图的英文 prompt | 否（本地纯函数） |
artisan_edit | 图像编辑三步法（compositor-retouch）：体检 → 出可回退修图方案 → 生成专业修图提示词；不把图喂回模型重画 | 否（本地纯函数） |
artisan_quality | 提示词质量审计（skill-optimizer）：七维诊断打分 + 基线门控检查 + 修复建议，送生图前自检 | 否（本地纯函数） |
技能桥工具（复用 taxue-imagegen 的 Python 脚本，技能零改动、零复制；详见「taxue-imagegen 技能桥」）：
| 工具 | 作用 | 对应技能脚本 |
|---|
artisan_plan | 类型路由（A/B/C/D/E）与槽位清单 | fill_meta.py --list / build_storyboard.py |
artisan_compose | 机械填槽组装可生图提示词（内嵌静态预检） | fill_meta.py |
artisan_preflight | 手写提示词静态预检，拦 11 个可文本检出的翻车项 | preflight.py |
artisan_check | 出图后验收：量测 + 文字带裁片 + 水印识别，返回 pass / blocker / pending | postcheck.py |
图控图（默认关闭）
generate_image 的 reference_assets 默认只用于结果卡片里「参考图 vs 生成图」并排对比，不上传。显式传 use_reference_images: true 时才把参考图内联编码进生图请求：
- Google Gemini：参考图作为
input_image 内容块随 prompt 进入 Interactions API。
- OpenAI / Seedream / codex（gpt-image）：参考图以 data URL 数组走
image 字段。
- Grok Imagine：参考图以 data URL 数组走
image_url 字段。
开启后生成结果会向参考图的构图、色彩、主体靠拢，适合「照着这张图还原/改画」类任务；要求路径为本地可读的 PNG/JPEG/WebP 文件。默认不带参考图的行为完全不变。
确定性色卡提取
extract_palette 用本地像素级聚类（Oklab 颜色空间 K-Means，无随机种子、固定迭代轮数），对 8-bit 非隔行 PNG 输出：
- 主色/辅色/点缀色的 hex 值与占比（点缀色按「高饱和 + 与主辅色拉开距离」评分选出）
- 暗部锚点色（明度 < 0.3 的簇）与高光锚点色（明度 > 0.87 的簇）
- 全部颜色及归一化占比
输出 hex 取自「离簇心最近的真实采样像素」，保证颜色真实出现在原图中。反推图像时先调它拿到真实色值再写进提示词，把配色描述从目测升级为像素级精确。JPEG/WebP 参考图需先用 sips 等本地命令转 PNG。
直出反推（相对原 forge 的任务包模式）
原 forge 把反推输出成「evidence-first 元提示词 + JSON 输出合同」，让模型把它当外包任务执行，与 DSH 单模型环境脱节，模型倾向绕开。本版改为直出：
| 输出字段 | 作用 |
|---|
prompt | 可直接粘贴到生图工具的完整提示词（还原参考图文字排版、风格与细节） |
optimization_advice | 可执行的优化方向（每一条一个变量） |
aspect_ratio | 从参考图真实像素宽高换算的画幅建议（如 9:16）；无像素时回退文本推断 |
variant_guidance | 同规格同风格新图引导 |
quality_gate / risk_flags / clarification_questions | 质量门、风险与澄清问题 |
模型调用一次 reverse_prompt 即可拿到完整结果，再把它直接喂给 generate_image，参考图经 reference_assets 传入后会在结果卡片与生成图并排预览对比。
视觉还原锚点（量身为本插件定做）
反推还原度不足的根因是模型看图没有方法论约束。本插件提炼 9 个可量化还原锚点，注入最终提示词，供下游生图模型逐条复现：
- 画幅锚点：第一句写死「画幅比例：<真实比例>」，正文不再出现第二个比例
- 气质锚点：首句锁定总体视觉气质，媒介感优先
- 风格锚点：先证据后定名，赛璐璐/厚涂/柔和渲染判定规则硬编码
- 表面层锚点：扫描颗粒/柔焦/低清只写作用区域，不得当材质纹理
- 构图锚点：景别、主体位置、留白、视角各一句，禁止冲突景别
- 光色材质锚点：主光源、冷暖、饱和度、关键材质固有色与反射
- 主体锚点：≥3 项独立锚点一致才写具体 IP/角色/品牌
- 文字锚点：可见文字逐字照抄，注明字体/横竖排/对齐
- 负向锚点：只留 2-5 个最可能跑偏风险，原图已有特征不得列入
画幅精确还原：reverse_prompt 新增 image_width / image_height 参数。模型 read_image 后把返回的 width×height 填入，插件按真实像素换算最接近的标准画幅（支持 Grok/Seedream 扩展比例），并在提示词第一句写死真实比例——截图/参考图的画幅因此可以精确还原，不再靠文本猜。
LLM 反推重组（观察描述 → 可生成提示词）
reverse_prompt 内置 LLM 反推重组器（llmPolish，默认开启）：模型 read_image 得到的只是「观察描述」，重组器把它按 6-block 结构化协议 转译为可直接喂给生图模型的生成指令：
- 主体与任务：主体是谁/什么、动作、姿态、方向
- 构图与版式：空间纵深、前后层次、视觉优先级、留白、裁切
- 视觉风格与材质：风格气质、光源方向与色温、投影、主色数量/色值、材质纹理
- 文字与标注：可见文字内容、字体、排版、字号关系、内边距
- 画幅与输出：画幅比例
- 约束与负向：保持/可改/避免用「没有…」「无…」自然表达
转译原则：去描述语气改生成语气、按题材路由选 block 顺序（装置类构图先行、海报类文字版式加重、人像类主体先行）、无元语言、负向克制。任一环节失败自动回退原提示词。可在设置中指定 llmPolishProvider / llmPolishModel，关闭 llmPolish 即退回纯规则编译。
Token 优化（相对原 forge）
| 项目 | 原 forge | taxue-artisan | 变化 |
|---|
| 注入体 | 3863 字节任务包 | 直出提示词（约 2178 字节） | -44% |
| 反推调用链路 | read_image + 读资料 + 手写长文（8-24 步） | read_image + reverse_prompt 一步直出（2-3 步） | 步数 -70% 以上 |
手段：
- 默认单语言：
output_language 默认 zh-CN，不再默认压一份英文元提示词；需要双语时显式指定。
- 直出而非外包：不再输出需要模型二次执行的「任务包」，直接产出可粘贴提示词，砍掉模型手写长文的多轮。
- 参考图对比：
generate_image 接收 reference_assets 路径，结果卡片并排显示参考图与生成图。
多语言
不局限于中文。reverse_prompt 与 optimize_prompt 的 output_language 参数支持三种取值：
| 取值 | 元提示词 / 审计 / 质量门 / 风险与澄清提示 |
|---|
zh-CN（默认） | 全中文 |
en | 全英文 |
bilingual | 中文为主、关键锚点双语 |
output_language: 'en' 时，meta_prompt 正文、quality_gate、risk_flags、clarification_questions、审计 warnings/summary/next_single_variable_test 均输出英文。
保存文件夹（生成图落盘位置可选）
generate_image 生成的图除附加到会话外，会落盘到可配置目录，方便追溯。配置路径：设置 → 插件 → taxue 画师 → 保存文件夹。
- 填入绝对路径 → 生成图保存到该目录（自动建目录）。
- 留空 → 保存到默认
~/Downloads/。
- 落盘文件名：
taxue-image-<时间戳>.<扩展名>；落盘失败不阻断出图，仅提示。
- 提示词 sidecar：落盘的同时写同名
.json（taxue-image-<时间戳>.json），内含完整 prompt、provider、model 与生成时间——图与生成它的提示词不分离，收藏即溯源。
taxue-imagegen 技能桥
artisan_plan / artisan_compose / artisan_preflight / artisan_check 四个工具把 taxue-imagegen 技能的能力接进 DSH。技能本身零改动、零复制：槽位清单、模板正文、验收阈值全部从技能目录读取，技能升级插件自动跟上，不存在第二份真源。
为什么是子进程调用而不是重写
技能的填槽、预检、验收逻辑经过数十轮实测调优（去水印族有 8 个版本、验收阈值在 202 张成品上标定）。用 TypeScript 重写等于丢弃全部实测依据，并且从第一天就开始与技能漂移。桥层只做「调用 + 透传」：脚本输出本就是为 Agent 设计的文本，原样交给模型比结构化解析更稳，脚本改了也不会让解析器碎掉。
代价是每次调用多约 300ms 的进程启动开销。出图本身 5-60 秒，这个占比不到 1%。
典型链路
artisan_plan → 拿到类型与槽位清单（省去读 SKILL.md 与模板文件）
artisan_compose → 槽位进、可生图提示词出
generate_image → 出图（也可用 dsh-workbuddy-image 的 workbuddy_generate_image 走 WorkBuddy 混元）
artisan_check → 三档验收，blocker 才允许一次定向重生
手写或改造过的提示词，送生图前单独跑 artisan_preflight；artisan_compose 组装出的提示词已内嵌预检，不必重复调用。
配置
设置 → 插件 → taxue 画师：
| 项 | 说明 |
|---|
| 技能目录 | taxue-imagegen 根目录（含 scripts/fill_meta.py）。留空按 ~/.workbuddy/skills/taxue-imagegen、~/.agents/skills/...、~/.claude/skills/... 顺序探测。 |
| Python 解释器 | 留空按 WorkBuddy 内置环境、/opt/homebrew/bin/python3、/usr/local/bin/python3、python3 顺序探测。技能脚本需 numpy / PIL / opencv。 |
| 脚本超时 | 单次脚本执行超时（ms），默认 60000。 |
技能目录不存在时工具会明确报错并指向设置页，不静默降级。桥层只接受四个白名单脚本，不接受任意命令。
供应商
| Provider | 默认模型 | 凭证环境变量 |
|---|
| Google Gemini | gemini-3.1-flash-image | GEMINI_API_KEY |
| OpenAI | gpt-image-2 | OPENAI_API_KEY |
| 字节 Seedream | doubao-seedream-5-0-260128 | ARK_API_KEY |
| xAI Grok | grok-imagine-image-2.0 | XAI_API_KEY |
| ChatGPT codex | gpt-image-2 | 无需 API Key，走 ChatGPT 订阅 |
凭证路由（订阅优先，已实测验证）：provider 为 grok 且 Grok 订阅已登录时，generate_image 自动走订阅出图（无需 API Key，SuperGrok / X Premium 的 OAuth token 对 /v1/images/generations 有效）；codex 走 ChatGPT 订阅（/backend-api/codex），登录订阅即可出图，无需 API Key；未登录订阅或非 grok/codex 供应商用 API Key 兜底；无 API Key 但环境有 Grok 订阅时自动重定向到 Grok 订阅。generate_image 声明 timeoutMs: 180000。Grok 出图时效：grok-imagine-image 约 5-15 秒，grok-imagine-image-2.0（默认，质量最高）约 30-60 秒，接近超时建议用 run_in_background 后台生图。订阅出图要求网络可达 api.x.ai（走系统代理）；网络层失败已包装为带排查提示的错误（而非笼统的 fetch failed）。
Grok 兼容性与差异：xAI 的 /v1/images/generations 是 OpenAI 兼容端，但 不支持 size/quality/style 参数，只支持 aspect_ratio 与 resolution。整合时已为 Grok 走独立参数路径——不带 size，可选带 aspect_ratio——避免收到 400。默认返回临时 URL，插件会立即下载持久化为附件。
安装
从 npm 安装（推荐，发布后可用）：
dsh plugin --profile web add taxue-dsh-artisan
从 GitHub 直装：
dsh plugin --profile web add github:taxueseek/taxue-dsh-artisan
本地源码开发时用 file: 引用：
dsh plugin --profile web add taxue-dsh-artisan@file:/path/to/taxue-dsh-artisan
重启 dsh web，打开 设置 → 插件 → taxue 画师 配置供应商与 API Key（写保护，前端不读回明文）。
兼容性
| taxue-dsh-artisan | Harness | 说明 |
|---|
| 0.3.1 | 0.2.1-alpha.3（当前，在跑） | 设置表单走 cordis Config 导出自动生成；不占 UI 座位，无座位依赖。 |
| 0.3.0 | 0.2.1-alpha.1（适配） | 宿主删除 installSettingsSection / settingsNamespace 后，设置表单改用 cordis Config 导出约定。 |
需要 Node.js ≥ 22.19。对 @deepseek-ai/* 的 peer 依赖声明为 >=0.1.0-0 <0.3.0，覆盖 0.1.x 全部 prerelease（npm next 现为 rc.8；web profile 实际捆绑 dsh-client-runtime 0.1.1-rc.2）。
可选桥接：炭笔动态万物速写
reverse_prompt 保留 dynamic_charcoal_mode 开关（默认关闭）。开启后元提示词额外锁定「主体类别—受力事件—主轴—深黑锚点—余势」，并按需加抓拍瞬间、低机位/俯拍、切边、时间残线、方向性留白与有限墨彩控制。
开发
pnpm install
pnpm run typecheck # tsc --noEmit
pnpm run test # 纯函数闭环 + 技能桥端到端（技能缺席时自动跳过）
pnpm run measure:tools # 工具面常驻上下文体积（只看真正进上下文的三部分）
pnpm run build # tsc && tsdown → lib/
卸载
dsh plugin --profile web remove taxueseek/taxue-dsh-artisan
贡献
欢迎提交 PR。
许可
MIT
