dsh-llms-forge

Readme

# dsh-llms-forge

[![npm](https://img.shields.io/npm/v/dsh-llms-forge.svg)](https://www.npmjs.com/package/dsh-llms-forge)

[![CI](https://github.com/zoahdev/dsh-llms-forge/actions/workflows/ci.yml/badge.svg)](https://github.com/zoahdev/dsh-llms-forge/actions)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![dsh-plugin](https://img.shields.io/badge/dsh--plugin-verified-blue)](https://github.com/topics/dsh-plugin)

Generate **llms.txt** for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) plugin repositories from `package.json` + `README.md`.

AI agents look for `llms.txt` first when they land in a repository. Most dsh plugins don't have one — this plugin creates it deterministically and keeps it honest: title from the package name, summary from the description (or the README's first paragraph), and key facts (install command, license, homepage, keywords, entry, CLI). Read-only by default; writing is explicit.

## Install

```sh
dsh plugin add dsh-llms-forge
```

Or run standalone:

```sh
npx dsh-llms-forge .
```

## CLI

```sh
dsh-llms-forge [dir] [--write] [--overwrite] [--json]
```

- Prints the proposed `llms.txt` to stdout (no writes by default).
- `--write` writes the file; `--overwrite` replaces an existing one.
- Exit codes: `0` clean, `1` warnings, `2` usage/IO error.

```sh
npx dsh-llms-forge . --write --overwrite
npx dsh-llms-forge ./my-plugin --json
```

## In-harness usage (agent-callable)

Ask your dsh agent:

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

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

## What the generated file looks like

```markdown
# dsh-dep-audit

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

## Key facts

- Install: dsh plugin add dsh-dep-audit
- License: MIT
- Homepage: https://github.com/zoahdev/dsh-dep-audit
- Keywords: deepseek-harness, dsh, ...
- Entry: lib/index.js
- CLI: dsh-dep-audit
- Version: 0.1.0

> Generated by dsh-llms-forge. Keep this file in sync with README.md and package.json.
```

## Why it exists

- The `llms.txt` convention is the fastest way for AI agents to understand a repository, yet most dsh plugins ship without one.
- Hand-written llms.txt files drift out of date; generated ones are reproducible and CI-checkable (`--json`, exit code).
- Zero runtime dependencies, read-only by default — safe to run anywhere.

## Development

```sh
pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration
```

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

## License

MIT © 2026 zoahdev

---

# dsh-llms-forge（中文）

为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）插件仓库**自动生成 llms.txt**（AI 可读发现文件），数据源是 `package.json` + `README.md`。

AI agent 进入仓库时最先找的就是 `llms.txt`，但绝大多数 dsh 插件没有。本插件把它确定性生成并保持诚实：标题取包名，摘要取 description（或 README 第一段），关键事实（安装命令、许可证、主页、关键词、入口、CLI）自动收集。默认只读，写盘需显式开启。

## 安装

```sh
dsh plugin add dsh-llms-forge
```

独立使用：

```sh
npx dsh-llms-forge .
```

## CLI

```sh
dsh-llms-forge [dir] [--write] [--overwrite] [--json]
```

- 默认只把生成的 `llms.txt` 打印到 stdout，不写盘。
- `--write` 写盘；`--overwrite` 覆盖已有文件。
- 退出码：`0` 干净，`1` 有警告，`2` 用法/IO 错误。

```sh
npx dsh-llms-forge . --write --overwrite
npx dsh-llms-forge ./my-plugin --json
```

## 在 harness 内使用（agent 可调用）

对 agent 说：

> 给这个插件仓库生成一份 llms.txt：`llms_forge`，目录指向仓库根目录，写入并覆盖。

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

## 为什么需要它

- llms.txt 是 AI agent 理解仓库最快的方式，但大多数 dsh 插件没有。
- 手写 llms.txt 会漂移过期；生成式可复现、可进 CI（`--json` + 退出码）。
- 零运行时依赖、默认只读，任何环境都能安全跑。

## 开发

```sh
pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration
```

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

## 许可证

MIT © 2026 zoahdev
## Related ecosystem tools

- [dsh-dep-audit](https://github.com/zoahdev/dsh-dep-audit) - dependency supply-chain hygiene
- [dsh-quality-score](https://github.com/zoahdev/dsh-quality-score) - plugin quality scorecard + full-registry leaderboard
- [dsh-ecosystem](https://github.com/zoahdev/dsh-ecosystem) - health scan, impact, trend, live dashboard
- [dsh-tutorials](https://github.com/zoahdev/dsh-tutorials) - bilingual plugin pipeline tutorials
## FAQ

- **How do I install?** dsh plugin add dsh-llms-forge or run the CLI directly (see README).
- **Does it need an API key?** No.
- **Is it read-only?** Yes by default; any write/apply is an explicit flag.
## Examples

See the README for full CLI usage. Quick start:

```sh
npx dsh-llms-forge --help
```