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

want-a-init

v0.2.0

Published

Model-driven /init command for DeepSeek Harness: analyzes the current project and generates/updates a high-signal AGENTS.md.

Readme

want-a-init

DeepSeek Harness 的模型驱动 /init 命令:让 agent 自己读你的仓库,写出一份仓库特有、可验证、不膨胀的 AGENTS.md——并把"持续维护它"变成 agent 运行时的常驻意识,而不是一次性仪式。

Version: 0.2.0 License: MIT DSH: Web Profile


为什么不是"又一个 AGENTS.md 模板生成器"

模板生成器只会产出通用建议("写测试"、"保持代码整洁"),这类文字对未来会话零价值——任何一个称职的模型本来就会做。AGENTS.md 真正值钱的只有三类东西:

  1. 本仓库独有的命令——构建顺序、单测怎么单跑、必须先生成再类型检查的那种顺序依赖;
  2. 不读代码就会踩的坑——生成物不能手改、需要哪个常驻服务、快照什么时候会漂;
  3. 边界与所有权——哪个目录是核心、哪个包不能反向依赖。

/init 的全部设计都围绕"只留这三类、其余全删"。它有骨架但不写死模板:骨架只是提出该回答的问题,答案必须来自仓库证据。

快速开始

# 从 GitHub 安装
dsh plugin --profile web add github:mexiaosqwq/want-a-init

# 或从本地 checkout 安装
dsh plugin --profile web add /path/to/want-a-init

dsh web          # 重启后生效

然后在任意会话里:

/init

agent 会在同一回合内只读调查仓库、写入 AGENTS.md、回报改了什么、删了什么陈旧内容。写盘范围绝对锁死在这一个文件:源码、配置、docs/、CLAUDE.md、子包/子目录的 AGENTS.md 一律不改,自由文本也无法给这些文件开后门(子包的 AGENTS.md 只作为上下文读取,不写)。

本地 link: 安装前置条件:仓库内必须先 pnpm install。否则插件解析不到 @deepseek-ai/dsh-llm,/init 根本不会出现在客户端(见排错)。

用法

| 输入 | 模式 | 行为 | |---|---|---| | /init | 默认合并 | 已有文件→原地改进:保留仍然正确的规则,删掉陈旧/通用内容,与当前代码对齐 | | /init force | 覆盖 | 先列出将被丢弃的既有条目;git 已跟踪→同回合重建;未跟踪(含尚未 git init 的目录,视同最严格情形)→等用户确认;文件不存在→跳过护栏直接创建 | | /init minimal | 裁剪 | 只留生存必需的事实:Project 身份、精确 Commands(含顺序)、关键 Pitfalls;Layout 压到 2–5 行;可省略 Architecture / Docs / Maintenance | | /init detailed | 展开 | 允许展开模块边界、数据/控制流、测试前置与夹具、环境搭建、可复用的 playbook——但每条仍须挣得自己的上下文成本 | | /init 只补 Commands,别动其他 | 自由文本 | 选项之外的任何输入都会原样交给模型解释,不对整句做模式猜测——包括"要不要更精简""要不要覆盖"这类意图,都由模型读语义后决定,不用正则去嗅 |

几处刻意设计:

  • 选项解析是严格的:只有输入(忽略空白与逗号后)全部由 force / minimal / detailed 组成才当选项处理。所以「别 force」这类否定句不会误触发——它整句作为自由文本交给模型。
  • minimal 与 detailed 同时给出:minimal 胜出,回复里会明确提示冲突。
  • 模式差异在"授权",不在提示词长度:默认 / minimal / detailed 三档提示词几乎等长(61 / 62 / 61 行),换掉的是整块 Detail level: 授权。默认档面向"该写的都写、别灌水",minimal 才是明确授权砍段。
  • 自由文本不走正则嗅探:buildPrompt 全文只在一处用正则——把用户输入里的 </user_guidance> 中和掉,防止分隔符被从内部逃逸。像 /init minimal,重点写测试 这种混合输入不会被提升成 minimal 模式(Detail level: 块会如实显示 default),但解释句里已经写明"要精简就压 Layout、砍 Architecture/Docs/Maintenance",模型照办即可。少一条正则、少一条分支、少一层误判。
  • /init 不自己写文件:命令只负责把调研指令注入为上下文(source.kind != 'user',客户端渲染成折叠的 context 行而非人类气泡),写盘由 agent 完成。中途取消则什么都不投递。

