dsh-config-manager: Instructions file for Codex

AGENTS.md

只放硬判据：证据与实测 → docs/lessons/<域>.md；机制细则 → DEVELOPERS.md；UI → DESIGN.md；对外契约 → docs/spec/。 加规则：先在 docs/lessons/<域>.md 写透证据，再回下面对应域补一行判据 + 指针，不另起小节。与代码冲突以代码为准，并当轮修本文件。 预算：≤28 KiB、单行 ≤400 B —— node scripts/check-agents-budget.mjs。

Rules

通用（任何改动）

• 验证顺序：npm run typecheck → npm test →（动 client/样式）npm run build →（大改）npm run smoke；TEMP/TMP 只给 build/install（→ .tmp/buildtmp，prepare 也算），npm test 用系统 TEMP（判据 → docs/lessons/git-and-release.md）；无 lint/format，typecheck 兜底。
• 版本号按 SemVer 判定：修复 = PATCH、兼容新增 = MINOR、破公开契约 = MAJOR；0.1.z 只放修复，功能进 MINOR；判据与历史保留 → docs/maintenance/versioning.md。
• 版本四处同步：package.json.version ≡ src/index.ts 的 PLUGIN_VERSION ≡ package-lock.json 根 version 与 packages[""].version ≡ docs/spec/compat-matrix.md 顶部版本声明行；tests/packaging-contract.test.ts 的 V-1 钉前三处，声明行由 scripts/check-doc-versions.mjs 钉住（npm version 不会改 PLUGIN_VERSION）。
• 发版：打 tag v* push 后全自动（阶段表 → DEVELOPERS.md）；前置 = 发布前检查清单（docs/maintenance/versioning.md §10）+ CHANGELOG.md 顶部亮点段；发布成功后按 .dsh/issue-ledger.md 的 awaiting-release 行回版本号并标 fixed。
• 用户可见的功能/行为/修复同轮进 CHANGELOG.md 的 ## [Unreleased]（落位见 skill changelog-writing）。
• git：工作副本 origin 每次跟随 repoUrl（含 --push，不一致即 set-url）；同一工作副本操作一律经 GitTransport.withWorkdir()；拉取只许 fetch + merge --ff-only，禁 git pull（坏 FETCH_HEAD ⇒ SAFE MODE）。
• 删源文件前先 git status --porcelain <路径>：见 ?? 必须停下；禁 git checkout -- <文件> 回滚，撤销改动用针对性 edit 反向。
• 只读端点必须有界：取值体碰不可控依赖（credentials 服务、子进程、工作副本自检、外部 HTTP）一律 withTimeout + 明确错误码；客户端首屏不得让单一慢请求垄断骨架。
• 只读端点别在 GET 里 spawn 外部进程：同一事实被反复索取（首页/切页/轮询）改「按需 detail + 短 TTL 缓存」，缓存 key 含 repoUrl，写路径经 withWorkdir 失效。
• 锁等待也是不可控依赖：只读自检自带 1.5 s 短上限，超时变成「冲突/可重试」错误码；锁回收先判 holder 进程存活，判不了才退回 mtime；等待上限要覆盖进程内链上排队。
• EOL 由根 .gitattributes 钉死，源码字面量守卫必须在读取入口折 LF；pnpm 11 minimumReleaseAge 会让 @latest 装旧版 —— 用精确版本或设 0。
• import 一律带 .ts；import type 强制（verbatimModuleSyntax）；类型合并用 declare module + import type{}。
• 依赖：运行时只有 js-yaml（peer 是 DSH 官方包）；不加 UI/CSS/图标/动画/工具库，也不引入已准入库的同类替代品；新增后同步 package.json + package-lock.json（两处 + 根对象）。
• 复用优先：新建 Component/Hook/Utility/Style/Type/API 前 ①Reuse ②Extend ③Refactor ④Create；查库序 src/client/common/* → src/ui/* → src/core/* → src/utils/* → src/security/* → DESIGN.md。
• 根目录只放对外文档（README*/CHANGELOG/SECURITY/LICENSE）与协作规范，其余进 docs/。