npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

dsh-arch-doc

v0.1.5

Published

DSH arch-doc skill plugin: analyze a codebase and generate architecture documentation (module responsibilities, dependencies, entry points and run methods).

Readme

arch-doc

English | 简体中文

License: MIT DeepSeek Harness CI dsh-index version

DSH 技能插件:输入代码库路径,自动生成架构文档(模块职责、依赖关系、入口点、运行方式)。

npm 包名为 dsh-arch-doc(原名 arch-doc 因 npm 防抢注拦截不可用,2026-09-02 改名);GitHub 仓库名与插件 id 保持 arch-doc,两者指向同一项目。

定位

arch-doc 是架构文档生成插件:扫描器只提取硬事实(语言、目录、依赖、入口点等确定性信息),语义总结由 LLM 按固定模板补充并标注推断。

它回答:

  • 这是什么类型的项目(语言 / 框架 / 构建系统 / 仓库类型)?
  • 模块怎么划分,各自负责什么?
  • 内部 / 外部依赖是什么关系?
  • 入口点在哪(CLI / Web / Worker / Scheduler / Library)?
  • 怎么安装、开发、构建、测试、运行、部署?

边界:扫描过程只读,不执行目标仓库代码;扫描器零依赖、无子进程、无网络。

安装

作为 DSH 插件(推荐):

dsh plugin --profile web add "github:duyanta123/arch-doc#v0.1.5"

或从 npm 安装:

npm install dsh-arch-doc

兼容性分层:独立脚本 scripts/arch-profile.mjs 可运行在 Node.js >= 18(无 Node 环境时 runbook 自动降级为 shell 手工探测,结论质量略降但流程完整);作为 DSH 0.2.1-rc.2 插件验证统一使用 Node.js >= 22.19。运行 npm run test:compat 可执行隔离 profile 的 add、dump-config 和启动 smoke test。

本地开发:profile 的 package.json 加 "arch-doc": "file:<本地路径>/arch-doc",bundles 数组加 "arch-doc",然后重启 profile。

快速开始

1. 作为 DSH 技能使用

安装后重启 profile,对 Agent 说:

用 arch-doc 分析 /path/to/repo

技能按 runbook 执行:先跑扫描脚本取事实,再按模板生成文档,写入目标仓库的 docs/ 下(见「输出」)。

2. 作为独立 CLI 使用

node scripts/arch-profile.mjs <repo_path> --probe
node scripts/arch-profile.mjs <repo_path> --scan --max-depth 3
node scripts/arch-profile.mjs <repo_path> --deps
node scripts/arch-profile.mjs <repo_path> --entry
node scripts/arch-profile.mjs <repo_path> --all

CLI 参数

| 参数 | 默认 | 说明 | | --- | --- | --- | | --probe | - | 识别项目类型 / 语言 / 构建系统,输出摘要 | | --scan | - | 目录扫描与模块划分(模块职责事实) | | --deps | - | 内部 / 外部依赖提取 | | --entry | - | 入口点识别(CLI / Web / Worker / Scheduler / Library) | | --all | - | 依次执行全部阶段,输出完整结果 JSON | | --max-depth <N> | 3 | 目录扫描深度(1–10) | | --include-dirs <a,b> | - | 只分析这些目录(相对 repo_path,逗号分隔) | | --exclude-dirs <a,b> | - | 额外排除目录(与内置排除目录合并,内置覆盖 node_modules、.venv 等构建产物) | | --language <L> | 自动 | 语言提示:python / javascript / typescript / go / java / kotlin / generic |

输出

对目标仓库生成三件套:

| 文件 | 用途 | | --- | --- | | docs/ARCHITECTURE.md | 结构化架构文档(按 9+1 章固定骨架:概览 / 技术栈 / 目录 / 模块职责 / 依赖关系 / 入口点 / 运行方式 / 关键流程 / 风险点 / 附录) | | docs/architecture.json | 机器可读的结构化结果 | | docs/diagrams/module-dependencies.mmd | Mermaid 模块依赖图 |

完整样例见 examples/sample-output.md:

## 1. 项目概览
- 项目名称:my-app
- 一句话描述:示例项目(Python FastAPI 服务)
- 架构风格:分层
- 仓库类型:monolith

## 2. 技术栈
- 语言:python
- 框架:fastapi、uvicorn
- 构建/运行:docker

安全边界

  • 只读扫描:扫描阶段不写入、不修改目标仓库源码,不执行目标仓库代码。
  • 零依赖运行:扫描器为单文件 Node 脚本,无第三方依赖、无子进程、无网络访问。
  • 产物限定:仅写入 docs/ 下的三个文档产物文件。
  • 降级安全:无 Node 环境时 runbook 自动降级为 shell 手工探测,不引入新依赖。

排障

生成的 ARCHITECTURE.md 里 Mermaid 图不渲染? file:// 协议下浏览器直接打开时,CDN 加载的 mermaid.js 受同源策略限制无法自动渲染;用 Typora 等本地渲染编辑器打开,或把 diagrams/module-dependencies.mmd 内容粘到 mermaid.live 查看。.mmd 源文件语法本身独立有效。

大仓库扫描太慢 / 输出太长? --max-depth 3 起步,必要时降到 2;确认 --exclude-dirs 覆盖了 node_modules、.venv、构建产物等大目录。

识别不到入口点? 先跑 --probe 确认项目类型识别正确;混合技术栈仓库以主语言构建文件为准(如 Go+Node 混合,以 go.mod 优先)。

升级 DSH 宿主到 0.1.5 系后旧会话打不开? Session format V3 迁移不可逆,属宿主行为;升级宿主前请先备份会话日志(见 CHANGELOG.md 0.1.4 条目)。

文档

License

MIT