产出形态

八个可选段落,没有可验证内容的段落直接省略,不留占位符:

# <项目名>

## Project       一行身份 + 技术栈 + 真实入口 + 包边界
## Layout        高密度注释地图:同模式文件合并成一条带计数(tests/ ← 31 *.test.ts)
## Docs          文档路由表:<何时读> -> <路径>(<回答什么问题>)
## Commands      精确命令:安装/构建/测试(全量+单跑)/lint/类型检查/生成/部署(标注先后)
## Architecture  核心模块、数据流、所有权边界、非显然的不变量
## Conventions   仓库特有规则与"禁止"项(原因不显然时才附一句)
## Pitfalls      反复出现的失败模式(或触发词索引,指向专门的 pitfalls 文档)
## Maintenance   未来 agent 如何原地更新、如何反向清理

骨架是地板不是天花板:仓库若有值得单独阅读时刻的知识(发布 playbook、被否决过的方案列表),可以加段。但"给会话偏好或一次性指令开段"被明确禁止。

反膨胀机制

这是本插件与"让模型随便写写"的关键差别,也是常驻维护段与命令提示词共用同一份规则字符串(DISTILL_RULE)的原因。规则形状是白名单兜底 + 排除项 + 开放式归因禁令 + 两条硬护栏,不是一张谁都能绕过去的固定清单:

  1. 只收这五类持久事实:精确命令、架构、关键不变量/阈值、反复踩的坑(写成"什么坏了 -> 为什么 -> 怎么修")、可复用的流程/QA/协作规则。写不出这五类之一的,本就不该进文件。
  2. 排除项靠白名单兜底:一次性任务指令、临时绕行、事故流水账、工作日志一律不收。真正封死"换马甲"的是第 1 条的 keep only——不在五类持久事实里的本就不该进文件,不必把排除项做成无穷清单。
  3. 归因标签全家桶封禁:(用户要求) / (user requested) / (用户决定) 只是三个最常见马甲,规则里明写 "or any equivalent label",并额外封死日期戳与用户原话引用。只封两个标签等于给模型留了换马甲的出口。规则本身写成紧凑祈使句即可。
  4. 无实证即丢弃:指不出具体文件、配置、命令或已观察到的故障来支撑一条结论,就整条删掉;同时禁止脑补技术理由——封死标签还不够,得给模型一个合法的放弃出口,否则它会为了保住一条偏好而现编因果。
  5. 外部红线例外:既有条目若涉及部署安全、外部接口兼容、线上环境边界,即使本地代码与单测无法佐证,也保留并向用户确认,绝不因"本地没验证到"就静默删除。把「对话偏好」和「生产不变量」精确切开,误删比留着几条垃圾危险得多。
  6. 近期记忆降级为候选池:会话记录和 git diff 只当作低信任候选——必须对着磁盘现状复核,剥掉任务细节,只放行跨任务的持久事实。上下文被压缩过也不会让幻觉得到官方认证。

第 1–5 条管入库标准,第 6 条管输入来源:来源可疑不等于内容错误,来源可信也不等于内容该进文件——两者是独立的闸门,都要过。

配套的两条写作纪律:一个事实只有一个家(详情写最具体的段,其它处只指路),段内按使用频率排序且保持稳定(让它是有序清单,不是堆积物)。

此外,这条规则字符串是每轮都要付费的:它被内联进常驻维护段,所以措辞本身也是成本。改它时先问"删掉这句,模型会不会写坏东西"——不会就删。

常驻维护段

