@weotro/dx 0.1.16 → 0.1.17

package/package.json

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

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

@@ -0,0 +1,82 @@
+---
+name: project-agent-standards
+description: 审核并补齐项目面向 agent 的 GitHub 模板、开发评审规范、DX 工作流与回访 Issue 规则，将 AGENTS.md 整理为按需读取的渐进披露结构。
+---
+
+# 项目 Agent 规范整备
+
+对用户指定仓库执行审核并补齐缺项；未指定时使用当前仓库。只读审核请求只报告差异。默认执行本地可回退的模板和文档修改，不包含提交、推送、发布 Issue / PR、安装工具或改造构建系统。现有全局技能保持不变。
+
+## 1. 建立项目依据
+
+检查工作区状态，读取目标及祖先的 `AGENTS.md`。按需检查已有规范、贡献指南、GitHub 模板、技术栈清单、任务配置和 CI。优先搜索标题与职责，不能仅凭文件名判定规范缺失。
+
+记录以下六项的现状、路径和缺口：Issue / PR 模板、agent 引用、开发评审规范、DX / Nx 工作流、回访规则、AGENTS.md 渐进披露结构。检查根及模块 agent 入口的内容分工、读取条件和引用链；祖先指令用于确定约束，不修改目标仓库之外的文件。区分已配置的命令、实际运行结果与未来建议；不读取或输出秘密值。
+
+完成条件：每项均有存在证据或明确的缺失结论，能够识别目标模块与实际工具链。
+
+## 2. 补齐 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 恢复。用户明确要求统一为附带模板时直接覆盖。
+
+检查根目录、`docs/` 与 `.github/` 是否有竞争的默认 PR 模板；将仍适用的独有约束合入标准模板，再清理被取代的默认副本并更新引用。保留用途不同的 Issue Forms、多模板及配置，不因其存在就删除。已有标准文件中的项目专属验收要求同样需要保留。
+
+完成条件：两个标准位置均有可用模板，默认 PR 模板选择无冲突，独有约束和用户原文可追踪。
+
+## 3. 补齐面向 agent 的参考文档
+
+按缺口读取对应资源，依照源码、配置和已有决策改写。现有等效文档优先就地补齐并继续使用其路径；只有缺失时才使用表中的默认路径。
+
+| 缺项 | 适配资源 | 默认路径 |
+| --- | --- | --- |
+| 开发与评审规范 | [开发规范骨架](assets/development-standards.md) | `docs/guides/development-standards.md` |
+| 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：说明触发条件、具体决策、命令前置条件、失败处理与完成证据。删除骨架中的编写提示及不适用分支，替换所有 `{{...}}`。保留目标项目语言约定，无约定时使用简体中文。
+
+开发规范应覆盖实际模块与风险；不会因使用此技能就迁移成三层架构或引入新的测试框架。将已有约束、此次建立的规则和未来建议分清；尚未接入的检查不能写成已经运行的门禁。
+
+DX 文档必须检查实际 DX 配置、Nx 目标与 CLI 能力。已接入则记录真实命令；只接入其一则分别说明职责；均未接入也生成说明，明确“未接入”并给出现有命令，不编造 `dx` 入口。工具链接入是另一个任务。
+
+回访规则合入现有 Issue 规范的对应章节；没有载体时才创建独立文档。沿用目标项目的本地或远程追踪方式，不引入原始项目的 `.scratch/` 默认存储决定。
+
+完成条件：三类说明可被 agent 直接使用，命令有配置依据，待确认事实明确列出，无未替换占位符。
+
+## 4. 检查并改造 AGENTS.md 的渐进披露结构
+
+渐进披露按任务需要加载说明：根入口保留项目识别、全局必需约束与条件明确的文档入口；模块入口保留该目录适用的规则；详细流程、命令说明、模板字段和专题规范放在被引用文档中。判断依据是内容职责与加载方式，不以行数或是否已有链接判定。只有简短必需规则的入口无需为了拆分而创建文件。
+
+存在下列情况时，在本次整备中直接改造：入口堆放仅特定任务需要的详细流程；所有专题文档被要求无条件全文加载；只有链接而没有读取条件；相同规范在多个入口重复维护。只读审核请求则报告问题和迁移建议。
+
+1. 按原有规则的适用范围梳理内容，保留全局必需约束及模块覆盖关系；将条件性细节归入现有等效文档，缺少载体时再按专题创建文档，沿用项目目录约定。
+2. 在原入口用“执行什么任务时，必须读取哪个文档”的短指令替换已迁移细节。适用时才读取的专题不使用无条件全文导入；避免入口互相引用或仅为转发再增加一层目录页。
+3. 更新迁移内容中的相对链接和其他引用，确保目标存在且能从入口到达。保留原规则的强制程度、例外、权限边界和历史决策，不因移动位置而削弱要求。修改未提交或未跟踪原文前保存仓库外备份并记录路径。
+4. 建立原章节到新位置的对应记录，逐项核对无遗漏后再删除重复正文。已有合适结构则就地补齐缺失的读取条件和链接，重复执行不重复拆分。
+
+在根 `AGENTS.md` 放 GitHub 模板和回访规则的触发入口；模块独有的开发规范放在模块 `AGENTS.md`。若仓库采用其他 agent 入口，复用其引用链；缺少入口则创建根 `AGENTS.md`。参考以下文字并替换为真实的相对链接：
+
+> 创建或更新 GitHub Issue / PR 正文时，必须读取并使用 [Issue 模板](.github/ISSUE_TEMPLATE/issue.md) / [PR 模板](.github/pull_request_template.md)。网页、CLI、API 和技能操作均适用。正文结构和填写要求以模板为准；发布前检查必填章节与占位内容。
+
+> 开发、修复或评审代码时，按任务范围读取 [开发与评审规范](docs/guides/development-standards.md) 的相关章节。
+
+> 初始化环境、选择启动 / 验证 / 构建命令或排查环境注入时，读取 [开发工作流](docs/guides/dx-development-workflow.md) 的相关章节。
+
+> 创建、更新或转为回访用途的 Issue 时，读取 [回访规则](docs/agents/follow-up-issues.md)。
+
+入口保留必要约束和读取条件。模板字段留在模板，命令细节留在工作流，回访标识留在 Issue 规范。将仓库其他位置同义重复的说明改成引用或删除；保留模块专属约束与历史决策。重复运行时复用既有入口，不追加相同规则。
+
+完成条件：入口、模块规则与专题细节分工清楚，每个按需文档都有明确触发条件，原有有效约束完整保留，没有失效链接、循环引用或无条件加载所有专题的要求。
+
+## 5. 验证与交付
+
+检查差异、Markdown 链接、模板 frontmatter、占位符和竞争模板。逐项复核第 1 步的六项清单与所有新引用，确认再执行一次不会增加文件或重复条目。对照迁移记录检查规则完整性，并分别用代码修改、Issue / PR 编写和回访任务走查入口，确认能够找到对应规范，且不会要求加载无关专题。
+
+纯文档修改按项目规则做差异与格式验证；验证命令存在可以检查配置或安全的帮助输出，不为文档审核运行发布、迁移或全仓测试。报告每项的保留 / 新建 / 更新状态、文件链接、实际验证和未确认事项，以及渐进披露检查结论与章节迁移去向；未接入 DX / Nx 要明确说明。不要将文档中列出的命令写成已经执行通过。

