@namewta/speculo 0.1.0

package/speculo/skills/github-npm-ops/references/issue-pr-triage.md

@@ -0,0 +1,219 @@
+# Issue 与 PR 分诊手册
+
+标签体系、分诊节奏、社区 PR 质量线与 stale 策略的落地细节。SKILL.md 中保留的是每天会用的动作，这里覆盖边界与模板。
+
+## 标签体系
+
+建议仓库标签按维度分组，而不是一股脑堆平。
+
+### 类型标签（必须有一个）
+
+| 标签               | 含义                                    |
+| ------------------ | --------------------------------------- |
+| `bug`              | 功能不符合预期或文档                    |
+| `feature-request`  | 新功能请求                              |
+| `enhancement`      | 现有功能的改进                          |
+| `documentation`    | 文档相关                                |
+| `question`         | 使用类问题（非 bug）                    |
+| `duplicate`        | 与其他 issue/PR 重复                    |
+| `invalid`          | 不适用本项目                            |
+| `wontfix`          | 不会修（给清晰理由）                    |
+| `good-first-issue` | 适合新贡献者                            |
+
+### 优先级（可选，用于 bug/feature-request）
+
+| 标签                | 含义                                             |
+| ------------------- | ------------------------------------------------ |
+| `priority:critical` | 生产破坏、安全事件；24h 内响应                   |
+| `priority:high`     | 显著影响主要用户；1 周内处理                     |
+| `priority:medium`   | 影响部分用户或体验；按 sprint 排期                |
+| `priority:low`      | 外观/轻微改进；有空再说                          |
+
+### 模块/领域（自定义）
+
+根据项目结构给领域标签，例如 `area:cli`、`area:templates`、`area:skill-creator`。方便按模块聚合。
+
+### 状态标签
+
+| 标签                | 含义                                        |
+| ------------------- | ------------------------------------------- |
+| `needs-repro`       | 等复现步骤                                  |
+| `needs-design`      | 需要设计讨论再 coding                       |
+| `needs-review`      | PR 等评审                                   |
+| `blocked`           | 被其他 issue/上游依赖阻塞                   |
+| `stale`             | 长时间无活动                                |
+| `closed-stale`      | 因无活动被关闭                              |
+
+## Issue 分诊流程
+
+1. 读 title、body、comments，判断类型
+2. 搜重复：`gh issue list --search "关键词" --state all --limit 20`
+3. 打 **类型** 标签，必要时加 **优先级** 和 **领域**
+4. 根据缺失信息回复：
+   - bug 缺复现：问复现步骤、系统信息、复现率
+   - feature-request：问具体 use case，是否有 workaround
+   - question：直接回答或指向文档
+
+### 回复模板
+
+**要求复现**
+
+> Thanks for the report. Could you share a minimal reproduction? Please include:
+> - Command you ran and full output
+> - Node version (`node -v`) and OS
+> - Contents of relevant config files
+> Without this we can't investigate further.
+
+**标记重复**
+
+> This looks like a duplicate of #XXX. Closing here, please follow the original for updates. Thanks!
+
+**转为 discussion**
+
+> This is more of a usage question than a bug, moving to [Discussions](link) where the community can chime in.
+
+### 大批量分诊节奏
+
+每天或每两天扫一次 open issue：
+
+```bash
+# 没有 type 标签的都要处理
+gh issue list --state open \
+  --search "no:label" \
+  --limit 50
+```
+
+## PR 审查流程
+
+### 入场检查（收到 PR 后 24h 内）
+
+1. CI 是否全绿：`gh pr checks <N>`
+2. 是否可合并：`gh pr view <N> --json mergeable,mergeStateStatus`
+3. 是否有描述、是否关联 issue
+4. 是否来自新贡献者（给欢迎评论）
+
+### 评审维度（深度审查时）
+
+- **目的对齐**：PR 是否解决了声明的 issue
+- **实现**：是否符合项目约定（见 AGENTS.md / CONTRIBUTING.md）
+- **测试**：新功能/bug 修复是否带测试
+- **文档**：面向用户的变更是否更新了 README/docs
+- **兼容性**：是否有破坏性变更，是否在 PR 描述里标注
+
+### 合并决策
+
+CI 全绿 + 至少一位 maintainer approve + 无 `blocked`/`needs-design` 标签 → 可合并。
+
+```bash
+# Squash merge（默认策略）
+gh pr merge <N> --squash --delete-branch
+
+# Merge commit（保留完整历史）
+gh pr merge <N> --merge --delete-branch
+```
+
+## Stale 策略
+
+### 判断规则
+
+- **Issue**：14 天无活动 → 加 `stale` 并询问
+- **PR**：7 天无 review/comment → 主动询问是否继续
+- **Stale → Closed**：再 14 天无响应 → 关闭并加 `closed-stale`
+
+### 自动化（推荐）
+
+用 [`actions/stale`](https://github.com/actions/stale)：
+
+```yaml
+name: Mark Stale
+
+on:
+  schedule:
+    - cron: '30 1 * * *'
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/stale@v9
+        with:
+          days-before-issue-stale: 14
+          days-before-issue-close: 14
+          days-before-pr-stale: 7
+          days-before-pr-close: 14
+          stale-issue-label: 'stale'
+          stale-pr-label: 'stale'
+          close-issue-label: 'closed-stale'
+          close-pr-label: 'closed-stale'
+          stale-issue-message: >
+            此 issue 已 14 天无更新。如仍需关注请留言，否则 14 天后将自动关闭。
+          stale-pr-message: >
+            此 PR 已 7 天无更新。如仍在推进请留言，否则 14 天后将自动关闭。
+          exempt-issue-labels: 'pinned,priority:critical,priority:high'
+          exempt-pr-labels: 'pinned,work-in-progress'
+```
+
+### 手动查询
+
+```bash
+# 找超过 14 天未更新的 open issue
+gh issue list --state open \
+  --json number,title,updatedAt \
+  --jq '.[] | select(.updatedAt < "2026-04-26")' | head -20
+
+# 找超过 7 天未更新的 open PR
+gh pr list --state open \
+  --json number,title,updatedAt,author \
+  --jq '.[] | select(.updatedAt < "2026-05-03")'
+```
+
+## 社区 PR 特殊处理
+
+### 新贡献者检测
+
+看 PR 作者历史：
+
+```bash
+gh pr view <N> --json author,authorAssociation
+# authorAssociation: FIRST_TIME_CONTRIBUTOR / CONTRIBUTOR / MEMBER
+```
+
+首次贡献者给热情的欢迎评论，附：
+
+- CONTRIBUTING 链接
+- 本地跑测试的命令
+- 告知 review 时长预期
+
+### CLA / DCO
+
+若仓库要求 CLA 签署或 DCO signoff，PR 里会有 bot 检查。未签署的：
+
+> Thanks for the PR. Our CLA bot needs you to sign the agreement before we can merge. You should see a comment above with instructions.
+
+### 驳回时保持尊重
+
+即使方向不对也要说明清楚：
+
+> Thanks for taking the time on this. After discussing with the team, we've decided not to go this direction because [原因]. The alternative we're considering is [方案]. Closing this PR, but would love to hear your thoughts in [issue link].
+
+## 每周例行巡检
+
+一个典型的周一清单：
+
+```bash
+# 1. 未分诊的 issue
+gh issue list --state open --search "no:label" --limit 20
+
+# 2. 超过 7 天无 review 的 PR
+gh pr list --state open --json number,title,updatedAt \
+  --jq '.[] | select(.updatedAt < "YYYY-MM-DD")'
+
+# 3. 本周合并统计
+gh pr list --state merged --base main --search "merged:>YYYY-MM-DD"
+
+# 4. 关注 critical/high 标签的未解决 issue
+gh issue list --label "priority:critical,priority:high" --state open
+```

package/speculo/skills/github-npm-ops/references/package-json-checklist.md

@@ -0,0 +1,171 @@
+# package.json 发布前字段清单
+
+发布失败的一半原因都是 `package.json` 少字段或字段错位。按这张清单逐项确认。
+
+## 必填字段
+
+### name
+
+- 普通包：全局唯一，小写 + 连字符（如 `my-cli`）
+- Scoped 包：`@scope/name`，必须先在 npm 上拥有 scope
+- **首次发布前用 `npm view <name>` 查询是否被占用**；返回 404 才可用
+
+```bash
+npm view my-cli                 # 404 = 可用；有输出 = 已占用
+npm view @scope/my-cli          # 首次发布会 404，正常
+```
+
+### version
+
+- 遵循 SemVer（MAJOR.MINOR.PATCH）
+- 必须与要发布的 git tag 严格匹配：tag `v0.0.2` ↔ version `0.0.2`
+- npm **不允许重复发布同一个 version**，即使之前 unpublished 也不行（24h 内）
+
+### repository
+
+**npm provenance 强制要求这个字段**，缺失会报 `E422`。
+
+```json
+{
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/owner/my-cli"
+  }
+}
+```
+
+- `url` 必须指向实际托管 workflow 的 GitHub 仓库
+- 注意大小写：GitHub 虽不区分，但 provenance 验证严格匹配
+
+### license
+
+SPDX 标识符（如 `MIT`、`Apache-2.0`、`ISC`）。别写 `LICENSE.md` 或随意字符串。
+
+## CLI 包专用字段
+
+### bin
+
+命令入口。路径必须以 `./` 开头：
+
+```json
+{
+  "bin": {
+    "my-cli": "./dist/cli/index.js"
+  }
+}
+```
+
+入口文件必须：
+
+1. 有可执行权限（`chmod +x`，或通过 `scripts/inject-shebang.mjs` 注入 shebang）
+2. 首行是 `#!/usr/bin/env node`
+3. 是 ESM（`"type": "module"` 时）或 CJS，与 package 一致
+
+### files
+
+显式允许列表，避免把源码、测试、`.env` 发到 npm：
+
+```json
+{
+  "files": [
+    "dist",
+    "templates",
+    "!dist/**/*.test.js",
+    "!dist/**/__tests__",
+    "!dist/**/*.map"
+  ]
+}
+```
+
+- 不写 `files` 时，npm 走 `.gitignore` 加一堆默认规则，通常会漏发或误发
+- 发布前用 `npm pack --dry-run` 看看 tarball 实际内容
+
+## 推荐但可选字段
+
+### description / keywords
+
+影响 npm 搜索结果，写清楚。
+
+### homepage / bugs
+
+```json
+{
+  "homepage": "https://github.com/owner/my-cli#readme",
+  "bugs": {
+    "url": "https://github.com/owner/my-cli/issues"
+  }
+}
+```
+
+显示在 npm 包页面，方便用户找文档和报问题。
+
+### engines
+
+```json
+{
+  "engines": {
+    "node": ">=24.14.1"
+  }
+}
+```
+
+声明最低 Node 版本；npm 会在安装时提示（但不会阻止）。
+
+### type / exports
+
+ESM 包：
+
+```json
+{
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  }
+}
+```
+
+## scripts
+
+### prepublishOnly
+
+发布前的质量闸门。仅在 `npm publish` 前执行（`npm install` 不触发）：
+
+```json
+{
+  "scripts": {
+    "prepublishOnly": "pnpm check"
+  }
+}
+```
+
+`pnpm check` 通常是 `pnpm lint && pnpm test && pnpm build`。
+
+### 不要用的 scripts
+
+- `prepublish` — 已废弃，会在 `install` 时也触发，容易误伤
+- `prepare` — 在 `install` 时也跑，写构建命令会导致普通安装变慢
+
+## 发布前自检流程
+
+```bash
+# 1. 检查 name 可用（首次发布）
+npm view @scope/my-cli
+
+# 2. 版本一致性
+node -e "console.log(require('./package.json').version)"
+git tag --list 'v*' | sort -V | tail -3
+
+# 3. tarball 内容预览
+npm pack --dry-run
+
+# 4. 运行质量闸门
+pnpm check
+
+# 5. 预演发布（不会真的推送）
+npm publish --dry-run --access public --provenance
+```
+
+如果 5 个命令都正常，再执行真正的 `git tag && git push origin <tag>` 触发 CI 发布。

package/speculo/skills/github-npm-ops/references/preflight-checklist.md

@@ -0,0 +1,39 @@
+# Phase 0 — 前置检测完整清单
+
+> 本文件是 `npm-cicd-release` 命令 Phase 0 的「展开形态」。命令正文只列出五项核心前置；这里给出 11 项完整探测、失败信号与建议修复。
+> 全部探测都是**只读**的，不会修改任何文件。任一项不通过 → 命令终止，输出修复建议；不要尝试自动跳过。
+
+## 探测矩阵
+
+| # | 项 | 探测命令 | 通过判定 | 失败建议 |
+|---|----|---------|---------|---------|
+| 1 | 当前分支 | `git rev-parse --abbrev-ref HEAD` | 输出 = 仓库声明的发布分支（默认 `main`） | `git checkout main` 后重新触发；或显式声明本仓库的发布分支 |
+| 2 | 工作区干净 | `git status --porcelain` | 输出为空 | 先 stash / commit；不允许 `git stash` 后立刻发版（stash 内容易丢失） |
+| 3 | 远端可达 | `git ls-remote --exit-code origin` | 退出码 0 | 检查网络 / SSH key / `gh auth status` |
+| 4 | gh 已登录 | `gh auth status` | 含 `Logged in to github.com` | `gh auth login` |
+| 5 | gh 仓库权限 | `gh repo view --json viewerCanAdminister` | `viewerCanAdminister == true` 或至少 push 权限 | 联系仓库管理员；或 fork 后申请 PR 流程 |
+| 6 | Node 版本 | `node --version` | ≥ `package.json#engines.node` | `nvm use` / `fnm use` / 升级本机 Node |
+| 7 | 包管理器 | `pnpm --version` (或 `npm` / `yarn`) | 版本 ≥ 仓库 lockfile 隐含版本 | 安装匹配版本；不要随意切换包管理器 |
+| 8 | release.yml 存在 | `test -f .github/workflows/release.yml` | 文件存在 | 转 `github-ops` skill 的 `references/workflow-yaml-reference.md` 先落该文件 |
+| 9 | release.yml 形态 | 见 [publish-detection.md](publish-detection.md) | 输出 `PUBLISH_TO_NPM=true` 或 `false` | 见 publish-detection 文档的判定矩阵 |
+| 10 | docs-sync state | `test -f .speculo/dev/docs-sync-state.json && jq . .speculo/dev/docs-sync-state.json` | 解析成功且 `last_sync_sha != null` | 不存在 → 走 `dev/D-docs-sync` workflow 的「首次运行」分支；存在但损坏 → 修复 JSON |
+| 11 | tag 名称冲突 | `git rev-parse vX.Y.Z 2>/dev/null` | 退出码非 0（tag 不存在） | 同 tag 已存在：先确认是否真的失败需要重发；若是则 `git tag -d` + `git push origin :refs/tags/vX.Y.Z`，否则 bump 到下一版本 |
+
+## 失败处理总策略
+
+- 探测项 1–3、6–7：本机环境问题，提示用户人工修复后重跑命令
+- 探测项 4–5：GitHub 权限问题，给出对应的 `gh` 命令
+- 探测项 8：基础设施缺失，明确转交 `github-ops` skill 而不是在本命令里现写 release.yml
+- 探测项 9：影响 Phase 5 的分支选择，**不阻塞**命令执行（仅决定后续是否做 npm view 校验）
+- 探测项 10：影响 Phase 2 是否进入 docs-sync 主流程
+- 探测项 11：直接关系到能否打 tag，必须在 Phase 0 阶段就排除
+
+## 与三个 skill 的边界
+
+Phase 0 只做**只读探测**，不调用任何 skill 的 SOP：
+
+- `git-commit-template` skill 只在 Phase 1 被引用
+- `docs-sync` skill 只在 Phase 2 / Phase 6 被引用
+- `github-ops` skill 在 Phase 3 / 4 / 5 被引用
+
+如果 Phase 0 嗅探到的状态需要某个 skill 的修复 SOP（如 release.yml 缺失），明确转交，不要在本命令内复刻 skill 的内容。

package/speculo/skills/github-npm-ops/references/publish-detection.md

@@ -0,0 +1,68 @@
+# Release.yml 是否含 npm publish 的判定脚本
+
+> 用于决定 Phase 5 是否做 npm 端校验。命令正文只展示了核心 grep；这里给出完整模式集合、第三方 action 清单与误判排除策略。
+
+## 判定输出
+
+```bash
+RELEASE_YML=".github/workflows/release.yml"
+
+if [ ! -f "$RELEASE_YML" ]; then
+  echo "RELEASE_YML_MISSING=true"
+  exit 0
+fi
+
+# 主判定：是否含 npm publish 步骤
+if grep -Eq 'npm[[:space:]]+publish|run:[[:space:]]*pnpm[[:space:]]+publish|run:[[:space:]]*yarn[[:space:]]+publish|JS-DevTools/npm-publish|cycjimmy/semantic-release-action|changesets/action' "$RELEASE_YML"; then
+  echo "PUBLISH_TO_NPM=true"
+else
+  echo "PUBLISH_TO_NPM=false"
+fi
+```
+
+## 模式集合
+
+`PUBLISH_TO_NPM=true` 命中下列任一行时为真：
+
+| 模式 | 形态 | 说明 |
+|------|------|------|
+| `npm publish` | `run: npm publish --provenance --access public` | 官方 npm CLI |
+| `pnpm publish` | `run: pnpm publish --no-git-checks` | pnpm 包管理器 |
+| `yarn publish` | `run: yarn publish --new-version $VERSION` | 旧 yarn / berry |
+| `JS-DevTools/npm-publish@vN` | `uses: JS-DevTools/npm-publish@v3` | 第三方封装 action |
+| `cycjimmy/semantic-release-action@vN` | `uses: cycjimmy/semantic-release-action@v4` | semantic-release 流水线 |
+| `changesets/action@vN` | `uses: changesets/action@v1` 且配置 `publish:` 输入 | Changesets 风格的多包发布 |
+
+## 误判排除
+
+下列形态**不应**触发 `PUBLISH_TO_NPM=true`：
+
+| 形态 | 是否触发 | 原因 |
+|------|---------|------|
+| `# npm publish` 注释行 | ❌ | grep `-E` 默认匹配整行；如需更严格可加 `^[^#]*` 锚定 |
+| `description: 'Run npm publish ...'` | ⚠️ 可能误命中 | 收紧 grep 为 `run:[[:space:]]*npm[[:space:]]+publish` 即可避免 |
+| `npm publish --dry-run` | ✅ 仍命中 | 视作真发布意图；如需排除，可在判定后追加 `--dry-run` 检查并手动降级 |
+| `npm pack` | ❌ | `pack` 不是 `publish` |
+| 仅 `softprops/action-gh-release` | ❌ | 这是 GitHub Release 创建器，不是 npm publish |
+
+## 收紧版（推荐用于精确判定）
+
+```bash
+grep -E '^\s*(run:\s*(npm|pnpm|yarn)\s+publish|uses:\s*(JS-DevTools/npm-publish|cycjimmy/semantic-release-action|changesets/action))\b' "$RELEASE_YML"
+```
+
+> 如果仓库使用了非主流的发布方式（如自写 shell 脚本里调用 `npm publish`），grep 仍可能漏判。
+> 漏判后果：Phase 5 跳过 `npm view` 校验。这是**安全侧**漏判（不会误报"未发布"），但用户应在该仓库的 README 或 SKILL 注释里明确发布方式，避免歧义。
+
+## 多 workflow 文件的处理
+
+若仓库有多个 release 相关 workflow（如 `release.yml` + `publish-canary.yml`），默认只看 `release.yml`。
+如需扩展，在调用方 workflow 或项目上下文中声明 `releaseWorkflowPaths: [...]`，执行时按该列表逐个判定。
+
+## 与 Phase 5 的衔接
+
+| 嗅探结果 | Phase 5 行为 |
+|---------|-------------|
+| `PUBLISH_TO_NPM=true` | 跑 `gh release view` + `gh run` + `npm view` 三端 |
+| `PUBLISH_TO_NPM=false` | 仅跑 `gh release view` + `gh run` 两端，并向用户输出「本仓库 release.yml 不含 npm publish 步骤」提示 |
+| `RELEASE_YML_MISSING=true` | Phase 0 直接终止，不进入后续 phase |