除了一次性命令,插件还会往系统提示注入 agents-md-maintenance 段落(当前约 1.6k 字符,order: 650),让每个会话都带着维护意识跑:

  • 前置阀门:工作区没有 AGENTS.md 时不得新建(除非用户明确要求或跑 /init);
  • 默认动作是"不编辑":多数任务对 AGENTS.md 的改动数应为 0;
  • 只在任务收尾评估,且只在出现"可复用且经代码验证"的教训时才原地更新,并在回复里说明改了哪段;
  • 裁剪是条件动作,不是常驻命令:只有本次任务本就决定更新 AGENTS.md、或某条旧规则直接误导了当前任务 / 指向刚删改的文件时才顺带清理;平时不主动发起整份清理(那是 /init 的活)。顺手剥掉残留的归因标签、日期戳、原话尾巴(剥标签、留规则);
  • 文档路由:写进仓库的长期文档按 Layout 安放,给它自描述头部,并在收尾时补上 Docs 路由行(不在任务中途写,避免文档被改名/删除后留下死链)。

规则文字(DISTILL_RULE)由这段与 /init 提示词共用,因此它同时是每轮都在付的上下文成本——扩写它之前先确认新句子真的拦得住某类坏输出。

段落位置 order: 650 落在宿主 SECTION_ORDERS 的 TEAM_POLICY(600) 与 PTC_ONLY(800) 之间——在全部策略块之后、首个工具段之前,是"指导"而非最高优先级指令。

开发

pnpm install
bash scripts/build.sh     # 存在性检查 + 跑全部自测

完整验证链(改了 lib/index.js 就必须全跑):

node --check lib/index.js
node scripts/parse-options.test.mjs    # 选项解析严格性、否定句不误触发、空输入=默认档
node scripts/build-prompt.test.mjs     # 五模式提示词 + 分隔符逃逸防护 + 分支暂停理由
node scripts/apply-smoke.test.mjs      # 真依赖链:注册→投递→段落→enabled 门控→cwd 回退/取消
want-a-init/
├─ lib/index.js                  ← 全部运行时逻辑(唯一该手改的源码)
├─ lib/index.d.ts                ← 类型镜像,必须与 7 个导出保持一致
├─ scripts/                      ← build.sh + 3 个自测
├─ cordis.patch.yml              ← loader row(id: init-command)
└─ package.json / pnpm-lock.yaml ← lockfile 入库保可复现安装

lib/index.js 导出 7 个名字,lib/index.d.ts 必须逐一镜像:name · inject · Config · SOURCE_KIND · parseOptions · buildPrompt · apply。其中 parseOptions / buildPrompt 是公开的纯函数,可直接 import 做自定义流程或断言测试。

面向 agent 的仓库知识(命令、架构细节、坑位)在 AGENTS.md,改代码前先读它。

排错

| 症状 | 原因 | 处置 | |---|---|---| | /init 不出现在客户端 | 本地 link: 安装但没跑 pnpm install,解析不到 @deepseek-ai/dsh-llm | 仓库内 pnpm install 后重启 | | 命令在、但系统提示没有维护段 | config.enabled: false,或 bundle 未真正挂载 | 查 Config inspect 的 include:init-command | | 段落重复/行为像是旧版本 | profiles/web/cordis.patch.yml 里手写的 init-command 行遮蔽了 bundle | 删掉该行后重启 | | 改完代码没生效 | 宿主按进程缓存插件 | 重启 dsh web | | 新建文件报 EACCES ... link '*.tmp' | 宿主 fs-local 降级路径缺失(与本插件无关) | 跑 dsh-fix 后重启 |

非目标

  • 不写 CLAUDE.md,也不创建任何替代性指令文件;只维护 AGENTS.md。
  • 不替你决定仓库长什么样:没有可验证依据的段落就省略,宁可短。
  • 不动你的源码、配置和文档:/init 的写盘范围就是那一个文件。
  • 不做一次性报告的存档库:审计、周报、工作日志不属于 AGENTS.md。

License

MIT