package/skills/project-agent-standards/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "项目 Agent 规范整备"
+  short_description: "审核并补齐 GitHub 模板、开发评审规范、DX 工作流和回访规则"
+  default_prompt: "使用 $project-agent-standards 审核当前仓库并补齐面向 agent 的项目规范。"
+policy:
+  allow_implicit_invocation: false

package/skills/project-agent-standards/assets/development-standards.md

@@ -0,0 +1,49 @@
+<!-- 编写提示：这是适配骨架，不是可直接复制的项目决策。用实际目录、框架和验证目标替换变量，删除不适用章节与本提示。 -->
+# {{项目或模块}} 开发与评审规范
+
+适用范围：{{目录与业务入口}}。
+依据：{{已有架构决策、领域术语、工具配置的相对链接}}。
+
+## 规范与执行
+
+开发、修复和评审时按改动范围读取对应章节。“必须”是验收要求，“应”允许有依据的偏离，“可”是可选方案。新增规则的目标状态与现有实现分开记录；文档本身不证明实现合规。
+
+开始实现前明确输入输出、权限、业务不变量、失败行为和验证方式。架构例外按项目既有决策机制处理，并在 PR 模板对应章节记录影响及验证。
+
+## 模块边界与依赖
+
+{{记录实际模块、各层职责、允许的依赖方向、入口与组装位置，以及一组目标仓库真实路径。单体、库、前端或脚本项目按自身结构填写。}}
+
+公共接口暴露调用者需要的能力；基础设施与第三方细节留在适配边界。修改共享接口时检查实际消费方，并说明兼容方式。
+
+## 契约、状态与错误
+
+{{记录协议或组件接口的真源、生成文件边界、输入校验、错误码或异常约定。}}
+
+边界明确空值、非法输入、超时、取消与重复操作的行为。状态变化通过可观察结果验收。诊断遵循项目语言及脱敏规则，避免暴露凭据和用户敏感内容。
+
+## 数据与外部副作用
+
+{{仅在存在持久化或远程调用时保留：事务边界、并发约束、幂等、重试、迁移兼容性、失败恢复及资源生命周期。引用实际实现约定，不默认引入事务框架或 Outbox。}}
+
+## 界面与交互
+
+{{仅在存在界面时保留：状态归属、加载/空/错误状态、可访问性、响应式、已有设计系统、前后端契约和关键交互验收。}}
+
+## 安全、配置与运行
+
+{{说明实际身份与权限边界、配置来源及优先级、秘密存储、启停与日志约定。依项目风险补充资源限制和可观测性。}}
+
+## 验证与评审
+
+按变更风险选择能观察行为的检查：业务逻辑、接口、持久化、交互及跨模块链路分别映射到现有测试入口。缺少自动化覆盖时记录具体缺口，不把计划中的检查当成已接入门禁。
+
+| 变更范围 | 验收证据 | 命令依据 |
+| --- | --- | --- |
+| {{真实模块或变更类型}} | {{需验证的行为、失败路径}} | {{链接到工作流对应章节}} |
+
+纯文档核对差异、格式和引用；代码改动执行覆盖本次风险的检查。相关检查已通过且输入未变化时不重复运行。按证据区分本次回归、既有失败和环境问题；验证结果统一填写 PR 模板。
+
+## 规范维护
+
+{{列出本项目特有的评审要点及已知未落实要求。只引用真实存在的文档；需要外部依据时核对所用框架版本，未核实的判断标为待确认。}}

