仓库发布打磨 sakikoTGW/dsh-plugin-tailor

简体中文 · English

dsh-plugin-tailor

把仓库从「能跑」改到「敢发布」：审计 → 选风格 → 品牌素材 → 双语 README → 发布前校验。

MIT · Node >=20 · DSH >=0.2.0-rc.2 <0.3.0 · v0.4.1

安装 · 七种风格 · 六个工具 · 路线图

真实输出：tailor audit ../dsh-plugin-resolver 与 tailor verify …（VHS tape 可重录）

目录

- 为什么需要它
- 怎么工作
- 功能
- 快速开始
- 六个工具
- 七种风格
- 自定义风格
- 品牌素材
- 工具输出
- 效果与证据
- 结构
- 测试与 CI
- 已知限制
- 权限与安全边界
- FAQ
- 路线图
- 生态与收录
- 反馈与安全
- License

为什么需要它

- README 停在「能跑」：安装命令藏在 docs 里、demo 是随手截图、限制一条不写；项目越好，越吃亏在表达。
- 每换一个仓库就重做一遍：首屏、徽章、目录、素材、发布检查，全是重复劳动，风格还无法复用。
- 发布前没人检查：相对链接、锚点、图片、TODO、测试数量过期，通常等读者发现。
- 「好看」没有标准：与其模仿某一个模板，不如把优秀仓库的共性拆成可选的风格预设 + 可执行的检查项。

本插件做的事：把仓库成熟度拆成 8 维 34 项检查，把 README 风格拆成 7 个预设，把品牌素材变成确定性 SVG，把发布前检查变成一条 repo_verify。

怎么工作

1. repo_audit：读 package.json、README、assets、CI、git 状态，按 8 维 34 项检查打分，输出按影响排序的缺口。
2. repo_plan：把缺口变成 P0/P1/P2 任务；每条带验收标准与 repo_verify 命令，风格缺口（缺 GIF、缺截图、缺英文页）也进任务。
3. repo_brand：按所选风格的调色板与图标字形，生成 icon.svg / logo.svg / banner.svg / social-preview.svg；确定性、无图片模型、不覆盖已有文件。
4. repo_readme：按风格组装 zh/en 草稿；只使用仓库真实事实，缺失项变成 TODO(tailor)；默认 dry-run 给 diff，apply 才落盘。
5. repo_verify：复跑审计 + 相对链接、图片、锚点、徽章、必需章节、剩余 TODO 检查，报告 PASS/FAIL 与 baseline 分数差。

功能

- 8 维 34 项审计：身份、首屏、安装、文档、证据、发布、社区、品牌；每条缺口都带具体修法，不只是打分。
- 7 种风格 + 双语草稿：从证据优先到极简排版，先看 diff 再落盘。
- 风格可自创：内置风格是 7 份 JSON；自定义放在 .tailor/styles/ 或 ~/.tailor/styles/，支持 extends 继承与 schema 校验。
- 12 个原创图形概念 × 明暗双版：icon / logo（明暗）/ banner（明暗）/ social / brand-sheet 共 8 个文件；同一仓库重复生成字节一致。
- 写保护：手写 README、已有素材、脏 worktree 默认拒绝，必须显式 force。
- 发布前校验：相对链接、图片、锚点、徽章、必需章节、剩余 TODO，一条命令给出 PASS/FAIL。
- CLI 与 DSH 工具同源：bin/tailor.mjs 和六个工具调用同一套 logic，终端里能复现。

快速开始

已发布到 npm 与 GitHub Release（v0.4.1）。三种装法：

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.4.1.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 # 自创风格

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? | 8 个文件（12 概念可选） |
| repo_verify | 读 | path、style? | PASS/FAIL、逐项检查、剩余 TODO、分数差 |

写操作默认 dry-run；手写 README 或已有素材默认拒绝/跳过，必须显式 force 才覆盖；worktree 脏且未 force 时直接拒绝。

七种风格

| 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 或其他智能体用。
- 所有工具（repo_audit / repo_plan / repo_readme / repo_brand / repo_verify）都接受自定义 style id。

品牌素材

repo_brand 不是换一张模板图，而是从 12 个手写几何概念里选，配上风格调色板和明暗两套版式：

12 个概念，每帧一个；完整对照见上面的 brand-sheet。

logo-dark
icon

明暗两套 banner / logo：深色给 README，浅色给文档与幻灯片。

| 概念 | 适合 | 概念 | 适合 |
| needle 针线 | 裁缝 / 定制 / 精修 | stitch 缝线勾 | 完成 / 校验 / 交付 |
| quill 羽毛笔 | 写作 / 文档 / 叙事 | arcs 上升弧 | 增长 / 指标 / 证据 |
| orbit 轨道 | 网络 / 远端 / 连接 | prompt 提示符 | CLI / 终端 / 工具 |
| bubble 对话泡 | 产品 / 交互 / 轻松 | radar 雷达 | 监控 / 扫描 / 安全 |
| hexstack 面板栈 | 平台 / 面板 / 分层 | monogram 字母环 | 成熟工具 / 极简 |
| spark 四角星 | 通用 / 品牌 / 高光 | layers 叠层 | 架构 / 模块 / 复用 |

一次生成 8 个文件：

