前言¶

上传 GitHub 之前，README 往往是最后一道没做好的工序：章节没有编号、参数散落在段落里、缺少首图与过程图、排版参差不齐。DSH 插件 dsh-github-readme 把这件事变成可复现的固定流程，通过四个工具覆盖从事实扫描、结构重写、素材生成到排版校验与带重试推送的全链路。

它是什么¶

dsh-github-readme 是一个 DSH 工具插件，负责在把仓库推送到 GitHub 之前，把 README 按统一版式优化。插件通过四个工具完成一组动作：扫描仓库事实、按编号骨架重写 README、用 Pillow 渲染首图和过程图、在推送前做排版校验和文案自检，最后带重试地 commit + push。

用一句话定位：它管「事实」和「结构」，用本地渲染解决素材，用校验和自检保证推送质量。

核心能力¶

事实扫描：readme_scan 只读仓库，把 package.json、目录树、现有图片、代码中的环境变量、git remote/分支/改动一次拿全，不靠模型记忆编数字。
结构重写：按 references/README-模板.md 的编号骨架填内容，删掉不适用的小节，保持章节编号连续（1..N）。
素材生成：readme_assets 用 Pillow 渲染 1200×600 首图和自适应高度的过程图，支持 10 种首图风格与 10 套配色，不依赖在线设计工具。
排版校验：readme_lint 检查图片/相对链接是否存在、章节编号是否连续、表格分隔行与必需章节是否齐全。
文案自检：deai_audit 六维打分并逐句打标，聚焦「标签式开头/空泛词/一眼 AI」三类问题，复检至 25 分以下。
推送：readme_publish 先 dryRun 查 diff，再正式 add → commit → push，遇到网络错误自动退避重试，不 force。

优化流程¶

对应到工具，固定顺序是：

扫描仓库（readme_scan）：读 package.json、README、两层目录树、现有图片、环境变量、git 状态。只读，不改文件。
重写结构：按 references/README-模板.md 的编号骨架填内容，不适用的小节删掉，编号保持连续。
生成素材（readme_assets）：根据 plan 渲染 assets/readme/banner.png 和 flow.png。首图有 10 种风格、每种 5–6 套配色，默认随机组合；图片是 2 倍超采样后缩放的，中文使用微软雅黑。
排版校验（readme_lint）：检查图片/相对链接是否存在、## N. 编号是否连续、表格有无 |---| 分隔行、必需章节和首图是否齐全。
文案自检（deai_audit）：六维打分 + 逐句打标，先看「标签式开头 / 空泛词 / 一眼 AI」三类，改完复检到 25 分以下。
提交推送（readme_publish）：先 dryRun 看 diff，再正式 add → commit → push。

四个工具¶

工具	做什么	关键参数
`readme_scan`	扫描仓库事实，给写 README 用	`path`（本地仓库）或 `url`（GitHub 地址，会浅克隆）
`readme_assets`	渲染首图 / 过程图（10 种风格，随机配色）	`plan`（必含 `outDir`；`style`、`palette`、`seed`、`banner`、`flow`）
`readme_lint`	README 排版体检	`path`（README.md 或仓库根）；`required`（必需章节关键词）
`readme_publish`	commit + push（带重试）	`path`、`message`；可选 `branch`、`files`、`dryRun`、`retries`

readme_assets 的 plan 示例：

{
  "outDir": "<仓库根>/assets/readme",
  "style": "split",
  "palette": "violet",
  "seed": 42,
  "banner": {
    "title": "GitHub 仓库 README 优化",
    "mono": "dsh-github-readme",
    "headline": "上传 GitHub 之前，先把 README 收拾干净",
    "bullets": ["首图 + 过程图：Pillow 渲染", "编号结构 1..N", "推前自检"],
    "chips": [{ "text": "仓库扫描" }, { "text": "首图 / 过程图", "color": "blue" }],
    "leftTop": "一个本地仓库 / GitHub 链接",
    "leftCard": { "title": "README 优化后", "chips": ["banner.png", "flow.png", "lint 通过"] }
  },
  "flow": {
    "title": "优化流程：一个仓库怎么变成一份能读的 README",
    "subtitle": "6 个步骤：扫描 → 重写 → 出图 → 校验 → 自检 → 推送",
    "steps": [{ "title": "扫描仓库", "tag": "readme_scan", "desc": "读事实，不改文件" }]
  }
}

style、palette、seed 可以省略：不传 style 则随机风格；不传 palette 则在该风格可选配色里随机；seed 用于复现同一张图。

首图风格与配色¶

首图有 10 种风格，每种自带 5–6 套配色。调用时不指定 style / palette 就随机组合，返回里会带上实际用的 style、palette、seed。

#	风格 id	名称	适合
01	`split`	经典分栏	通用款，左栏图标 + 小卡，右栏标题与卖点
02	`band`	左侧色带	工具类，左栏列文件清单
03	`topbar`	顶部横幅	内容多，卖点拆成三张卡片
04	`diagonal`	对角色块	想要强视觉记忆点
05	`center`	居中构图	品牌型项目，图标标题居中
06	`terminal`	终端窗口	开发者工具 / CLI
07	`editorial`	杂志编辑	文档型项目，大标题 + 编号条目
08	`cards`	卡片网格	信息多，四格各管一摊
09	`wave`	波浪渐变	偏产品 / 创意
10	`minimal`	极简留白	标题是主角，克制

