zoahdev / dsh-readme-forge

dsh-readme-forge

Generate a README.md for DeepSeek Harness (dsh) plugin repositories from package.json + cordis.patch.yml + source layout.

Every new plugin needs a README before it can be found by humans or AI. This one builds a deterministic starter: title, description, install command, CLI, tools (from cordis.patch.yml), development, and license — then you polish. Read-only by default; writing is explicit. The companion to dsh-llms-forge (which generates llms.txt from the README you just forged).

Install

dsh plugin add dsh-readme-forge

Or run standalone:

npx dsh-readme-forge .

CLI

dsh-readme-forge [dir] [options]

  --write        write README.md to disk
  --overwrite    replace an existing README.md (only with --write)
  --no-tools     omit the Tools section from cordis.patch.yml
  --no-dev       omit the Development section
  --json         print the machine-readable dsh-readme-forge/v1 result
  --help         show this help

Exit codes: 0 clean, 1 warnings, 2 usage/IO error.

npx dsh-readme-forge . --write --overwrite
npx dsh-readme-forge ./my-plugin --no-tools --json

In-harness usage (agent-callable)

Ask your dsh agent:

给这个插件仓库生成一份 README：readme_forge，目录指向仓库根目录，写入并覆盖。 Generate a README for this plugin repo: readme_forge with dir set, then write: true, overwrite: true.

The tool returns a dsh-readme-forge/v1 result with the proposed content and warnings, and writes the file only when options.write is true.

What it generates

# dsh-dep-audit

Dependency supply-chain hygiene audit for DeepSeek Harness ...

## Install

dsh plugin add dsh-dep-audit

## CLI

npx dsh-dep-audit --help

## Tools

- `dep_audit`

## Development

pnpm install && pnpm typecheck && pnpm build && pnpm test

## License

MIT © 2026 zoahdev

> Generated by dsh-readme-forge. Keep this file in sync with package.json and cordis.patch.yml.

Why it exists

• The ecosystem grows by thousands of plugins per week; most lack a README, and hand-writing one from scratch is the #1 first-hour friction for new plugin authors.
• Generated READMEs are deterministic and CI-checkable (--json, exit code) — the llms-forge pipeline starts where this one ends.
• Zero runtime dependencies, read-only by default, safe to run anywhere.

Development

pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration

CI runs the dsh-plugin-doctor preflight, unit tests, packed-artifact integration (real readme_forge invocation), and a fresh-profile dsh web boot smoke on Windows.

License

MIT © 2026 zoahdev

---

dsh-readme-forge（中文）

为 DeepSeek Harness（dsh）插件仓库生成 README.md：数据源是 package.json + cordis.patch.yml + 源码目录结构。

每个新插件在被人类或 AI 发现之前都需要 README。本插件生成确定性起始文档：标题、描述、安装命令、CLI、工具（取自 cordis.patch.yml）、开发与许可证——之后再人工润色。默认只读，写盘需显式开启。与 dsh-llms-forge 互补（它从刚生成的 README 再生成 llms.txt）。

安装

dsh plugin add dsh-readme-forge

独立使用：

npx dsh-readme-forge .

CLI

dsh-readme-forge [dir] [options]

  --write        把 README.md 写到磁盘
  --overwrite    覆盖已有 README.md（需配合 --write）
  --no-tools     省略 cordis.patch.yml 的 Tools 小节
  --no-dev       省略 Development 小节
  --json         输出机器可读 dsh-readme-forge/v1 结果
  --help         帮助

退出码：0 干净，1 有警告，2 用法/IO 错误。

npx dsh-readme-forge . --write --overwrite
npx dsh-readme-forge ./my-plugin --no-tools --json

在 harness 内使用（agent 可调用）

对 agent 说：

给这个插件仓库生成一份 README：readme_forge，目录指向仓库根目录，写入并覆盖。

工具返回 dsh-readme-forge/v1 结果（含生成内容与警告），仅在 options.write 为 true 时写盘。

为什么需要它

• 生态每周新增上千插件，多数没有 README；从零手写是插件作者第一小时的常见摩擦。
• 生成式 README 可复现、可进 CI（--json + 退出码）——llms-forge 管道的起点就在这里。
• 零运行时依赖、默认只读，任何环境都能安全跑。

开发

pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration

CI 跑 dsh-plugin-doctor 预检、单元测试、打包集成（真实 readme_forge 调用）、Windows 全新 profile 的 dsh web 启动冒烟。

许可证

MIT © 2026 zoahdev