@weotro/dx 0.2.2 → 0.3.2

package/skills/dx-adopt/references/dx-0.3-contract.md

@@ -0,0 +1,99 @@
+# DX 0.3.0 应用契约
+
+本文随 0.3.0 的 npm 包和 dx-adopt 技能独立分发。实际接入按[0.3.0 向导](switch-to-0.3.md)执行，排查应用适配问题时参考[经验与回归检查](adoption-regressions.md)。
+
+## 入口与语法
+
+工程发现标记为最近的 `dx/scripts` 目录，其父级 dx 的父目录是工程根，也是应用进程 cwd。最近工程损坏或缺少入口时失败，不回退外层工程。七个标准入口全部必选，每个是无扩展名、可读可执行的文件；名称匹配 `[a-z][a-z0-9-]*`，shebang 指定绝对解释器路径，首行不超过 255 字节（不含换行）。辅助模块放在公开入口目录外。
+
+| 入口 | 必填位置参数 | 必需聚合 |
+| --- | --- | --- |
+| setup | 无，额外位置参数报错 | 整个工程 |
+| start | `<目标>` | stack，不接受 all |
+| build / lint / deploy | `<目标>` | all，不接受 stack |
+| test | `<unit\|e2e> <目标>` | 两种类型各自 all，不接受 stack |
+| db | `<migrate\|seed\|reset\|status> <目标>` | 无，禁止 all/stack |
+
+缺少或多出位置参数、未知类型/动作/目标明确报错。目标由应用声明，all/stack 的成员、顺序与失败行为由应用实现，dx 不自动编排。扩展命令可自由定义位置参数，但遵守公共选项规则；独立集成测试及额外数据库动作使用明确命名的扩展。check/initial 为保留名称，不得提供同名应用脚本。
+
+首个 `--` 前只接受规定的位置参数、五种环境标志和 -h/--help；未知选项报错，工具专属参数放在 `--` 后。dx 删除自身消费的环境标志，保留类型、动作、目标、首个 `--` 和之后每项原始参数，包括空字符串及空格，不重新拼接 shell 命令。
+
+```text
+dx build admin --prod -- --mode fast
+应用 argv: ["admin", "--", "--mode", "fast"]
+dx test unit all -- --watch
+应用 argv: ["unit", "all", "--", "--watch"]
+```
+
+标准命令 -h/--help 由 dx 显示统一语法，允许缺少位置参数；不运行应用、环境加载或 setup。应用/工具帮助通过合法调用后的 `-- --help` 请求。扩展帮助交给应用执行，仍先检查契约并加载环境，不能视为无副作用。
+
+## 契约声明
+
+工程根 `dx/contract.json` 必须为 JSON 对象，只包含 `schemaVersion` 和 `commands`。版本必须为数字 1；commands 必须恰好包含七个标准命令，扩展不用声明。各层只允许示例所示字段：setup 为状态对象；其他命令通过 targets、types 或 actions 定位完整调用组合。
+
+以下示例表示一个有真实单测、其余能力确实不适用的库项目。只有确认项目现状符合时才采用对应 mock；有实际服务或构建任务时改为 implemented 并实现它们。
+
+```json
+{
+  "schemaVersion": 1,
+  "commands": {
+    "setup": { "status": "implemented" },
+    "start": { "targets": { "stack": { "status": "mock", "reason": "库项目没有常驻服务" } } },
+    "build": { "targets": { "all": { "status": "mock", "reason": "直接发布源码，无构建步骤" } } },
+    "lint": { "targets": { "all": { "status": "implemented" } } },
+    "deploy": { "targets": { "all": { "status": "mock", "reason": "库项目没有部署服务" } } },
+    "test": {
+      "types": {
+        "unit": { "targets": { "all": { "status": "implemented" } } },
+        "e2e": { "targets": { "all": { "status": "mock", "reason": "库项目没有端到端应用流程" } } }
+      }
+    },
+    "db": {
+      "actions": {
+        "migrate": { "targets": { "main": { "status": "mock", "reason": "项目不使用数据库" } } },
+        "seed": { "targets": { "main": { "status": "mock", "reason": "项目不使用数据库" } } },
+        "reset": { "targets": { "main": { "status": "mock", "reason": "项目不使用数据库" } } },
+        "status": { "targets": { "main": { "status": "mock", "reason": "项目不使用数据库" } } }
+      }
+    }
+  }
+}
+```
+
+每个状态对象只有 status 和可选 reason；status 为 implemented 或 mock，mock 必须附非空字符串原因。所有 unit 目标必须 implemented。start stack、build/lint/deploy all、unit/e2e all 必须显式声明；db 四个动作各至少一个目标，可分别使用 main。添加目标时在对应 targets 中声明状态；不允许通过任意新字段添加环境策略、工具命令或编排。
+
+mock 由应用脚本实际执行，输出包含命令名称和不适用原因的日志，返回 0 表示跳过。声明 mock 不会让 dx 自动跳过脚本。需要但尚未完成的能力不能声称不适用；缺少单测不能靠 mock 履约。
+
+## 静态检查与行为证据
+
+`dx check` 聚合入口与声明的静态错误，成功返回 0，失败返回 1；不加载环境、不复制文件、不调用业务脚本。全量检查包括全部公开扩展入口，不只检查即将调用的脚本。检查名称、文件、权限、shebang、保留名称、必需声明、组合、状态与 mock 原因。
+
+真实应用调用（含扩展帮助）须通过全量检查，再在环境加载、setup 复制与应用执行前通过本次参数、目标和环境校验。顶层及标准命令帮助、版本和 initial 不因应用契约缺失或损坏被拦截。新接入先补齐入口及声明，再 check 和 setup；没有兼容模式或绕过开关。
+
+静态合规不证明业务真实实现。dx 不扫描 echo/exit 等文本猜测实现，也不为 check 试运行脚本。dx-adopt 分别取得真实 unit 等功能证据、mock 日志与退出码证据，明确未验证项；implemented 声明本身不是验收结果。
+
+## 环境
+
+命令是环境选择唯一来源，APP_ENV/NODE_ENV 仅传递结果。test unit 固定 test，test e2e 固定 e2e，首个 `--` 前禁止任何环境标志，包括冗余 --test/--e2e。其他应用命令含扩展默认 development，可传 --dev/--staging/--prod/--test/--e2e 中一个；不同或重复标志都报错。首个 `--` 后的标志不参与解析。
+
+| 命令选择 / APP_ENV | NODE_ENV | 环境文件后缀 |
+| --- | --- | --- |
+| development | development | development |
+| staging | production | staging |
+| production | production | production |
+| test | test | test |
+| e2e | test | e2e |
+
+例如 `APP_ENV=production dx build all` 仍为 development；生产构建配置使用 `dx build all --prod`。环境标志只选择当前机器的配置，不改变执行机器，也不自动部署；start 保持本机启动，资源实际位置由配置地址决定。
+
+从工程根按低到高加载：继承普通环境变量 < `.env.<环境>` < `.env.<环境>.local`。APP_ENV/NODE_ENV 在变量展开前由命令确定，不被继承值或文件改变。仅合并子进程环境，不修改 dx 自身 process.env。dotenv 解析引号、注释及多行值，dotenv-expand 展开同层已定义变量、前层与继承变量。文件缺失跳过，读取失败停止；通用 .env/.env.local、应用子目录和旧 env-layers.json 不自动加载。CI 普通同名变量也可能被文件覆盖。
+
+应用直接消费注入结果，不重复解析 dx 环境标志或根据 NODE_ENV 重新选择环境层。额外工具 dotenv 加载、构建优化模式及必要值校验属于应用，验收其真实效果。
+
+## setup、进程与分发
+
+setup 顺序为：全量契约及本次输入检查 → 基础 worktree 复制 → 环境加载 → 应用 setup。linked worktree 从主 Git 工作目录复制所有以 .local 结尾的普通文件（含隐藏及被忽略的文件），按相对路径写入当前 Git worktree 根，保留权限，跳过已有文件/目录/链接。跳过源符号链接、Git 元数据及嵌套 worktree，目标父路径必须为实际目录；复制失败停止应用，已复制文件保留。主工作目录、非 Git 工程、没有主 checkout 的 bare 仓库 worktree 跳过复制。Git 需安装。复制 .env.local 不代表加载它，独立 clone 不共享秘密。其他命令不触发 setup。
+
+dx 继承标准流、保持交互终端、返回应用退出状态并转发 SIGINT/SIGTERM；应用幂等清理自己的后代，dx 不监督后台服务。单进程 Shell 包装可用 exec。工具选择、安装、编排、数据库确认和部署恢复均由应用负责。
+
+运行要求 Node.js >=20.11.0，macOS/Linux；全局 dx 可在应用依赖尚未安装时调用 setup，本地依赖需要独立引导。initial 无需应用工程，不运行 setup；使用包内 skills 更新 ~/.agents/skills 的托管技能、建立 ~/.claude/skills 链接并清理托管旧副本及历史删除技能，其他技能保留。技能外部工具另行安装认证。验证分发使用隔离 home，记录实际包版本与引用完整性。

