@weotro/dx 0.3.4 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weotro/dx",
-  "version": "0.3.4",
+  "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,7 @@ 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` 的视觉核对规则：是否明确默认无需视觉核对，以及用户或适用技能明确要求时的例外。
 
@@ -76,7 +76,7 @@ DX 文档必须检查实际 DX 配置、Nx 目标与 CLI 能力。已接入则
 
 检查模块入口与被引用规范中的语言要求，修正与上述规则冲突的说明，确保中文协作与英文诊断两类要求同时生效。只读审核仅报告缺口；本次整备补齐规则，不批量翻译历史文档或改写应用日志。
 
-检查根 `AGENTS.md`（沿用仓库已有的文件名大小写）是否包含以下开工前三问。已有完整等效约束且正确、符合项目状况时保持原样；部分缺失时只补缺项，整段缺失时在根入口的工作原则或全局约束处加入以下内容，沿用项目语言。此约束属于全局必需规则，保留在根入口正文中：
+检查根 `AGENTS.md`（沿用仓库已有的文件名大小写）是否包含以下开工前两问。已有完整等效约束且正确、符合项目状况时保持原样；部分缺失时只补缺项，整段缺失时在根入口的工作原则或全局约束处加入以下内容，沿用项目语言。此约束属于全局必需规则，保留在根入口正文中：
 
 > Ask yourself before starting:
 >
@@ -122,6 +122,6 @@ DX 文档必须检查实际 DX 配置、Nx 目标与 CLI 能力。已接入则
 
 复核视觉核对规则的默认行为与例外：普通前端、移动端 App 或页面验收不增加视觉核对要求；用户或适用技能明确要求时执行，且不影响其他必要验证。
 
-检查差异、Markdown 链接、模板 frontmatter、占位符和竞争模板。逐项复核第 1 步的十一项清单与所有新引用，确认根入口的开工前三问完整、语言规范覆盖中文文档与讨论、Issue / PR、评论和代码注释以及英文日志与错误信息、`.scratch/` 的跟踪与忽略状态已分别核实、适用项目的跨端联动规则覆盖实际存在的各端，已有正确且适用的内容未被改写，每处修改均有具体缺口或纠错依据，再执行一次不会增加文件或重复条目。对照迁移记录检查规则完整性，并分别用代码修改、Issue / PR 编写和回访任务走查入口；模拟用户要求创建 GitHub Issue / PR 的任务，确认流程直接提交正式 Issue 或普通 PR，没有草稿确认或 Draft 状态的中间环节；多端项目额外从 mobile 或 front 修改任务走查另一端影响评估，确认能够找到对应规范，且不会要求加载无关专题。
+检查差异、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/upsert-tool/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false