Skip to main content
M

want-a-init

mexiaosqwq/want-a-init

Model-driven /init command: the agent analyzes the current repo and generates/updates a high-signal AGENTS.md, with a persistent system-prompt reminder to keep it maintained.

Install

dsh plugin --profile web add github:mexiaosqwq/want-a-init

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

Related plugins