dsh-plugin-tailor：把仓库从能跑改到敢发布
简体中文 · English
dsh-plugin-tailor
把仓库从「能跑」改到「敢发布」：审计 → 选风格 → 品牌素材 → 双语 README → 发布前校验。
MIT · Node >=20 · DSH >=0.2.0-rc.2 <0.3.0 · v0.5.0
安装 · 七种风格 · 六个工具 · 路线图
8 维审计、44 项检查、7 种风格、12 个原创图形概念
真实终端：repo_audit 给 dsh-plugin-resolver 打 81 分，repo_verify 返回 PASS
真实输出：tailor audit ../dsh-plugin-resolver 与 tailor verify …（VHS tape 可重录）
目录
为什么需要它
- README 停在“能跑”：安装命令藏在 docs、demo 是随手截图、限制一条不写；项目越好，越吃亏在表达。
- 每换一个仓库就重做一遍：首屏、徽章、目录、素材、发布检查，全是重复劳动，风格还无法复用。
- 发布前没人检查：相对链接、锚点、图片、TODO、测试数量过期，通常等读者发现。
- “好看”没有标准：与其模仿某一个模板，不如把优秀仓库的共性拆成可选的风格预设 + 可执行的检查项。
本插件做的事：把仓库成熟度拆成 8 维 44 项检查，把 README 风格拆成 7 个预设，把品牌素材变成确定性 SVG，把发布前检查变成一条 repo_verify。
手工 README 对比 tailor 生成：demo、证据、品牌、链接检查
怎么工作
repo_audit → repo_plan → repo_brand → repo_readme → repo_verify
repo_audit：读 package.json、README、assets、CI、git 状态，按 8 维 44 项检查打分，输出按影响排序的缺口。repo_plan：把缺口变成 P0/P1/P2 任务；每条带验收标准与 repo_verify 命令，风格缺口（缺 GIF、缺截图、缺英文页）也进任务。repo_brand：按所选风格的调色板与图标字形，生成 icon.svg / logo.svg / banner.svg / social-preview.svg；确定性、无图片模型、不覆盖已有文件。repo_readme：按风格组装 zh/en 草稿；只使用仓库真实事实，缺失项变成 TODO(tailor)；默认 dry-run 给 diff，apply 才落盘。repo_verify：复跑审计 + 相对链接、图片、锚点、徽章、必需章节、剩余 TODO 检查，报告 PASS/FAIL 与 baseline 分数差。
功能
六个能力：repo_audit、repo_readme、repo_brand、双语对等、写保护、repo_verify
- 8 维 44 项审计：身份、首屏、安装、文档、证据、发布、社区、品牌；每条缺口都带具体修法，不只是打分。
- 7 种风格 + 双语草稿：从证据优先到极简排版，先看 diff 再落盘。
- 风格可自创：内置风格是 7 份 JSON；自定义放在
.tailor/styles/ 或 ~/.tailor/styles/，支持 extends 继承与 schema 校验。
- 12 个原创图形概念 × 12 个品牌文件：
icon / maskable / 明暗 logo / 明暗 wordmark / 明暗 banner / social / brand-sheet / brand-tokens.json / 索引；同一仓库重复生成字节一致。
- 视觉 QA：调色板自动算 WCAG 对比度，
repo_brand 输出 PASS/FAIL；审计含 14 项品牌与视觉检查（尺寸、比例、明暗配对、alt、首屏图、宽度控制）。
- 3 套 README 版式引擎：
editorial / centered / showcase，风格 JSON 里用 visual 字段配置，不是同一模板换色。
- 写保护：手写 README、已有素材、脏 worktree 默认拒绝，必须显式
force。
- 发布前校验：相对链接、图片、锚点、徽章、必需章节、剩余 TODO，一条命令给出 PASS/FAIL。
- CLI 与 DSH 工具同源：
bin/tailor.mjs 和六个工具调用同一套 logic，终端里能复现。
快速开始
已发布到 npm 与 GitHub Release（v0.5.0）。三种装法：
# 1) DSH 插件（推荐，直接从 npm 装）
dsh plugin --profile <profile> add dsh-plugin-tailor
# 2) CLI 全局安装（不需要 DSH 也能用）
npm install -g dsh-plugin-tailor
dsh-repo-tailor styles
# 3) 离线：源码或 Release tarball
git clone https://github.com/sakikoTGW/dsh-plugin-tailor
dsh plugin --profile <profile> add /path/to/dsh-plugin-tailor
dsh plugin --profile <profile> add /path/to/dsh-plugin-tailor-0.5.0.tgz
装完重启一次引擎，六个 repo_* 工具上线。之后改 logic/ 下一次调用即生效，改 host/register.js 或 index.js 需要重启引擎。
不装插件也能用 CLI，和工具走同一套逻辑：
node bin/tailor.mjs styles # 列出 7 种风格
node bin/tailor.mjs audit . --style=terminal # 打分 + 缺口
node bin/tailor.mjs plan . --style=terminal # 任务清单
node bin/tailor.mjs brand . --style=playful --apply
node bin/tailor.mjs readme . --style=evidence --lang=both
node bin/tailor.mjs verify . --style=evidence
node bin/tailor.mjs style:init . --id=my-style --extends=evidence # 自创风格
CLI help：六个命令与示例
tailor --help：六个命令和示例，和 DSH 工具共用同一套逻辑。
在 DSH 里直接调用：
repo_audit { path: ".", style: "terminal" }
repo_plan { path: ".", style: "terminal" }
repo_readme { path: ".", style: "terminal", lang: "both" }
repo_brand { path: ".", style: "terminal", apply: true }
repo_verify { path: ".", style: "terminal" }
六个工具
| 工具 | 读写 | 主要参数 | 返回 |
|---|
repo_styles | 读 | path?, json? | 内置 + 自定义风格的 id、来源（builtin/global/repo）、校验错误；json: true 返回机器可读结构 |
repo_audit | 读 | path, style? | 0-100 分、8 维明细、按影响排序的 gaps、风格缺口 |
repo_plan | 读 | path, style?, limit? | P0/P1/P2 任务，每条带 acceptance 与 verify |
repo_readme | dry-run / 写 | path, style?, lang?, apply?, force? | diff、TODO 清单、风格缺口 |
repo_brand | dry-run / 写 | path, style?, concept?, tagline?, apply?, force? | 12 个文件（12 概念可选） |
repo_verify | 读 | path, style? | PASS/FAIL、逐项检查、剩余 TODO、分数差 |
写操作默认 dry-run；手写 README 或已有素材默认拒绝/跳过，必须显式 force 才覆盖；worktree 脏且未 force 时直接拒绝。
七种风格
7 种 README 风格预设：证据优先、终端工具、移动端社群、GIF 教程、品牌产品页、面板平台、极简排版
| id | 风格 | 语言 | 首屏 | demo | 默认图形 | 适合 |
|---|
evidence | 证据优先 | 双语 | banner | GIF | arcs | 有基准/测试的工程仓库 |
terminal | 终端工具 | 双语 | 居中 logo | GIF | prompt | 有品牌 logo 的命令行工具 |
mobile | 移动端 · 社群 | 中文优先 | banner | 截图 | orbit | App / 移动端 / 社群产品 |
playful | GIF 开场 · 教程 | 英文优先 | logo | GIF | bubble | TUI / 开发者工具 |
product | 品牌产品页 | 英文优先 | 品牌 banner | 截图 | radar | 面向普通用户的产品 |
platform | 面板平台 | 双语 | 居中 logo | GIF | hexstack | 面板 / 平台 |
minimal | 极简排版 | 英文优先 | 无图 | 无 | monogram | 成熟工具 / 框架 |
选择建议、每个预设的章节顺序、以及“优秀仓库的 12 个共性”写在 docs/STYLES.md。
自定义风格
7 个内置风格不是代码，是 7 份 JSON 数据（styles/*.json）。你自己的风格也是 JSON：放在仓库的 .tailor/styles/ 或本机的 ~/.tailor/styles/，加载时自动合并、校验，无需改逻辑。
cp styles/evidence.json .tailor/styles/acme.json
# 改成自己的 id / 文案 / 调色板，然后
node bin/tailor.mjs styles . # 看到 acme（repo 来源）
node bin/tailor.mjs readme . --style=acme --lang=both
也可以从现有风格继承，只覆盖要改的字段：
node bin/tailor.mjs style:init . --id=acme --extends=evidence
{
"extends": "evidence",
"id": "acme",
"label": { "zh": "Acme 证据风", "en": "Acme evidence" },
"palette": { "brand": "#E4572E", "deep": "#B23A1C" },
"labels": { "install": { "zh": "开始使用", "en": "Get started" } }
}
- 加载顺序：内置 →
~/.tailor/styles → <repo>/.tailor/styles；同 id 后者覆盖前者。
extends 逐键合并：label / palette / labels 等对象合并，sections / badgeSet 数组替换。- 每个字段的含义、允许值、完整 schema 见 styles/README.md 与 styles/schema.json。
- 写坏的风格文件会被跳过并在
repo_styles 里列出文件与原因，其他风格照常可用。
- 机器可读：
tailor styles . --json（DSH 工具 repo_styles { json: true }）输出 styles / dirs / errors，给 GUI 或其他 agent 用。
- 所有工具（
repo_audit / repo_plan / repo_readme / repo_brand / repo_verify）都接受自定义 style id。
品牌素材
12 个原创图形概念：needle、stitch、quill、arcs、orbit、prompt、bubble、radar、hexstack、monogram、spark、layers
repo_brand 不是换一张模板图，而是从 12 个手写几何概念里选，配上风格调色板和明暗两套版式：
12 个图形概念逐个展示：needle、stitch、quill、arcs、orbit、prompt、bubble、radar、hexstack、monogram、spark、layers
12 个概念，每帧一个；完整对照见上面的 brand-sheet。
浅色版 banner：1280×400
明暗两套 banner / logo：深色给 README，浅色给文档与幻灯片。
| 概念 | 适合 | 概念 | 适合 |
|---|
needle 针线 | 裁缝 / 定制 / 精修 | stitch 缝线勾 | 完成 / 校验 / 交付 |
quill 羽毛笔 | 写作 / 文档 / 叙事 | arcs 上升弧 | 增长 / 指标 / 证据 |
orbit 轨道 | 网络 / 远端 / 连接 | prompt 提示符 | CLI / 终端 / 工具 |
bubble 对话泡 | 产品 / 交互 / 轻松 | radar 雷达 | 监控 / 扫描 / 安全 |
hexstack 面板栈 | 平台 / 面板 / 分层 | monogram 字母环 | 成熟工具 / 极简 |
spark 四角星 | 通用 / 品牌 / 高光 | layers 叠层 | 架构 / 模块 / 复用 |
一次生成 12 个文件：
| 文件 | 尺寸 | 用途 |
|---|
icon.svg | 512×512 | 图标 / 头像 |
icon-maskable.svg | 512×512 | PWA / Android，80% 安全区 |
logo.svg / logo-dark.svg | 760×176 | 浅色 / 深色 lockup |
wordmark.svg / wordmark-dark.svg | 760×120 | 纯文字 lockup，给 slides / 视频 |
banner.svg / banner-light.svg | 1280×400 | 深 / 浅横幅 |
social-preview.svg | 1280×640 | GitHub social preview |
brand-sheet.svg | 1280×auto | 12 概念对照 + 调色板对比度 |
brand-tokens.json | — | 调色板 / 对比度 / 字体 / 间距 / 动效 token |
assets/README.md | — | 素材索引、用法与切换命令 |
调色板会先做 WCAG 检查，再写进 brand-tokens.json：正文对比 ≥7:1、图形 ≥3:1，repo_brand dry-run 直接列出每一项。
node bin/tailor.mjs brand . --style=evidence --concept=needle \
--tagline="From it runs to ship it." --apply --force
默认 dry-run 只列文件、概念和对比度；apply 才写盘，已有文件默认跳过。
视觉系统
视觉不是“加一张 banner”，而是一套可解释的规则。设计与动效原则写在 docs/DESIGN.md（来自 emotion-design / apple-design / hallmark：先定情绪、动效必须有信息量、不画假终端 chrome、间距与字号进 token）。
Logo 构造动效：网格 → mark → tile → lockup → identity，每拍都有说明
标记构造：6 拍、约 3 秒；最后一拍停 2 秒，不做装饰性循环。
3 套版式引擎，写进风格 JSON 的 visual 字段，自定义风格也能选：
| engine | 用它的风格 | 首屏 | 导航 | demo | 特点 |
|---|
editorial | evidence / minimal | 左对齐 banner 或纯文字 | inline 链接 | 720–760px | 像长文，信息密度高 |
centered | terminal / platform | 居中 logo + 居中 H1 | <kbd> chips | 760px | 像产品主页，锚点明确 |
showcase | mobile / playful / product | 全宽 banner + 居中 H1 | <kbd> chips | 860px | 像发布页，视觉先行 |
可配置项：engine、badgeStyle（flat-square / for-the-badge）、demoWidth、navStyle、featureCards、footer；schema 见 styles/README.md。
视觉检查现在是 14 项（品牌维度权重 20%）：logo 尺寸/比例、明暗配对、banner 比例、social 2:1、maskable、wordmark、tokens、demo 资产、README 图片数、alt 覆盖率、首屏图位置、图片宽度控制等。repo_audit 会把这些缺口按影响排序。
工具输出
真实 CLI 输出，不是示意图；截图由实际 stdout 渲染，命令写在图里。
repo_styles 输出：7 个风格的 id、语言、首屏和说明
tailor styles：只描述风格本身，不带仓库名。
repo_brand dry-run：12 个文件、12 个概念与对比度 QA
tailor brand . --style=evidence --concept=needle：dry-run 列出 12 个文件、12 个概念和 6 项对比度检查。
repo_verify PASS 输出：链接、图片、锚点、章节、TODO 逐项通过
tailor verify：PASS 时逐项列出链接、图片、锚点、章节与 TODO。
效果与证据
repo_audit 对 dsh-plugin-resolver 的真实输出：81/100，B 级，10 个缺口
- 自举：本仓库用自己补文档/品牌/README，审计分 37 → 100（D → A）；
dsh-plugin-resolver 审计 81/100（B），repo_verify 返回 PASS。
- 测试：18 项离线测试（
npm test，pass 18 / fail 0），CI 在 Node 20/22/24 上跑。
- 纯逻辑耗时：
auditFacts 0.01 ms、renderReadme 0.03 ms、verifyFacts 0.03 ms；collectFacts 因为要起 4 个 git 子进程约 109–794 ms（视仓库大小）。
- CLI 端到端：
tailor audit . 中位数 248 ms，其中约 200 ms 是 Node 启动。
- 口径：环境、方法、输出体积都写在 BENCHMARK.md；自举前后与测试输出在 docs/EVIDENCE.md。
结构
index.js host half：注册工具、热加载 logic
host/register.js tool schema（稳定，改动需重启）
logic/
api.js 6 个工具入口
facts.mjs 只读仓库事实
rubric.mjs 8 维 44 项检查
plan.mjs gaps → P0/P1/P2 任务
styles.mjs 风格加载器（JSON + 自定义 + extends + 校验）
style-schema.mjs 风格 schema 与合并规则
readme.mjs 双语草稿、版式引擎、diff、apply 安全
brand.mjs 12 概念品牌引擎（12 文件 + 对比度 QA）
palette.mjs 色彩、对比度、设计 tokens
verify.mjs 链接/锚点/图片/章节/TODO
util.mjs diff、slug、路径边界
styles/ 7 个内置风格 JSON + schema.json + 说明
bin/tailor.mjs CLI（和工具共用逻辑）
bench/micro.mjs 纯逻辑基准
docs/ SPEC / STYLES / DESIGN / ACCEPTANCE / EVIDENCE
test/tailor.test.mjs 18 项离线测试
测试与 CI
npm test # 18 项离线测试
node bench/micro.mjs . # 纯逻辑微基准
node bin/tailor.mjs verify . --style=evidence
- 测试覆盖：风格注册与 JSON schema、自定义风格加载/extends/错误跳过、facts、audit 排序、plan、README 渲染/落盘安全、品牌确定性、坏链/坏图/坏锚点、宿主注册、CLI。
- CI：
.github/workflows/test.yml，Node 20/22/24 矩阵，跑 npm test、CLI smoke、npm pack --dry-run。
GitHub Actions：Node 20/22/24 矩阵全部通过，19 秒
真实 CI：Node 20 / 22 / 24 三个 job 全绿，19 秒。
已知限制
- 分数衡量结构与证据是否存在，不衡量文笔：100 分不代表 README 好读，最终判断仍要人做。
- 草稿必须人工校对：
TODO(tailor) 是给你填的；repo_verify 会把剩余 TODO 作为 warn 报出来。
- 只做 zh / en，不做其他语言；不自动选风格；不自动 commit / push / 发布。
- 不生成真实截图或图片：
repo_brand 只生成 SVG 几何和 tokens，demo GIF/截图需要用真实运行另外录。
- 动效是 GIF 演示，不是可交互动画：
mark-motion.gif 只解释构造过程；README 无法响应 prefers-reduced-motion。
- 品牌素材是几何 SVG，不是插画/摄影：需要插画级视觉时仍要人或模型来画；
repo_brand 保证的是概念选择、12 文件、明暗两套、对比度 QA、一致性和可重复生成。
- 自定义风格写坏会被跳过：
repo_styles 会列出文件和原因；加载器不猜测、不自动修复。
collectFacts 是主要耗时项（git 子进程 + 文件遍历），纯判断逻辑可以忽略不计。- SVG 字宽依赖系统字体：Inter / Segoe UI / 微软雅黑，不同机器上文字宽度略有差异。
- npm 包与插件包同名：插件用
dsh-plugin-tailor，CLI 命令是 dsh-repo-tailor（也可 npx dsh-plugin-tailor）；发布流程见 PUBLISHING.md。
权限与安全边界
| 动作 | 边界 |
|---|
| 读取 | 只读仓库内文件 + git status/log/tag；插件自身不联网 |
写入（仅 apply: true） | README.md / README.en.md / assets/*.svg / assets/README.md / .tailor/baseline.json |
| 拒绝 | 路径逃逸（../）、手写 README 未 force、已有素材未 force、worktree 脏且未 force |
| 不做 | 不执行仓库脚本、不 npm install、不 commit / push / 发布、不调用图片模型 |
| 依赖 | 只用 Node 标准库；无运行时依赖 |
FAQ
和“README 模板”有什么区别？
模板给结构；这里给 8 维审计、按风格生成、写保护、发布前校验。事实来自仓库，缺失就写 TODO，不编数字。
会覆盖我手写的 README 吗？
默认拒绝。只有带 generated-by 标记的文件才允许再生成；否则必须显式 force。
需要联网吗？
不需要。徽章图片是 GitHub 渲染时去 shields.io 加载的；插件本身不发请求。
支持哪些语言和风格？
zh / en 两种页面；7 种风格：evidence、terminal、mobile、playful、product、platform、minimal。旧命令里的 id 仍可用。
为什么 100 分还要人工看？
分数只衡量结构、证据、品牌是否存在，不衡量文笔和事实正确性；发布前仍要人读一遍。
npm 什么时候发？
已经发布：dsh-plugin-tailor@0.5.0（latest 指向当前版本）。
路线图
生态与收录
反馈与安全
License
MIT
Built for DeepSeek Harness · 属于 dsh-plugins 插件集 · 回到顶部 ↑
如果它帮你省了时间，点个 ⭐ 让更多人看到。