配色 10 套：ocean 蓝 / emerald 绿 / violet 紫 / amber 琥珀 / rose 玫红 / cyan 青 / indigo 靛蓝 / slate 石板灰 / lime 青柠 / sunset 落日橙。

项	规范
首图	1200×600 PNG；10 种风格，每种 5–6 套配色；默认随机
随机规则	不传 `style` → 随机风格；不传 `palette` → 该风格可选配色里随机；`seed` 固定组合
过程图	宽 1200，高度随步骤数自适应（3–6 步），配色跟随同一套 palette
旧字段兼容	`theme`（blue/green/violet/orange）自动映射到对应配色
图标	`play` / `check` / `doc` / `branch` / `bolt` / `puzzle` 六种内置字形
输出	`assets/readme/banner.png`、`flow.png`，README 用相对路径引用

默认规则¶

插件仓库里带了一份技能 github-readme-optimize（skill/ 目录）。装好后，DSH 在遇到「上传 GitHub / 推仓库 / 发插件 / 优化 README」这类任务时会按这套流程执行。

想让「上传 GitHub 前默认优化 README」对所有会话生效，把下面这段加进 ~/.dsh/AGENTS.md：

## GitHub 上传前默认优化 README

- 只要要往 GitHub 推内容（新建仓库、git push、发布插件），先按 `github-readme-optimize` 技能优化 README 再推。
- 顺序：readme_scan → 写编号 README → readme_assets 出图 → read_image 自查 → readme_lint → deai_audit → readme_publish。
- 工具没加载（旧会话）：直接跑 `~/.dsh/profiles/desktop/node_modules/dsh-local-github-readme/scripts/render_readme_assets.py`。
- 例外：用户明确说「先别改 README，直接推」。

安装与启用¶

前置条件：

Windows 10 / 11：图片渲染使用系统自带微软雅黑（C:\Windows\Fonts\msyh.ttc），其他系统需修改字体路径。
DSH 桌面版：已实测 0.2.1-rc.2，需要支持 ctx.tools 工具注册的版本。
Python + Pillow：优先用 DSH 自带 Python 运行时（自带 Pillow）；也可用 GITHUB_README_PYTHON 指定解释器。
git：readme_publish 使用本机 git 和已保存的凭据推送。

命令行安装（DSH 桌面版一般用 desktop，dsh web 用 web）：

dsh plugin --profile desktop add github:zz12hui/dsh-github-readme

装完重启 DSH（关闭窗口含托盘退出 → 重开 → 恢复会话）。装完插件后，想让「上传 GitHub 前默认优化 README」对所有会话生效，再装技能、加 AGENTS.md 规则。

手动安装（旧版 / 离线环境）：

git clone https://github.com/zz12hui/dsh-github-readme.git

把仓库内容复制到 %USERPROFILE%\.dsh\profiles\desktop\node_modules\dsh-local-github-readme\。目录名保持 dsh-local-github-readme（与 package.json 的 name 一致）。
在 %USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml 末尾追加：

   - insert:
       - id: github-readme-panel
         name: 'dsh-local-github-readme'

装技能（可选但推荐）：把 skill/ 下的内容复制到 %USERPROFILE%\.dsh\skills\github-readme-optimize\；用 dsh plugin add 装的，skill/ 在 %USERPROFILE%\.dsh\profiles\desktop\node_modules\dsh-local-github-readme\skill\。
在 ~/.dsh/AGENTS.md 末尾加上默认规则。
重启 DSH。插件和技能都在启动时加载，刷新页面不会加载它们。

验证¶

重启后让助手「扫一下这个仓库的 README 情况」，应该看到 readme_scan 被调用；再让它「给这个仓库出首图和过程图」，应该调用 readme_assets。

适用场景与注意¶

适合在需要把 README 统一版式、增加首图和过程图、统一章节编号、推送前做排版与文案自检的仓库上使用。

插件以当前 DSH 进程权限运行。安装前建议检查源码与许可证。社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系，不要写成官方应用商店。

短结尾¶

dsh-github-readme 把 README 优化从「靠人力临时补」变成「固定流程」，适合需要统一风格与质量的仓库。目录页与 GitHub 链接见下方。

https://www.skillhub.cn/plugins/zz12hui/dsh-github-readme
https://github.com/zz12hui/dsh-github-readme

DeepSeek Harness 插件：dsh-github-readme

前言¶

它是什么¶

核心能力¶

优化流程¶

四个工具¶

首图风格与配色¶

默认规则¶

安装与启用¶

验证¶

适用场景与注意¶

短结尾¶

精选优惠券

DeepSeek Harness 插件：dsh-github-readme

前言¶

它是什么¶

核心能力¶

优化流程¶

四个工具¶

首图风格与配色¶

默认规则¶

安装与启用¶

验证¶

适用场景与注意¶

短结尾¶

精选优惠券

相关文章