| 文件 | 用途 |
| icon.svg | 512×512 图标 / 头像 |
| logo.svg / logo-dark.svg | 浅色 / 深色 lockup |
| banner.svg / banner-light.svg | 1280×400 深 / 浅横幅 |
| social-preview.svg | 1280×640 社交卡 |
| brand-sheet.svg | 12 概念对照，默认高亮 |
| assets/README.md | 素材索引与切换命令 |

node bin/tailor.mjs brand . --style=evidence --concept=needle \
--tagline="From it runs to ship it." --apply --force

默认 dry-run 只列文件和概念；apply 才写盘，已有文件默认跳过。

工具输出

真实 CLI 输出，不是示意图；截图由实际 stdout 渲染，命令写在图里。

tailor styles：只描述风格本身，不带仓库名。

tailor brand . --style=evidence --concept=needle：dry-run 列出 8 个文件和 12 个概念。

tailor verify：PASS 时逐项列出链接、图片、锚点、章节与 TODO。

效果与证据

- 自举：本仓库用自己补文档/品牌/README，审计分 37 → 100（D → A）；dsh-plugin-resolver 审计 84/100（B），repo_verify 返回 PASS。
- 测试：16 项离线测试（npm test，pass 16 / 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 维 34 项检查 plan.mjs gaps → P0/P1/P2 任务 styles.mjs 风格加载器（JSON + 自定义 + extends + 校验） style-schema.mjs 风格 schema 与合并规则 readme.mjs 双语草稿、diff、apply 安全 brand.mjs 12 概念品牌引擎（明暗双版） verify.mjs 链接/锚点/图片/章节/TODO util.mjs diff、slug、路径边界 styles/ 7 个内置风格 JSON + schema.json + 说明 bin/tailor.mjs 命令行（和工具共用逻辑） bench/micro.mjs 纯逻辑基准 docs/ SPEC / STYLES / ACCEPTANCE / EVIDENCE test/tailor.test.mjs 16 项离线测试

测试与 CI

npm test # 16 项离线测试
node bench/micro.mjs . # 纯逻辑微基准
node bin/tailor.mjs verify . --style=evidence

- 测试覆盖：风格注册与 JSON schema、自定义风格加载/extends/错误跳过、facts、audit 排序、plan、README 渲染/落盘安全、品牌确定性、坏链/坏图/坏锚点、宿主注册、命令行。
- CI：.github/workflows/test.yml，Node 20/22/24 矩阵，跑 npm test、命令行 smoke、npm pack --dry-run。

真实 CI：Node 20 / 22 / 24 三个 job 全绿，19 秒。

已知限制

- 分数衡量结构与证据是否存在，不衡量文笔：100 分不代表 README 好读，最终判断仍要人做。
- 草稿必须人工校对：TODO(tailor) 是给你填的；repo_verify 会把剩余 TODO 作为 warn 报出来。
- 只做 zh / en，不做其他语言；不自动选风格；不自动 commit / push / 发布。
- 不生成真实截图或图片：repo_brand 只生成 SVG 几何，demo GIF 需要用真实运行日志另外录。
- 品牌素材是几何 SVG，不是插画/摄影：需要插画级视觉时仍要人或模型来画；repo_brand 保证的是概念选择、明暗两套、一致性和可重复生成。
- 自定义风格写坏会被跳过：repo_styles 会列出文件和原因；加载器不猜测、不自动修复。
- collectFacts 是主要耗时项（git 子进程 + 文件遍历），纯判断逻辑可以忽略不计。
- SVG 字宽依赖系统字体：Inter / Segoe UI / 微软雅黑，不同机器上文字宽度略有差异。
- npm 包与插件包同名：插件用 dsh-plugin-tailor，命令行命令是 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 什么时候发？ 见路线图。现在用 GitHub Release 里的 .tgz。

路线图

- [x] v0.1 8 维审计、P0–P2 规划、双语草稿、发布前校验
- [x] v0.2 12 个原创图形概念、明暗两套品牌套件、brand-sheet
- [x] v0.3 风格去仓库名、真实命令行截图、demo 重录
- [x] v0.4 风格结构化（JSON + schema）、自定义风格、extends、style:init
- [ ] v0.4 npm 发布 + dsh-plugins hub 收录
- [ ] v0.4 --palette 配色（暖色 / 高对比 / 单色 / 跟随品牌主色）
- [ ] v0.5 同一仓库多风格并排预览（截图，不靠自引用）
- [ ] v0.5 可选图像模型插画模式（PNG，不替代 SVG 几何）

生态与收录

- 装插件：dsh-plugin-resolver（用一条工具调用装对版本）
- 索引：dsh-plugins（catalog.json 是唯一事实源）
- 移动端适配：dsh-plugin-resolver-dshgo
- 收录状态：GitHub Release ✅ · npm ⏳ · hub catalog ⏳

反馈与安全

- 问题与建议：<https://github.com/sakikoTGW/dsh-plugin-tailor/issues>
- 安全问题：请走 Security → Advisories → Report a vulnerability（私密报告，见 SECURITY.md）
- 贡献指南：CONTRIBUTING.md · 发布流程：PUBLISHING.md

License

MIT

为 DeepSeek Harness 打造 · 属于 dsh-plugins 插件集 · 回到顶部 ↑

如果它帮你省了时间，点个 ⭐ 让更多人看到。