package/skills/project-agent-standards/assets/dx-development-workflow.md

@@ -0,0 +1,46 @@
+<!-- 编写提示：先检查项目实际配置。未接入 DX / Nx 时保留标题但明确状态，将命令表改为现有工具入口；删除无关章节、变量和本提示。 -->
+# DX 与 Nx 开发工作流
+
+供 agent 在初始化环境、选择命令或排查执行问题时按需读取。
+
+## 工具职责与真源
+
+接入状态：{{DX 与 Nx 分别为已接入 / 未接入；缺少 CLI 与缺少仓库配置分别说明}}。
+
+{{列出公开任务入口、内部编排工具、实际配置路径及版本依据。只有已验证使用全局 DX 时才写全局安装策略；不套用其他仓库包名、版本或目录。}}
+
+## 环境准备
+
+{{记录实际运行时版本来源、依赖安装命令、所需服务及其由谁管理。没有初始化入口就列现有必要步骤，不虚构 dx setup。}}
+
+## 配置与注入
+
+{{记录环境选择参数、配置文件加载顺序、秘密的本地存放位置、必须变量名及校验时机。说明绕过公开入口是否会丢失环境注入；不填写真实秘密。}}
+
+## 命令选择
+
+下表命令来自项目配置；“已配置”不表示本次已经运行通过。
+
+| 任务 | 实际命令 | 前置条件 | 行为与副作用 |
+| --- | --- | --- | --- |
+| {{初始化 / 启动 / 检查 / 测试 / 构建中实际存在的任务}} | {{精确命令}} | {{所需依赖与环境}} | {{执行范围、产物、是否启动服务或修改数据}} |
+
+{{DX 已接入时核对 CLI 支持的参数与目标映射；Nx 已接入时说明依赖顺序、缓存和 configuration。只记录存在的目标，明确附加路径或参数是否真的透传。}}
+
+## 验证范围与失败处理
+
+{{按模块列出行为验收入口，区分单元 / 集成 / E2E、Mock / 真实依赖。说明完整套件是否已包含子套件，避免重复执行。}}
+
+环境或依赖缺失单列为未运行或环境失败；测试进程失败不能记为通过。失败证据包括实际命令、退出状态和关键原因。运行结果填写仓库 PR 模板。
+
+## 生成产物与服务生命周期
+
+{{有生成代码时：真源、生成目标、消费方依赖和是否入库。有服务时：启动/结束责任、端口来源、临时数据隔离与清理，以及是否自动迁移。无相应行为则删除本节。}}
+
+## 发布边界
+
+{{只列现有发布入口、目标环境和执行权限；没有入口就明确尚未配置。文档审核不执行发布或迁移。}}
+
+## 尚未接入或待确认
+
+{{只列具体缺项及其对 agent 的影响。未接入 DX / Nx 时给出现有替代入口，明确本次只补文档，未安装或接入工具链；无缺项时删除本节。}}