package/skills/dx-adopt/references/switch-to-0.3.md

@@ -0,0 +1,61 @@
+# DX 0.3.0 接入与切换向导
+
+本向导及[完整契约](dx-0.3-contract.md)、[经验与回归检查](adoption-regressions.md)一起分发。直接完成 0.3.0 的应用入口和调用方式，不需要访问 dx 源码或经过中间版本。
+
+## 1. 安装并取得说明
+
+沿用应用的全局或项目依赖安装方式。已发布的全局版本可通过以下命令安装并同步资料：
+
+```sh
+npm install -g @weotro/dx@0.3.0
+dx --version
+dx initial
+```
+
+项目依赖由原包管理器安装 `@weotro/dx@0.3.0`，使用该依赖的 CLI 执行同样的版本核验与 initial。待发布验证使用实际提供的 0.3.0 `.tgz`；安装源、开发调用及 CI 应一致。
+
+同步后的阅读入口为 `~/.agents/skills/dx-adopt/SKILL.md`，本目录 references 中包含全部规则和经验。包内另有 README.md、example/README.md 和可运行 example；全局包位于 `npm root -g` 输出下的 `@weotro/dx`，本地包位于项目 `node_modules/@weotro/dx`。这些是安装包路径，无需源码仓库。
+
+完成条件：确认实际 CLI 为 0.3.0，并能在已安装技能目录读取本向导及两个配套参考。
+
+## 2. 将实际功能接到标准入口
+
+盘点当前 package scripts、工具任务、CI、容器及部署调用，建立“功能 → 调用方 → 新入口/目标 → 验证结果”的对应关系。保留真实实现、工具链及确认条件。
+
+在工程根建立七个带有效 shebang、可读可执行的 `dx/scripts/` 入口，以及 `dx/contract.json`。按[契约 JSON 示例](dx-0.3-contract.md#契约声明)声明 `schemaVersion: 1`、目标及每个调用组合的能力状态；辅助实现放在公开入口目录外。
+
+- setup 无位置参数；start/build/lint/deploy 各接一个目标。
+- test 接 unit/e2e 类型与目标；db 接 migrate/seed/reset/status 动作与单目标。
+- start 显式声明 stack；build/lint/deploy 和两种测试各显式声明 all；db 各动作至少一个目标。
+- 每个 unit 目标必须真实实现；确实不适用的其他能力可声明 mock，附原因，由应用输出命令和原因并返回 0。需要但未完成的功能如实保留为未完成项。
+
+完成条件：七个入口、声明与实际功能对应完整，`dx check` 返回 0。静态合规不代表真实功能已验证。
+
+## 3. 一次切换所有调用方
+
+根据实际职责填写目标，不盲目用 all 替代单目标。统一调用形式例如：
+
+```sh
+dx setup
+dx start stack
+dx build all --prod
+dx lint all -- --fix
+dx test unit all
+dx test e2e all
+dx db migrate main --e2e
+dx deploy all --staging
+```
+
+工具专属参数放在首个 `--` 后，由应用按参数数组转交。test 命令固定选择 test/e2e，不接受额外环境标志；其他应用命令默认 dev，最多接受一个环境标志。应用读取 dx 注入的 APP_ENV/NODE_ENV，命令是环境选择来源。
+
+同步 package scripts、CI、容器、部署平台、Playwright webServer、测试内启动命令和开发/agent 指令。E2E 内启动非测试命令也要显式选择环境，如 `dx start stack --e2e`；仅设置父进程 APP_ENV 不会选中 E2E 配置。
+
+完成条件：所有活动调用方使用相同的 0.3.0 来源及语法，搜索替换前的路径和命令后没有遗漏消费者；确认无人使用的包装和配置才清理。
+
+## 4. 用实际行为验收
+
+先 `dx check`，再按需执行 setup 和真实 unit、lint、构建与其他相关功能。标准帮助不会执行业务；扩展帮助和 `-- --help` 仍是应用调用。数据库与部署按项目既有授权使用隔离资源验证。
+
+按[经验与回归检查](adoption-regressions.md)选择涉及的分支，核对实际环境层、最终工具 argv、构建产物、worktree 配置和进程回收。mock 逐项验证日志及退出码。项目本地接入说明链接到已安装的 dx-adopt 资料，写清目标和环境用法。
+
+完成条件：分别记录静态合规、真实通过、mock 跳过和未验证项；implemented 声明与脚本返回 0 均不能替代真实运行证据。

package/skills/git-release/SKILL.md

@@ -11,7 +11,7 @@ description: 仅在显式调用 git-release 时使用：准备或执行版本发
 只读检索、本地草稿、可回滚编辑和常规测试可自主推断并继续；从相关文件和直接依赖开始，仅在证据不足或影响跨模块时扩大范围，复用仍有效的验证。
 仅在不可逆或难以回滚的修改缺少具体授权时，先完成预览、草稿与验证，再说明对象和影响并等待确认；会话中已有授权继续有效。缺少事实时先查证、标注假设并推进独立工作，确实无法确定操作目标时才询问。对外发送消息须有明确授权。
 
-用户显式调用本技能执行发布，即明确授权在本次目标仓库创建并推送目标版本的 tag，以及创建并发布对应的 GitHub Release。完成准备和验证后连续执行至发布结果核验，无需再次询问是否推送 tag 或创建 Release。用户明确限定为仅准备、草稿、审计或修改技能时，按该范围执行；本授权不包含覆盖冲突 tag、删除既有 Release 或额外的生产操作。
+用户显式调用本技能执行发布，即明确授权在本次目标仓库创建并推送目标版本的 tag、创建并发布对应的 GitHub Release，以及创建该版本的远程 GitHub 回访审计 Issue。完成准备和验证后连续执行至 Release 与回访 Issue 均读回核验，无需再次询问是否推送 tag、创建 Release 或回访 Issue。用户明确限定为仅准备、草稿、审计、修改技能或不创建 Issue 时，按该范围执行；本授权不包含覆盖冲突 tag、删除既有 Release 或额外的生产操作。
 
 ## 发布准备
 
@@ -45,8 +45,8 @@ gh release create v<VERSION> --title "v<VERSION>" --notes-file <notes-path>
 
 准备审计草稿时按需读取 [发布后回访契约](references/post-release-follow-up.md)。以本次变更映射受影响对象、预期行为、通过标准和脱敏证据；不是部署操作手册。
 
-默认本技能只编写回访审计 Issue，不执行生产验证；用户另有只读取证任务时按该任务范围继续。发布成功不代表部署完成，依赖部署后事实的审计项保持未勾选。
+默认本技能创建远程回访审计 Issue，不执行生产验证；用户另有只读取证任务时按该任务范围继续。发布成功不代表部署完成，依赖部署后事实的审计项保持未勾选。
 
-任务包含创建回访 Issue 时，发布成功后创建并读回，确认实质变更均有对应审计项或不适用说明。创建失败时保留草稿与已发布状态，修复可恢复错误，仅补做未完成的 Issue 操作。
+发布成功后，在同一目标仓库查找该版本已有的回访 Issue（含已关闭项），以版本、Release URL 和目标提交确认对应关系；存在则复用并读回，否则直接创建并读回，确认实质变更均有对应审计项或不适用说明。创建失败或结果不明时先查询远端状态，修复可恢复错误，仅补做未完成的 Issue 操作，避免重复创建。确实无法完成时保留草稿并报告具体阻碍，明确标记回访 Issue 未完成。
 
-最终报告版本、目标提交、Release URL、验证结果和回访 Issue（或本地草稿）链接；区分发布成功、部署状态未知与未完成项。
+完整发布的完成条件包含远程回访 Issue 已创建或复用并读回核验；本地草稿仅是准备或失败恢复材料。最终报告版本、目标提交、Release URL、验证结果和远程回访 Issue URL；区分发布成功、部署状态未知与未完成项。仅准备或草稿任务按用户范围报告本地产物。

package/skills/git-release/references/post-release-follow-up.md

@@ -75,12 +75,12 @@ GitHub Release、tag、CI 或部署工作流成功都不能证明生产已完成
 
 ## 完成边界
 
-完整发布并创建回访 Issue 的完成条件如下；用户仅要求本地草稿时，以草稿覆盖范围和质量为准：
+完整发布的完成条件如下；回访 Issue 按入口技能默认创建到目标 GitHub 仓库。用户明确限制任务范围时按该范围执行，仅要求本地草稿时以草稿覆盖范围和质量为准：
 
 - Release 已读回确认；
 - 本次发布的每项实质变更已映射到审计项或不适用说明；
 - 每个审计项都有审计对象、通过标准、证据要求和时机；
-- Issue 已创建并读回，且没有占位符；
+- 远程 Issue 已创建或复用并读回，且没有占位符；
 - 所有依赖部署后事实的审计项均未勾选；
 - Issue 没有声称已经完成部署或生产验证，也没有写成部署操作步骤。
 

package/skills/project-agent-standards/SKILL.md

@@ -7,11 +7,13 @@ description: 审核并补齐项目面向 agent 的 GitHub 模板、开发评审
 
 对用户指定仓库执行审核并补齐缺项；未指定时使用当前仓库。只读审核请求只报告差异。默认执行本地可回退的模板和文档修改，不包含提交、推送、发布 Issue / PR、安装工具或改造构建系统。现有全局技能保持不变。
 
+以下所有规范、模板和入口均先检查是否已有等效内容，再依据源码、配置、测试和已有决策核对其正确性及项目适用性。已存在、正确且符合项目状况的内容保持原样，不为统一措辞、路径或套用骨架而修改。只有确认缺失、错误、过时或不符合项目状况时才做最小必要修改；依据不足时保留原文并报告待确认事项。
+
 ## 1. 建立项目依据
 
 检查工作区状态，读取目标及祖先的 `AGENTS.md`。按需检查已有规范、贡献指南、GitHub 模板、技术栈清单、任务配置和 CI。优先搜索标题与职责，不能仅凭文件名判定规范缺失。
 
-记录以下六项的现状、路径和缺口：Issue / PR 模板、agent 引用、开发评审规范、DX / Nx 工作流、回访规则、AGENTS.md 渐进披露结构。检查根及模块 agent 入口的内容分工、读取条件和引用链；祖先指令用于确定约束，不修改目标仓库之外的文件。区分已配置的命令、实际运行结果与未来建议；不读取或输出秘密值。
+记录以下七项的现状、路径和缺口：Issue / PR 模板、agent 引用、开发评审规范、DX / Nx 工作流、回访规则、AGENTS.md 渐进披露结构、根 AGENTS.md 的开工前三问。检查根及模块 agent 入口的内容分工、读取条件和引用链；祖先指令用于确定约束，不修改目标仓库之外的文件。区分已配置的命令、实际运行结果与未来建议；不读取或输出秘密值。
 
 完成条件：每项均有存在证据或明确的缺失结论，能够识别目标模块与实际工具链。
 
@@ -24,11 +26,11 @@ description: 审核并补齐项目面向 agent 的 GitHub 模板、开发评审
 | [Issue 模板](assets/github/ISSUE_TEMPLATE/issue.md) | `.github/ISSUE_TEMPLATE/issue.md` |
 | [PR 模板](assets/github/pull_request_template.md) | `.github/pull_request_template.md` |
 
-目标缺失时创建目录并直接复制。目标已有等效内容时保留；空文件或缺少模板必需结构时，以资源覆盖该目标文件。覆盖前保留目标的未提交或未跟踪原文到仓库外的临时备份，并记录路径；已提交的原文可通过 Git 恢复。用户明确要求统一为附带模板时直接覆盖。
+确认没有可复用的等效模板时，创建目录并按项目状况适配资源。目标已有正确且适用的等效内容时保留；空文件可使用资源填充，缺少项目所需结构时只补齐缺项。覆盖前保留目标的未提交或未跟踪原文到仓库外的临时备份，并记录路径；已提交的原文可通过 Git 恢复。用户明确要求统一为附带模板时直接覆盖。
 
 检查根目录、`docs/` 与 `.github/` 是否有竞争的默认 PR 模板；将仍适用的独有约束合入标准模板，再清理被取代的默认副本并更新引用。保留用途不同的 Issue Forms、多模板及配置，不因其存在就删除。已有标准文件中的项目专属验收要求同样需要保留。
 
-完成条件：两个标准位置均有可用模板，默认 PR 模板选择无冲突，独有约束和用户原文可追踪。
+完成条件：Issue / PR 均有可用模板，已有正确且适用的路径保留，默认 PR 模板选择无冲突，独有约束和用户原文可追踪。
 
 ## 3. 补齐面向 agent 的参考文档
 
@@ -52,6 +54,14 @@ DX 文档必须检查实际 DX 配置、Nx 目标与 CLI 能力。已接入则
 
 ## 4. 检查并改造 AGENTS.md 的渐进披露结构
 
+检查根 `AGENTS.md`（沿用仓库已有的文件名大小写）是否包含以下开工前三问。已有完整等效约束且正确、符合项目状况时保持原样；部分缺失时只补缺项，整段缺失时在根入口的工作原则或全局约束处加入以下内容，沿用项目语言。此约束属于全局必需规则，保留在根入口正文中：
+
+> Ask yourself before starting:
+>
+> 1. "Is this a real problem?" - Reject over-engineering.
+> 2. "Is there a simpler way?" - Always seek the simplest solution (KISS).
+> 3. "Will it break anything?" - Backward compatibility is an iron law.
+
 渐进披露按任务需要加载说明：根入口保留项目识别、全局必需约束与条件明确的文档入口；模块入口保留该目录适用的规则；详细流程、命令说明、模板字段和专题规范放在被引用文档中。判断依据是内容职责与加载方式，不以行数或是否已有链接判定。只有简短必需规则的入口无需为了拆分而创建文件。
 
 存在下列情况时，在本次整备中直接改造：入口堆放仅特定任务需要的详细流程；所有专题文档被要求无条件全文加载；只有链接而没有读取条件；相同规范在多个入口重复维护。只读审核请求则报告问题和迁移建议。
@@ -77,6 +87,6 @@ DX 文档必须检查实际 DX 配置、Nx 目标与 CLI 能力。已接入则
 
 ## 5. 验证与交付
 
-检查差异、Markdown 链接、模板 frontmatter、占位符和竞争模板。逐项复核第 1 步的六项清单与所有新引用，确认再执行一次不会增加文件或重复条目。对照迁移记录检查规则完整性，并分别用代码修改、Issue / PR 编写和回访任务走查入口，确认能够找到对应规范，且不会要求加载无关专题。
+检查差异、Markdown 链接、模板 frontmatter、占位符和竞争模板。逐项复核第 1 步的七项清单与所有新引用，确认根入口的开工前三问完整，已有正确且适用的内容未被改写，每处修改均有具体缺口或纠错依据，再执行一次不会增加文件或重复条目。对照迁移记录检查规则完整性，并分别用代码修改、Issue / PR 编写和回访任务走查入口，确认能够找到对应规范，且不会要求加载无关专题。
 
 纯文档修改按项目规则做差异与格式验证；验证命令存在可以检查配置或安全的帮助输出，不为文档审核运行发布、迁移或全仓测试。报告每项的保留 / 新建 / 更新状态、文件链接、实际验证和未确认事项，以及渐进披露检查结论与章节迁移去向；未接入 DX / Nx 要明确说明。不要将文档中列出的命令写成已经执行通过。

package/skills/dx-adopt/references/dx-0.2-contract.md

@@ -1,95 +0,0 @@
-# DX 0.2.1 能力与调用契约
-
-本文随技能发布，供应用接入时独立使用。实际安装包不同于 0.2.1 时核对行为，不将此表外推为其他版本的保证。
-
-## 能力分界
-
-| dx 提供 | 应用提供 |
-| --- | --- |
-| 最近工程发现、脚本检查、进程调用、退出状态 | 构建、测试、数据库和部署的具体实现 |
-| dotenv 两层加载、dotenv-expand 变量展开、环境选择 | 必需变量与占位符校验、额外服务配置 |
-| setup 前的 worktree 本地文件准备 | 安装依赖、生成文件、准备服务 |
-| initial 的包内技能分发 | 目标项目的代码与脚本；initial 不执行接入迁移 |
-| 帮助与版本查询 | 应用子命令帮助、目标选择、编排和恢复 |
-
-不内置 Nx、Prisma、PM2、Vercel、SDK 构建、制品部署、回滚、端口清理、自动重试或环境策略配置。这些工具可以继续在应用中使用。
-
-## 安装与技能
-
-- 包名 `@weotro/dx`，Node.js 至少 20.11.0；支持 macOS/Linux，不支持 Windows。setup 的 Git 定位需要已安装 Git。
-- 全局安装可独立于应用 node_modules 工作；本地依赖需先有安装它的引导途径。运行时依赖由 dx 包自己携带，应用不必为了 dx 的环境注入安装 dotenv CLI。
-- `dx initial` 使用安装包中的 skills/，覆盖更新 `~/.agents/skills` 的托管技能，为 `~/.claude/skills` 建立链接，并按原规则清理托管旧副本和历史已删除技能。其他技能保留。
-- initial 无需应用工程，不加载项目环境，不运行 setup；setup 也不会自动执行 initial。新技能随包安装后，通过 initial 同步；仅把 dx 版本写入 package.json 不等于技能已更新。
-
-## 脚本路由
-
-```text
-项目根/
-  dx/scripts/setup
-  dx/scripts/start
-  dx/scripts/build
-  dx/scripts/test
-  dx/scripts/db
-  dx/scripts/deploy
-```
-
-按需提供入口，不要求六个全部存在。自定义名称匹配 `[a-z][a-z0-9-]*`；initial 为保留命令。每个入口为可读、可执行、无扩展名的文件，shebang 解释器使用绝对路径，首行最多 255 字节，不含换行。
-
-从调用目录向上找到最近的 `dx/scripts`，对应项目根作为应用脚本 cwd。最近标记损坏、不可读或缺少所请求入口时直接失败；不会执行外层同名命令。未发现内层标记才继续向上查找。
-
-`dx build admin --prod` 只运行 `dx/scripts/build`，脚本仍收到 `admin`、`--prod`。没有自动的二级命令查找、app 目录推断、默认 all 或构建编排。`start stack` 与 `start admin` 也调用同一个 start 文件，由应用选择服务。
-
-无参数和顶层 `--help` 显示帮助，`--version` 无需工程。`dx initial --help` 是内置帮助；其他命令后的 `--help` 交给应用，不由 dx 截获。
-
-## 环境
-
-**环境名称选择配置，执行位置是运行 dx 的当前机器。** 例如在开发电脑执行 `dx start admin --prod`，dx 读取该电脑项目根的 `.env.production`，再加载 `.env.production.local` 覆盖，设置 APP_ENV / NODE_ENV 为 production，并在该电脑调用 `dx/scripts/start` 启动 admin。它不表示到生产服务器运行，也不触发远程连接、发布或部署；`--staging` 等标志同理。在服务器执行时，当前机器就是那台服务器。
-
-应用 start 保持本机启动语义；需要远程部署时，由应用 deploy 等明确入口实现。进程访问哪些数据库或 API 取决于配置中的地址：本机运行仍可能连接远端资源，运行位置与资源位置应分别说明。
-
-从找到的项目根加载，优先级由低到高：
-
-```text
-继承环境变量 < .env.<environment> < .env.<environment>.local
-```
-
-这意味着 CI 注入的普通变量也可能被文件中的同名值覆盖。公开文件只放适合入库的默认值或明确占位符，真实值放入忽略的 local 文件或按项目方式注入；项目脚本自己校验必要值。
-
-环境选择按下列顺序：
-
-1. 命令后、第一个 `--` 前的环境标志；优先级依次为 `--prod`、`--staging`、`--dev`、`--test`、`--e2e`。建议调用方只使用一个。
-2. 调用者 APP_ENV，其次 NODE_ENV；都没有时为 development。选择名称转小写，dev/local 映射为 development；不支持的名称报错。
-
-| 选定环境 / APP_ENV | 注入的 NODE_ENV | 两层文件 |
-| --- | --- | --- |
-| development | development | .env.development、.env.development.local |
-| staging | production | .env.staging、.env.staging.local |
-| production | production | .env.production、.env.production.local |
-| test | test | .env.test、.env.test.local |
-| e2e | test | .env.e2e、.env.e2e.local |
-
-APP_ENV 和 NODE_ENV 在展开变量前确定，不允许文件重新设置。不从环境文件中读取 APP_ENV 来决定加载哪套文件。命令名本身不会改环境：未指定环境的 `dx test` 或 `dx build` 不会自动选择 test 或 production。
-
-文件缺失跳过，读取失败则停止；只修改传给应用的子进程环境。dotenv 负责引号、注释和多行值，dotenv-expand 按其语法展开同层已定义变量、前层和调用者变量。迁移旧手写解析或 shell source 时，应使用非敏感样例复核 `$`、引号、转义及依赖顺序，不能当作 shell 脚本执行。
-
-不加载通用 `.env` / `.env.local`、应用子目录文件或 `dx/config/env-layers.json`。`DX_CONFIG_DIR` 和顶层 `--config-dir` 不再选择工程或配置。选择环境的标志保留在 argv；`--` 后的标志只属于应用参数。
-
-## setup 的公共步骤
-
-必须先有合法 `dx/scripts/setup`。入口检查通过后，顺序为复制 → 环境加载 → 应用脚本。
-
-- 当前是 linked worktree 时，从 Git 登记的主工作目录递归复制所有以 `.local` 结尾的普通文件，含隐藏与被 Git 忽略的文件，按相对路径写入当前 Git worktree 根并保留文件权限。
-- 跳过已经存在的文件、目录和链接；不覆盖、不更新已有副本，不会在每次 start/build 时同步。
-- 跳过源符号链接、`.git` 元数据和嵌套 worktree；目标父路径必须是实际目录。失败停止应用 setup；已成功复制的文件保留，修复后可再次执行。
-- 主工作目录（含从其子目录调用）、非 Git 工程、bare 仓库下没有主 checkout 的 worktree 不复制。Git 不可用会报错。
-- 项目根若是 Git 根的子目录，复制目标仍是 Git worktree 根，环境加载位置仍是项目根。
-
-复制 `.env.local` 不代表会加载它；加载始终只认选定环境的两层文件。新 clone 不共享另一个 clone 的本地文件，也不会自动向远端下载凭据。
-
-## 进程与操作责任
-
-argv 逐项传递，空字符串、引号、空格、`--` 保留；dx 不拼接 shell 字符串。stdin/stdout/stderr 直接继承，应用退出码保留。
-
-脚本保持前台终端；dx 转发 SIGINT/SIGTERM，并保留应用最终信号或退出码。终端 Ctrl-C 可能与转发同时到达，应用应幂等清理自己启动的进程。dx 不监督任意后代或后台服务。
-
-单进程 Shell 包装优先使用 `exec`。多服务启动、端口冲突、工具版本、秘密校验、数据库确认和部署恢复均由应用完成；没有通用 `--yes`、`--dry-run` 或自动修复能力。

package/skills/dx-adopt/references/migrate-0.1.md

@@ -1,50 +0,0 @@
-# 从 0.1.x 迁移
-
-仅用于已有旧版调用的项目。0.2.0 起采用硬切换，接入使用 >=0.2.0 的实际已核验版本：旧命令表和内部 runner 不再执行，迁移的目标是把项目实际需要的行为放入应用脚本，而非重建旧 dx。
-
-## 先盘点，再替换
-
-检查项目真实使用的 `dx/config/commands.json`、环境层/策略配置、包脚本、CI、容器入口、Nx 等工具目标和项目已有实现。只记录环境文件路径与变量名，避免将秘密值复制进报告。旧版本实现只有在行为无法由项目源码解释时才按实际版本查证。
-
-建立一张迁移表，每项包含：旧入口与调用者、实际执行内容、环境、顺序/并发关系、安全条件、新入口/实现文件、验证方式与结果。不能仅把旧命令名改成新命令名；同一个 `dx build admin` 在新版本下也需要实际的 build 文件。
-
-## 旧能力的去向
-
-| 旧依赖或配置 | 新脚本入口应做什么 |
-| --- | --- |
-| commands.json 的 command、嵌套子命令和环境分支 | 对应顶层 dx/scripts 文件，内部自行解析目标与子命令，根据 APP_ENV 调用真实实现 |
-| concurrent、commands 引用、all/development 聚合 | 在项目脚本中明确任务成员、顺序/并发、失败传播与退出收尾 |
-| internal: pm2-stack、backend-artifact-deploy 等 | 直接使用项目工具完成原先需要的流程；不能保留 internal 字段期待 dx 执行 |
-| app、目标别名、自动推断目录、requiresPath/fileCommand | 在项目脚本验证目标和路径并按 argv 调用；旧占位符替换不再发生 |
-| env-layers.json、自定义环境路径、{app} 层 | 迁到标准两层，或由应用明确加载额外文件；通用 .env 和 .env.local 不参与 dx 加载 |
-| env-policy、requiredVars、占位符检查、dangerous/确认 | 由项目入口执行必要检查与确认；包括 allowRoot/allowSubdirGlobs 等布局规则，详见适配回归检查 |
-| ports、自动终止服务、重试、Prisma 自动生成 | 将必要准备放入 setup 或具体应用流程；启动失败不再由 dx 自动修复 |
-| Next/Nx 构建识别、强制 NODE_ENV、轮询变量 | 核对项目工具要求，在项目实现中显式设置；不要假定 dx 仍设置 NX_DAEMON 等变量 |
-| SDK 构建、制品上传、Vercel、回滚、版本注入 | 项目维护自己的构建/发布脚本和故障处理；dx 不再提供这些实现 |
-| dx-with-version-env、私有 lib import、旧 bin 路径 | 改成项目自己的实现及公开 dx 脚本入口，检查 package scripts、CI 和容器调用点 |
-| dx install、lint、clean、cache 等旧命令 | 按项目需要保留为自定义脚本，或把其调用者改成实际工具；标准安装准备可归入 setup |
-| --config-dir、DX_CONFIG_DIR、自定义根定位 | 在目标工程建立 dx/scripts 标记，调整调用 cwd；旧配置目录不再定义工程 |
-| 技能分发 | skills 与 dx initial 仍保留。不要把 initial 删除或误改为项目 setup |
-
-## 实施顺序
-
-1. 保留旧实现证据，完成迁移表。只清理已确认没有消费者的旧功能；需求不明确但仍被 CI 使用的行为先保留在项目侧。
-2. 创建必需的应用脚本及内部实现。使用实际工具命令，避免复制整套旧 dx 私有运行时。每条分支有成功、失败及参数处理行为；项目帮助应在业务操作前处理。
-3. 整理环境。原先的普通环境变量优先级、APP_ENV/NODE_ENV 关系、构建和测试环境逐项复核；以随技能的 [当前契约](dx-0.2-contract.md) 为准。已有 dotenv 包若仍被应用其他模块使用，应保留。
-4. 更新安装策略与调用者，进行本地/隔离验收。CI 与本地采用一致的版本策略（如全局 latest、最低 >=0.2.0），记录各自实际版本，保证创建脚本时的可执行权限入库。仅设置 CI secret 不足以证明未被文件同名值覆盖。
-5. 消费者和验证均切换后，删除无人使用的旧 dx 配置、包装和依赖，更新文档。保留 Prisma schema、PM2 ecosystem、Nx 配置等仍被项目脚本使用的工具文件。
-
-## 容易漏掉的行为
-
-- `dx build admin --prod` 中的 --prod 仍进入 build 的 argv。直接 `exec nx build "$@"` 可能把 dx 标志误传给 Nx；在项目解析层消费环境标志，正确处理 `--` 边界。
-- `.env.<环境>.local` 中已有值不会被基础 setup 更新；旧 worktree 需要同步新增配置时明确处理缺项，不能通过再次 setup 假定全部刷新。
-- 缺少环境文件不会让 dx 自行阻止数据库或部署。需要的变量、生产目标、不可逆操作和失败恢复须在应用中验证；不能删除原确认条件后裸调用工具。
-- `start stack` 不再隐含 PM2 重置或端口清理。启动哪些服务、是否清理冲突端口、如何退出由项目确定。
-- 测试文件参数不再由 dx 的 fileCommand 模板转换；验证文件和目录范围都传给了正确测试目标。
-- 新的 NODE_ENV 映射与命令名无关。旧项目若依赖“build 一定 production”或“test 一定 test”，调整调用参数或项目工具逻辑并测试。
-
-## 完成条件
-
-按 [适配回归检查](adoption-regressions.md) 验证迁移涉及的分支，特别是测试层独立性、构建产物、环境布局和后代进程回收。
-
-迁移表中每个实际使用的旧能力都已实现、替换或在用户授权下明确取消；无未解释的旧私有接口与配置消费者；根目录、子目录、fresh clone/worktree 和 CI 的安装与调用方式明确。报告实际验证结果，不能把假脚本返回成功或未执行的部署写成迁移完成。