--- name: update-nu description: 根据最新 Nushell 发布说明、本地 nu CLI 实测和源码更新 nushell-pro 技能、迁移指南与回归测试；用于 Nushell 发版后的技能维护。 --- # 更新 nushell-pro 先建立版本证据，再更新指导。读取目标仓库的 `SKILL.md`（nushell-pro） 及相关 reference，遵循其解析检查、测试隔离和版本兼容要求。 产物写入 nushell-pro 仓库；不修改用户的 Nu 配置、不安装或升级二进制。 ## 1. 定位素材并同步 - 先确认目标是 nushell-pro 源码仓库（含根 `SKILL.md`、`references/`、 `tests/`），不要因技能从全局安装目录加载而修改安装副本。记录目标绝对路径 和 `git status --short`，保留用户已有修改。 - 从环境变量或目标仓库 `.env` 读取 `NU_DOC_REPO`、`NU_SOURCE_REPO`。 环境变量优先；只解析这两个键的单行字符串，允许单/双引号，按字面路径处理。 不 `source`/执行 `.env`，不打印其余内容。相对路径以目标仓库为基准； 空值、重复键或无效仓库路径不能静默回退。缺少路径时请用户提供。 - 对两个仓库分别检查路径、Git 根目录、分支和工作区；执行 `git -C fetch origin main`，成功后立即以 `FETCH_HEAD^{commit}` 固定该仓库本轮的上游 SHA，再比较 `HEAD...`（不依赖远端跟踪分支是否更新）。 干净的 main 分支落后且可快进时执行 `git -C pull --ff-only origin main`。已同步则跳过。 有本地修改、分叉或非 main 分支时不自动切分支、stash、reset 或合并； 说明阻碍，但可从已固定的上游 SHA 只读分析。即使 HEAD 包含上游，额外的 本地提交也不是正式发布证据。后续日志、目录枚举和文件读取统一使用该 SHA： `git log -- ...`、`git ls-tree -r --name-only `、 `git show :`。只有工作区干净且 HEAD 等于该 SHA 时才直接读文件。 网络失败时不能宣称素材已最新，应明确无法确认并停止“最新版本”更新。 - 从 `git log -n 80 --name-status -- blog` 找近期 release note， 再核对同一提交树中 `blog/*nushell_v*.md` 的标题、正文版本与提交历史。 比较语义版本，不按文件名日期或最后一次编辑时间判定最新版本； 区分正式发布说明与预备稿。必要时扩大历史范围并核对发布状态。 用户给的路径可能被改名：按版本和 rename 历史找回，并报告实际路径。 - 博客不是完整的正式版本清单。用官方 GitHub Releases（如 `gh release list --repo nushell/nushell --exclude-drafts --exclude-pre-releases` 或官方 API）确认最新稳定版本，必要时翻页，不按发布时间替代 SemVer 排序。 补丁版可能只有 release body：分别记录“最新正式目标版本”和“博客基线版本”， 阅读两者及其间补丁说明。草稿/预发布博客不提高版本门槛；无法确认正式状态则 停止最新版本更新，不能仅凭文件名、源码版本或未核实的 tag 推断已经发布。 ## 2. 二进制版本门禁（写入更新之前） - 执行 `nu --version` 并记录 `version` 的版本、`commit_hash`、平台和构建信息。 固定实际可执行文件绝对路径；门禁、parse check、运行测试均使用该路径， Nu 测试的子进程使用 `$nu.current-exe`，避免 PATH 中的另一个版本混入。 隔离 PATH 时仍保留终止进程所需的系统工具，不能把“找不到其他 nu”与 “删除全部 PATH”混为一谈；先确认取消机制可用，再启动挂起复现。 将实际版本与已确认的最新正式目标版本比较，不要求等于博客的基线版本。 - 本地版本低于发布版本：立即停止更新 nushell-pro，提示用户先升级本地 Nu 并重新运行。不得绕过门禁或把源码 main 的版本当成本机版本。 - 本地是预发布版或高于目标版：不能将其结果标为目标版实测；先取得匹配的 正式版二进制再继续；若只是高于博客基线，先核实是否正式补丁版，不能直接 要求降级。禁止用字符串字典序比较版本；低版本 Nu 可能没有 `into semver`， 门禁不能依赖尚未确认存在的新 Nu 语法。 - 记录 docs/source SHA；源码 main 可能已进入下一开发版，行为冲突时优先 查目标 release tag 的实现和测试。源代码推断与 CLI 实测分别标注。 本地没有 release tag 时先查询远端标签；若二进制提供 commit_hash， 可直接以该提交核对源码，记录依据，不能臆造标签名或把 main 当发布标签。 ## 3. 分析与实操 - 完整阅读发布说明的 breaking changes、additions、fixes、performance。 建立简洁的“变更 → 影响 → 验证 → 落点”记录，不照抄完整 changelog。 - 优先覆盖破坏性变更、常用脚本惯用法、静默数据丢失、错误传播、安全边界。 同时 `rg` 搜索旧技能中的缺陷、限制和 workaround，主动复测可能已修复项。 - 用 `nu --no-config-file` 和固定程序文本验证；外部输入通过 argv/env/文件传入， 不拼成 `nu -c` 程序。新 `.nu` 先 `nu-check --debug` 再执行。 有副作用的测试只使用自建 `mktemp --directory`，清理仅限自建资源。 - 测试断言具体值、类型、错误和退出状态；流式错误要消费到终点才算验证。 死锁/长驻进程复现放到隔离子进程，设置超时、终止与清理验收；有限输入 不代表有限运行时间。禁止依赖上游输出数量来保证不会挂死。 补全通过 `commandline complete` 驱动引擎，不能只直接调用补全函数。 TUI 优先 headless 接口；交互、平台、插件、性能未实测的部分明确标注。 - 文档、help、实测不一致时缩小复现，再查 release 源码/测试。 不因为相邻功能修复就推断整个类别都已修复。 对照发布说明的示例记录实测字段差异；可选字段不照抄成固定 schema。 “破坏性变更”可能仍有弃用兼容桥：分别验证新接口和旧签名，不把文档的 全称断言直接当成事实，也不因为旧写法暂时可用就省略迁移建议。 新增 row-condition 支持时复测旧闭包与尾随 flags 的组合，避免只验证新语法。 ## 4. 更新与迁移归档 - 新增 `references/nu-.-migration.md`，包含版本边界、 迁移示例、审查要点、验证命令和证据来源；补丁版本更新同一指南。 - 高频且跨任务的指导同步到主入口和对应主题 reference；历史指南保留 当时事实，加上新版本修复说明/链接，避免把旧缺陷变成永久规则。 - 添加有价值的版本回归测试，更新旧测试的版本限定；不删除仍适用于旧版本 的断言，不通过无条件 skip 掩盖回归。保留历史证据的实测版本/修订号， 新增本轮验证记录，不覆盖成仿佛旧复现也是新版本的结果。兼容性只在实际跑过 对应二进制时宣称已验证；仅当前版本通过不能证明旧版本仍通过。 - 主 `SKILL.md` 只列最新三个 migration（按数字版本排序）。超过三个时将 更早指南移动到 `references/archive/`，保留内容；检查并修正所有入链、 被移动文档内部的相对链接及 README 结构。主入口提示按需查阅归档目录。 少于或等于三个时不提前归档。归档目录可用简短索引说明保留策略。 先列移动映射；目标已存在且内容不同就停止该移动，不能覆盖。重复运行应只 更新现有指南、不重复归档；同时更新归档索引中的版本清单和“尚无归档”说明。 存在冲突时记录路径并报告归档未完成，不得将部分成功表述为全部完成。 ## 5. 验证、反馈与技能迭代 - 运行新增/受影响脚本的解析和行为检查，再运行仓库现有 smoke suites。 旧缺陷断言失败时先区分上游修复、测试问题和新回归，再修改预期。 - 检查 Markdown 本地链接、最近三个迁移入口、`git diff --check` 及完整 diff。 包含新建未跟踪文件；入口数量为 `min(3, 现有版本指南数)`，并核对版本内容， 不只数三个链接。下次修改本流程时按 [场景验收](references/validation.md) 检查门禁、证据来源和归档的行为。 新建/修改技能后运行可用的 skill-creator `quick_validate.py`（Python 用 uv）。 - 记录可复现命令、实际版本/SHA、结果及未验证范围。最终简述技能与指南路径、 验证结果、使用 nushell-pro 过程中发现的问题及修正情况。 - 将本轮遇到的实际流程缺陷补回本技能；规则应能服务后续发版，避免不断堆叠 只对某次发版有用的细节。不要自动提交、发布或在 GitHub 评论。