@weotro/dx 0.3.3 → 0.3.5

package/lib/codex-initial.js

@@ -33,6 +33,7 @@ const DELETED_SKILLS = [
   'pr-ship',
   'pr-train-ship',
   'create-issue',
+  'stagewise-ui-debugging',
   'third-party-review',
 ]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weotro/dx",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "license": "MIT",
   "repository": {

package/skills/git-release/SKILL.md

@@ -25,7 +25,44 @@ description: 仅在显式调用 git-release 时使用：准备或执行版本发
 
 优先从 GitHub Release 确定上次发布，必要时结合 tags 与项目策略确认基线。首次发布按项目约定确定范围。读取该基线到目标提交的日志、diff 摘要和相关 PR；仅对影响理解有必要的文件展开内容。
 
-说明实质变更、对应 PR/Issue、兼容性和升级注意事项；按实际内容分类，不填无关栏目。先在本地完成发行说明和回访审计草稿，便于核对后发布。
+每个新 Release 正文以 `# vX.Y.Z` 标题开头，紧接非空的 `FOR USER` 段落，再写 `## 主要变更`。`FOR USER` 是产品公告页「版本日志」的唯一内容真源，由发布人员事后手动同步；缺失或格式不合法会使同步直接报错。即使以内部改动为主，也必须根据真实、已上线的变化，从用户视角写至少一条，不虚构用户收益。
+
+### FOR USER 格式与内容
+
+以下格式是严格解析契约，修改时须与同步命令解析器同步：
+
+- 正文中恰好一个 `## FOR USER` 二级标题，大小写和空格必须一致；段落到下一个 `## ` 二级标题或正文末尾为止。
+- 段落内恰好一个 `### ` 三级标题，建议不超过 40 字。
+- 标题后第一个非空段落是一行摘要，建议不超过 120 字。
+- 分组仅允许 `#### 新增`、`#### 优化`、`#### 修复`，按此顺序排列，每组最多出现一次。无内容的分组整组省略，至少保留一个分组。
+- 每组至少一条以 `- ` 开头的列表项；每条只写一行纯文本，不嵌套、不加链接，建议不超过 200 字。
+- 段落内只包含上述标题、摘要和分组列表，不出现额外标题、代码块、表格、图片或其他内容。
+
+用简体中文写给普通用户，只描述用户能感知且已上线的变化。不写 PR/Issue 编号、分支名、提交号、接口路径、错误码、配置键、表名、迁移名、环境名、内部服务名，以及 agent、审校、验证过程等发布流程信息；不写尚未上线或只在 staging 生效的内容。
+
+示例（没有内容的「修复」分组已省略）：
+
+```markdown
+# v0.2.220
+
+## FOR USER
+
+### 公告页新增版本日志
+
+现在可以在公告页查看每次更新的内容。
+
+#### 新增
+- 公告页新增「版本日志」，按发布时间倒序展示每个版本的更新。
+
+#### 优化
+- 公告页标签栏在手机上更易点击，标签较多时可以左右滑动。
+
+## 主要变更
+```
+
+在 `## 主要变更` 及后续栏目说明实质变更、对应 PR/Issue、兼容性和升级注意事项；按实际内容分类，不填无关栏目。先在本地完成发行说明和回访审计草稿，逐条核对上述格式与内容规则后发布。
+
+本约定不要求回填历史 Release（包括 v0.2.219 及之前的版本），不包含同步命令、backend 接口或客户端展示的实现，也不要求 br 品牌同步或 pt-BR 版本的段落。
 
 ## 创建发布
 
@@ -39,7 +76,7 @@ gh release create v<VERSION> --title "v<VERSION>" --notes-file <notes-path>
 ```
 预发布版本按项目规则设置 prerelease 标记。部分失败时先读回远端状态，复用已创建的 tag/Release，仅补齐剩余步骤；不覆盖冲突 tag，也不盲目重放发布。
 
-读回 `gh release view v<VERSION> --json tagName,name,body,url,isDraft,isPrerelease`，核对内容和目标提交后报告实际结果。
+读回 `gh release view v<VERSION> --json tagName,name,body,url,isDraft,isPrerelease`，核对内容和目标提交，并对远端 `body` 逐条核对「FOR USER 格式与内容」的全部规则，包括位置与唯一性、标题、单行摘要、分组名称与顺序、非空单行纯文本条目及内容禁区。不能只核对本地草稿；远端正文不合规时修正并再次读回，全部通过后才报告发行说明核验完成。
 
 ## 发布后回访
 

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

@@ -13,7 +13,9 @@ description: 审核并补齐项目面向 agent 的 GitHub 模板、开发评审
 
 检查工作区状态，读取目标及祖先的 `AGENTS.md`。按需检查已有规范、贡献指南、GitHub 模板、技术栈清单、任务配置和 CI。优先搜索标题与职责，不能仅凭文件名判定规范缺失。
 
-记录以下十项的现状、路径和缺口：Issue / PR 模板、agent 引用、开发评审规范、DX / Nx 工作流、回访规则、AGENTS.md 渐进披露结构、根 AGENTS.md 的开工前三问、`.scratch/` 的 Git 跟踪状态、跨端联动规则、GitHub Issue / PR 的直接提交流程。检查根及模块 agent 入口的内容分工、读取条件和引用链；祖先指令用于确定约束，不修改目标仓库之外的文件。区分已配置的命令、实际运行结果与未来建议；不读取或输出秘密值。
+记录以下十一项的现状、路径和缺口：Issue / PR 模板、agent 引用、开发评审规范、DX / Nx 工作流、回访规则、AGENTS.md 渐进披露结构、根 AGENTS.md 的开工前两问、`.scratch/` 的 Git 跟踪状态、跨端联动规则、GitHub Issue / PR 的直接提交流程、中文协作与英文诊断的语言规范。检查根及模块 agent 入口的内容分工、读取条件和引用链；祖先指令用于确定约束，不修改目标仓库之外的文件。区分已配置的命令、实际运行结果与未来建议；不读取或输出秘密值。
+
+另检查根 `AGENTS.md` 的视觉核对规则：是否明确默认无需视觉核对，以及用户或适用技能明确要求时的例外。
 
 完成条件：每项均有存在证据或明确的缺失结论，能够识别目标模块与实际工具链。
 
@@ -56,7 +58,7 @@ description: 审核并补齐项目面向 agent 的 GitHub 模板、开发评审
 | DX / Nx 工作流 | [工作流骨架](assets/dx-development-workflow.md) | `docs/guides/dx-development-workflow.md` |
 | 回访规则 | [回访规则](assets/follow-up-issues.md) | `docs/agents/follow-up-issues.md` |
 
-文档写给执行任务的 agent：说明触发条件、具体决策、命令前置条件、失败处理与完成证据。删除骨架中的编写提示及不适用分支，替换所有 `{{...}}`。保留目标项目语言约定，无约定时使用简体中文。
+文档写给执行任务的 agent：说明触发条件、具体决策、命令前置条件、失败处理与完成证据。删除骨架中的编写提示及不适用分支，替换所有 `{{...}}`。新建或修改的内容遵循第 4 步的语言规范。
 
 开发规范应覆盖实际模块与风险；不会因使用此技能就迁移成三层架构或引入新的测试框架。将已有约束、此次建立的规则和未来建议分清；尚未接入的检查不能写成已经运行的门禁。
 
@@ -68,7 +70,13 @@ DX 文档必须检查实际 DX 配置、Nx 目标与 CLI 能力。已接入则
 
 ## 4. 检查并改造 AGENTS.md 的渐进披露结构
 
-检查根 `AGENTS.md`（沿用仓库已有的文件名大小写）是否包含以下开工前三问。已有完整等效约束且正确、符合项目状况时保持原样；部分缺失时只补缺项，整段缺失时在根入口的工作原则或全局约束处加入以下内容，沿用项目语言。此约束属于全局必需规则，保留在根入口正文中：
+检查根 `AGENTS.md`（沿用仓库已有的文件名大小写）是否明确包含以下语言规范。已有完整等效规则则保留，部分缺失时只补缺项，缺失时在根入口的全局约束中添加；仅写“默认中文回复”不足以覆盖全部要求：
+
+> 所有输出文档、讨论与回复、Issue / PR 的标题和正文、评审评论以及代码注释均使用简体中文；程序日志、错误信息及其他运行时诊断文本使用英文。代码标识符、命令、协议字段及引用的原始日志或错误文本保持原样。
+
+检查模块入口与被引用规范中的语言要求，修正与上述规则冲突的说明，确保中文协作与英文诊断两类要求同时生效。只读审核仅报告缺口；本次整备补齐规则，不批量翻译历史文档或改写应用日志。
+
+检查根 `AGENTS.md`（沿用仓库已有的文件名大小写）是否包含以下开工前两问。已有完整等效约束且正确、符合项目状况时保持原样；部分缺失时只补缺项，整段缺失时在根入口的工作原则或全局约束处加入以下内容，沿用项目语言。此约束属于全局必需规则，保留在根入口正文中：
 
 > Ask yourself before starting:
 >
@@ -81,6 +89,12 @@ DX 文档必须检查实际 DX 配置、Nx 目标与 CLI 能力。已接入则
 
 已有等效约束时复用，仅有单端时将跨端检查记为“不适用”，不添加不存在的端或要求无关端机械同步。
 
+检查根 `AGENTS.md` 是否包含以下视觉核对规则。已有完整等效规则则保留，部分缺失时只补缺项，缺失时在根入口的验收约束中添加：
+
+> 在验收或检查前端、移动端 App 或页面时，默认无需进行视觉核对；只有用户或当前任务适用的技能明确要求视觉核对时才执行。功能、交互、测试及构建等其他必要验证仍按任务要求进行。
+
+核对模块入口与被引用的验收规范，修正默认强制视觉核对的冲突说明，保留用户或适用技能明确要求的例外。只读审核仅报告缺口。
+
 渐进披露按任务需要加载说明：根入口保留项目识别、全局必需约束与条件明确的文档入口；模块入口保留该目录适用的规则；详细流程、命令说明、模板字段和专题规范放在被引用文档中。判断依据是内容职责与加载方式，不以行数或是否已有链接判定。只有简短必需规则的入口无需为了拆分而创建文件。
 
 存在下列情况时，在本次整备中直接改造：入口堆放仅特定任务需要的详细流程；所有专题文档被要求无条件全文加载；只有链接而没有读取条件；相同规范在多个入口重复维护。只读审核请求则报告问题和迁移建议。
@@ -106,6 +120,8 @@ DX 文档必须检查实际 DX 配置、Nx 目标与 CLI 能力。已接入则
 
 ## 5. 验证与交付
 
-检查差异、Markdown 链接、模板 frontmatter、占位符和竞争模板。逐项复核第 1 步的十项清单与所有新引用，确认根入口的开工前三问完整、`.scratch/` 的跟踪与忽略状态已分别核实、适用项目的跨端联动规则覆盖实际存在的各端，已有正确且适用的内容未被改写，每处修改均有具体缺口或纠错依据，再执行一次不会增加文件或重复条目。对照迁移记录检查规则完整性，并分别用代码修改、Issue / PR 编写和回访任务走查入口；模拟用户要求创建 GitHub Issue / PR 的任务，确认流程直接提交正式 Issue 或普通 PR，没有草稿确认或 Draft 状态的中间环节；多端项目额外从 mobile 或 front 修改任务走查另一端影响评估，确认能够找到对应规范，且不会要求加载无关专题。
+复核视觉核对规则的默认行为与例外：普通前端、移动端 App 或页面验收不增加视觉核对要求；用户或适用技能明确要求时执行，且不影响其他必要验证。
+
+检查差异、Markdown 链接、模板 frontmatter、占位符和竞争模板。逐项复核第 1 步的十一项清单与所有新引用，确认根入口的开工前两问完整、语言规范覆盖中文文档与讨论、Issue / PR、评论和代码注释以及英文日志与错误信息、`.scratch/` 的跟踪与忽略状态已分别核实、适用项目的跨端联动规则覆盖实际存在的各端，已有正确且适用的内容未被改写，每处修改均有具体缺口或纠错依据，再执行一次不会增加文件或重复条目。对照迁移记录检查规则完整性，并分别用代码修改、Issue / PR 编写和回访任务走查入口；模拟用户要求创建 GitHub Issue / PR 的任务，确认流程直接提交正式 Issue 或普通 PR，没有草稿确认或 Draft 状态的中间环节；多端项目额外从 mobile 或 front 修改任务走查另一端影响评估，确认能够找到对应规范，且不会要求加载无关专题。
 
 纯文档修改按项目规则做差异与格式验证；验证命令存在可以检查配置或安全的帮助输出，不为文档审核运行发布、迁移或全仓测试。报告每项的保留 / 新建 / 更新状态、文件链接、实际验证和未确认事项，以及渐进披露检查结论与章节迁移去向；未接入 DX / Nx 要明确说明。不要将文档中列出的命令写成已经执行通过。

package/skills/upsert-tool/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: upsert-tool
+description: 仅在用户显式调用 upsert-tool 时使用：通过 SSH config 主机别名安装或升级指定软件，统一有效安装，并验证交互式与非交互式调用。
+disable-model-invocation: true
+---
+
+# Upsert Tool
+
+将指定 SSH 主机上的目标软件安装或升级至最新稳定版。每个软件保留一套有效安装，目标登录用户在交互式和非交互式 shell 中均可直接调用。仅响应用户手动调用；普通安装、升级请求不自动触发本技能。
+
+Codex 调用示例：`$upsert-tool 在 SSH Host staging 上安装或升级 ripgrep 和 jq`。
+Claude Code 调用示例：`/upsert-tool 在 SSH Host staging 上安装或升级 ripgrep 和 jq`。
+两端共用本技能正文，使用各自可用的终端工具执行 SSH，无需依赖另一端的专用工具。用户可指定 SSH config 路径；省略时使用 SSH 默认配置。
+
+## 1. 确定主机与软件
+
+- 使用用户给出的具体 Host 别名，检查相应 SSH config 及 Include，通过 `ssh -G <alias>` 核对最终连接目标、用户和端口；自定义配置时所有 SSH 调用均带同一个 `-F`。别名缺失、存在歧义或只有通配模式时，先询问具体目标，不猜主机。
+- 建立“用户名称、官方项目、包标识、可执行命令”的映射。名称无法唯一对应软件时，列出候选及区别并反问用户；得到答案前不安装、不卸载同名候选。可继续检查其他已明确的软件。
+- 保留 SSH 的主机密钥校验，认证或密钥校验失败时报告具体阻塞，不通过禁用校验绕过。将别名、包名作为数据安全传参，不能直接拼接成远程 shell 代码。
+
+完成条件：目标主机、登录用户和每个待操作软件的身份唯一明确。
+
+## 2. 检查现状并选择安装来源
+
+- 远程检查系统、架构、默认 shell、权限与现有包管理器。只读取所需配置，避免输出凭据、完整环境或含密钥的进程参数。
+- 对每个工具检查命令解析的全部路径、软链接最终目标、版本、包管理器归属及已知安装位置。检查系统级与目标用户级安装、版本管理器 shim、相关服务的实际执行路径；不能仅凭 `command -v` 断定只有一份。
+- 优先沿用可信的现有安装渠道。查询官方稳定发布与该渠道的可用版本，确定当前系统和架构的兼容性。仓库落后、版本被锁定或最新版不兼容时，说明差异并处理原因；需要更换来源或破坏兼容性且授权不明确时，提出具体方案询问用户。不得把旧仓库版本或预发布版称为最新稳定版。
+- 默认唯一性范围是目标软件的系统级与目标用户级有效安装，不擅自清理其他用户、项目依赖、容器或系统必需组件。多个入口指向同一安装不算重复；独立旧安装不能仅用调整 PATH 隐藏。检查依赖后通过所属管理器清理重复安装；无法安全合并时先询问并报告未满足唯一性。
+
+完成条件：每个软件都有当前版本、目标版本、保留的来源与路径，以及必要的去重方案。已经达标的工具直接验证，不重装。
+
+## 3. 处理运行状态并升级
+
+- 写入前检查目标二进制是否正被服务或任务使用，识别 systemd、launchd、容器、进程管理器或独立进程的实际管理方式，记录原运行状态、启动方式、配置和恢复路径。包升级的自动重启钩子也计入影响。
+- 根据该软件的升级说明决定能否在线替换、是否需要 reload、优雅 stop/start 或依赖顺序。运行中 CLI 任务先等待结束；无法等待时询问如何处理。需要停机但已有授权未覆盖中断影响时，先给出受影响服务和具体操作，再询问维护窗口。
+- 停止前准备可用的旧版本或恢复方式，保留配置和数据；涉及数据格式迁移时先验证备份与恢复条件。二进制降级不等于数据可回滚。
+- 通过原管理器优雅停止目标服务并确认退出，避免监管器自动拉起旧进程；不使用宽泛的 `pkill`，不默认强杀。使用已确认来源安装或升级指定软件及必要依赖，不执行整机无差别升级。
+- 完成安装后按原运行状态恢复：原先运行的服务启动并验证，原先停止的服务保持停止。确保运行进程实际使用新版本，而非只验证磁盘上的新文件。
+- 安装或健康检查失败时停止后续依赖操作，按准备的恢复方案处理；记录恢复是否成功。无法安全恢复时保留证据和备份，报告受影响服务，不反复重启或继续破坏性清理。
+
+完成条件：目标版本已安装，重复有效安装已安全清理，受影响服务恢复到预期状态；失败项明确记录，不冒充成功。
+
+## 4. 验证调用与交付
+
+- 将可执行入口放在目标用户两种 shell 均可见的持久 PATH 中，必要时使用指向唯一安装的稳定软链接。根据实际 shell 的启动文件规则选择最小改动；仅改 `.bashrc`、临时 `export`、alias 或 shell function 不能作为通用修复。
+- 开启新的 SSH 会话，分别验证交互式登录 shell、交互式非登录 shell及普通 `ssh <alias> '<command>'` 的非交互式远程命令。使用该 shell 支持的启动参数，不能统一假设为 Bash。验证不能靠测试命令临时设置 PATH 或额外 source 文件制造成功。
+- 每种模式均检查命令解析、最终真实路径和版本，并执行无副作用的基本功能检查；需要运行时环境的工具同时验证其解释器与必要环境可用。服务进程另查其自身运行环境，不能用 shell 成功替代服务健康检查。
+- 再次检查重复安装与入口遮蔽。仅在实际检查覆盖范围内声明唯一；有无法读取的位置或未覆盖用户时明确说明范围。对运行中的服务检查状态和健康端点；原先停止的服务验证配置与可执行文件即可。
+- 用中文报告主机别名和用户、各软件安装前后版本、来源和唯一安装路径、各 shell 验证结果、服务停止/恢复结果，以及未完成项和下一步。无法确认上游最新版本时明确写“最新版本未核实”。
+
+完成条件：所有指定软件在约定范围内满足最新稳定版、唯一有效安装和两种调用方式，且服务状态符合预期；否则交付部分完成报告及明确阻塞。

package/skills/stagewise-ui-debugging/SKILL.md

@@ -1,54 +0,0 @@
----
-name: stagewise-ui-debugging
-description: 仅在显式调用 stagewise-ui-debugging 时使用：对比 Stagewise 设计稿与前端 UI。
----
-
-# Stagewise UI 调试
-
-## 执行边界与优先级
-
-在宿主系统与开发者指令约束内，冲突时依次采用：当前任务的具体要求与已有授权 > 目标项目适用的 AGENTS.md > 本技能及其引用的通用流程。
-只读检索、本地草稿、可回滚编辑和常规测试可自主推断并继续；从相关文件和直接依赖开始，仅在证据不足或影响跨模块时扩大范围，复用仍有效的验证。
-仅在不可逆或难以回滚的修改缺少具体授权时，先完成预览、草稿与验证，再说明对象和影响并等待确认；会话中已有授权继续有效。缺少事实时先查证、标注假设并推进独立工作，确实无法确定操作目标时才询问。对外发送消息须有明确授权。
-
-## 概览
-
-用于对齐 `design/ui_kits/app/` 设计稿和 `apps/front` 前端页面。核心原则：改 UI 前先在相同视口下，对比 Stagewise 包装后的设计站和前端站。
-
-## 速查
-
-| 目标 | 未启动时的候选命令 | 默认访问地址 |
-| --- | --- | --- |
-| 设计稿 | `dx start stagewise-design-system` | `http://localhost:8766/ui_kits/app/` |
-| 前端页面 | `dx start stack-front` | `http://localhost:3002` |
-
-`stagewise-design-system` 会用 Stagewise 包装设计静态站，桥接 `8765 -> 8766`。`stack-front` 会启动 PM2 交互式服务栈和 `stagewise-front`，桥接 `3001 -> 3002`。
-
-## 流程
-
-1. 从项目配置核实地址并检查服务状态，复用已启动的实例。缺少服务时，根据项目实际命令自主启动所需的本地开发服务；默认命令示例：
-   ```bash
-   dx start stagewise-design-system
-   dx start stack-front
-   ```
-2. 用浏览器工具访问所需页面。打不开、空白或渲染异常时，自行检查端口、启动日志和依赖，修复可回滚的本地问题后重试；需要用户凭据或交互时说明具体阻塞。
-3. 在相同浏览器视口下对比本次涉及的组件或页面。响应式改动检查桌面和移动端；单一断点修改先验证该断点，影响布局时再扩展。
-4. 检查 DOM 时记住：两个页面都经过 Stagewise 包装。包装节点、桥接覆盖层、注入属性可能和裸应用 DOM 不同。优先做视觉对比和稳定的应用层选择器检查；编辑前先确认样式来自产品 UI，而不是 Stagewise 外壳。
-5. 修改后端或前端页面后，页面会自动刷新到最新状态。需要确认时重新查看或刷新浏览器对比，不要先急着重启服务。
-6. 如果任务涉及真实 UI 实现，按项目指令读取涉及组件的设计规则；`design/readme.md`、`design/SKILL.md`、`ruler/design-system.md` 仅在实际存在且与本次修改相关时读取。
-
-## 触发示例
-
-用户说：“调一下前端和设计稿的卡片间距。”
-
-用户显式调用本技能后，检查服务、定位该卡片并在同一视口对比，修改间距并验证受影响的布局。普通间距调整不自动加载本技能。
-
-## 常见误区
-
-| 常见问题 | 处理方式 |
-| --- | --- |
-| 用 `localhost:3001` 和设计稿对比，而不是 Stagewise 的 `3002` | 使用包装后的地址，让前端和设计稿处在同一种调试表面。 |
-| 把空白页直接当成 UI bug | 先确认对应 `dx start ...` 服务正在运行且健康。 |
-| 用不同视口宽度对比 | 设计稿和前端设置相同视口，并补充移动端检查。 |
-| 根据 Stagewise 包装 DOM 直接改样式 | 确认选中的节点或样式属于产品 UI，不是 Stagewise 外壳。 |
-| 每次页面改动后立刻手动重启 | 先看自动刷新或热更新后的浏览器结果，再决定是否需要重启。 |