package/skills/project-agent-standards/assets/follow-up-issues.md

@@ -0,0 +1,9 @@
+# 回访 Issue 规则
+
+创建用于后续复查、跟进验证的 Issue，或将既有 Issue 转为该用途时：
+
+- 标题使用 `[回访] 原标题`，并添加名称完全一致的 `回访` 标签；前缀与标签只保留一份，保留其他标签和流程状态。
+- GitHub Issue 正文沿用仓库 Issue 模板，在现有章节内写清回访对象、触发条件或时间、可观察的验收标准；模板的正文结构不在此重复定义。
+- 获得创建或更新 GitHub Issue 的授权后，若仓库缺少 `回访` label，随该次操作创建并应用；权限不足时报告标签未完成，不把 Issue 标记为全部处理完成。
+- 项目已有本地 Issue 追踪时，一级标题保留此前缀，在 `Labels:` 行或既有标签字段记录 `回访`，沿用原状态机制。同步到 GitHub 时保留标识；本规则不改变项目的本地 / 远程追踪策略。
+- 验证完成后按项目流程记录证据并关闭或更新状态；“回访”本身不表示验收通过。

package/skills/project-agent-standards/assets/github/ISSUE_TEMPLATE/issue.md

@@ -0,0 +1,27 @@
+---
+name: Issue
+about: 提交功能、缺陷、重构或其他可执行事项
+title: ""
+labels: ""
+assignees: ""
+---
+
+## 背景
+
+<!-- 说明当前情况、问题或提出该事项的原因。 -->
+
+## 目标
+
+<!-- 说明完成后可观察的状态；明确不做的事单独列出。 -->
+
+## 验收标准
+
+<!-- 使用客观、可验证的条目；每条标准应能通过测试、命令或明确观察进行确认。 -->
+
+- [ ]
+
+## 关联
+
+<!-- 可选。相关 Issue/PR 用 Refs: #<id> 列出；没有则删除本段。 -->
+
+Refs: #

package/skills/project-agent-standards/assets/github/pull_request_template.md

@@ -0,0 +1,27 @@
+## 变更目的
+
+<!-- 用 1-3 句话说明问题、预期结果和必要背景；不要复述 Issue 全文。 -->
+
+## 主要改动
+
+<!-- 用精简条目说明最终行为、契约或运维变化；不记录探索过程、agent 分工、复杂度门禁或完整日志。 -->
+
+-
+
+## 验证结果
+
+<!-- 只记录当前 HEAD 的最低充分验证。每项写“命令或检查 — 状态 — 关键结果”；状态使用“通过 / 失败 / 未运行”。失败必须说明是否为已登记并在基线复现的既有问题。 -->
+
+-
+
+## 风险与后续
+
+<!-- 统一列出未覆盖范围、已知风险、follow-up 和合并/发布后动作；每项标注“阻塞 / 非阻塞 / 发布后”。存在“阻塞”项时不得合并；没有则填写“无”。 -->
+
+无
+
+## 关联
+
+<!-- 主 Issue 使用 Closes: #<issue-id>；其他关联使用 Refs: #<issue-id>。 -->
+
+Closes: #

package/skills/ship-issue-pr/SKILL.md

@@ -122,6 +122,8 @@ Issue/PR 正文及评论优先使用结构化工具参数；使用 CLI 时将多
 
 全过程发现新的范围外问题时，搜索去重后直接创建或补充 follow-up Issue，按项目模板与规划记录复现/证据、影响、目标、验收标准、来源 Issue/PR 和依赖。当前验收必须解决的问题留在本次修复循环，不能通过拆 Issue 绕过合并门禁。
 
+回访性质的 follow-up（例如发布后效果检查、观察期结束后的验证或问题修复后的跟踪确认）必须添加回访标签。优先使用项目已有的回访标签；没有对应标签时创建 `回访` 并添加。复用已有 Issue 时也要补齐标签，保留其他标签，并读回确认。正文写明回访时间或触发条件、检查对象和完成标准；尚未到回访时机的任务按等待项处理。
+
 | Follow-up 状态 | 处理 |
 | --- | --- |
 | 无阻塞，代码与所需资源均可用 | 直接创建独立 worktree，派发 sub-agent，要求调用 `ship-issue-pr` 完成同一套流程 |