【免费下载链接】NativeScript⚡ Write Native with TypeScript ✨ Best of all worlds (TypeScript, Swift, Objective C, Kotlin, Java, Dart). Use what you love ❤️ Angular, React, Solid, Svelte, Vue with: iOS (UIKit, SwiftUI), Android (View, Jetpack Compose), Flutter and you name it compatible.项目地址https://gitcode.com/gh_mirrors/na/NativeScript点击查看免费下载导读本文围绕 NativeScript 官方仓库内置的 Agent 技能Skill文档.agent/skills/fix/SKILL.md展开完整还原其定义的从 bug 报告到合并 PR六阶段调试工作流获取问题Get the bug→ 追踪代码路径Trace the code path→ 定位根因Root cause→ 实施修复Fix→ 验证Verify→ 收尾Finish。无论你是人类开发者还是使用 AI 编码助手的 Agent本文都会教你如何结合仓库中packages/core平台拆分源码、同目录.spec.ts测试与apps/automated真机测试体系系统化地修复一个真实的跨平台 bug并让修复通过回归测试与规范审查。1. 工作流概览一份为 Agent 设计的 Bug 修复协议.agent/skills/fix/SKILL.md是 NativeScript 仓库为 AI 编码助手设计的可执行技能文件。文件开头的 YAML front-matter 定义了它的元数据--- name: fix description: Debug and fix a bug end-to-end (GitHub issue or free-text report → trace → root cause → fix → test → PR). Use anytime you need to fix broken, throwing, or misbehaving code in this workspace. argument-hint: [issue-number-or-description] ---其中description明确了该技能的适用范围任何出现崩溃、抛错或行为异常的代码argument-hint说明了它的输入参数一个 GitHub Issue 编号或一段对问题的文字描述。整个工作流被划分为六个阶段每个阶段有明确交付物阶段目标关键产出Phase 1: Get the bug拿到可复现的问题描述复现步骤、环境信息、堆栈/报错Phase 2: Trace the code path从入口追到报错点引用了file:line的证据链Phase 3: Root cause证实根因而非猜测一个失败的 spec回归测试的雏形Phase 4: Fix最小改动修复根因平台文件对齐的补丁 .d.ts更新Phase 5: Verify证明修复有效全量测试通过 真机用例清单Phase 6: Finish收尾交付格式化、规范提交、PR工作流还强制要求动手改代码前必须先阅读它引用的四份参考文档见下文第 6 节其中packages/core相关改动还要遵守CorePlatformModules.md的平台拆分约定。2. 阶段一获取 Bug —— 把模糊报告变成可执行的起点本阶段的目标是把问题描述转化为可定位的文件线索。文档给出了两条输入路径有 GitHub Issue 编号直接通过 GitHub CLI 拉取完整信息gh issue view number --json title,body,labels,comments没有编号自由文本报告直接从用户提供的描述中收集信息。无论哪条路径都要从报告中提取三样东西它们直接决定从哪个文件开始读复现步骤reproduction steps最小触发路径例如创建 Page 后调用page.actionBar抛错。环境信息platform, versionsAndroid/iOS/visionOS、NativeScript 与运行时版本。这一步极其重要——NativeScript 是典型的平台拆分架构下文第 3 节详述只在 Android 上复现往往意味着双平台实现已经分叉。堆栈与报错stack trace / error message堆栈里出现的模块路径几乎直接指向要读的第一个文件。这一阶段不需要任何代码改动产出是一份结构化的问题简报。3. 阶段二追踪代码路径 —— 平台拆分的双轨阅读法NativeScript 的packages/core是所有核心模块的所在地它采用按文件名后缀进行平台拆分的架构这是整个追踪阶段必须理解的前提。参考文档 CorePlatformModules.md 解释了其文件结构foo.ios.ts/foo.android.ts—— 平台实现二者必须导出完全相同的公开 APIfoo-common.ts—— 共享逻辑平台文件导入并扩展它foo.d.ts—— 手工编写的合并公开 API 声明不是自动生成的。构建时由打包器bundler根据目标平台解析后缀因此foo.ios.ts与foo.android.ts是同一模块的两种实现。仓库中随处可见这种结构例如 application/index.android.ts、application/index.ios.ts 与 application/application-common.ts 三件套text/index.android.ts 与 text/index.ios.ts 亦然。追踪时的核心纪律文档原话Forpackages/core, read BOTH platform files — a bug on one platform often means the implementations diverged.即两个平台文件必须都读。一个平台上的 bug 往往意味着实现已经分叉比如一方忘了同步行为、或平台 API 用法不一致。追踪方法是从入口文件沿着调用链走到报错点并对链条上的每个环节记录证据。文档还特别强调一条诚实性红线Keep claims honest: distinguish what you proved by reading code (quotefile:line) from what you suspect. Do not present a hunch as the root cause.即区分读代码证实的与猜测的凡是结论必须能引用文件:行号绝不允许把直觉当成根因。4. 阶段三定位根因 —— 用失败的测试钉死机制本阶段的工作是证实而非猜测先确认机制再动手修只有当逻辑可以被单元测试覆盖时先写一个复现该 bug 的失败 specfailing spec。这个测试有双重身份——它既是根因成立的证明也是日后防止回归的守卫。在包内全面搜索同类模式文档原话Grep for the same pattern elsewhere in the package; a bug rarely lives in only one place同一个 bug 极少只存在于一处。用正则搜索整个包列出每一处相同写法为阶段四的全面修复提供清单。NativeScript 的单元测试是与源码同目录存放的*.spec.ts文件例如 xml/index.spec.ts 就紧挨着 xml/index.ts测试框架为 Vitest通过 Nx 按包运行。一个典型的失败测试长这样摘自 WritingUnitTests.md 的示例import { Observable } from .; describe(Observable, () { it(notifies a listener once, () { const observable new Observable(); let callCount 0; observable.once(test, () callCount); observable.notify({ eventName: test, object: observable }); observable.notify({ eventName: test, object: observable }); expect(callCount).toBe(1); }); });测试环境要点单元测试运行在 Node 而非设备上vitest.setup.ts 会 stub 掉__IOS__、__ANDROID__、__UNIT_TEST__等平台全局变量以及最小化的NSObject风格 mock让 core 模块能够加载但真实 iOS/Android API 不可用如果测试需要更多原生能力需要在该 setup 文件中扩展 mock。因此凡是依赖真实原生运行时才能观察到的行为不属于单元测试的范畴而应放入 e2e 套件见第 5 节。5. 阶段四与阶段五最小修复与双轨验证修复最小改动 平台对齐阶段四的修复原则非常明确Apply the smallest change that fixes the root cause, not the symptom.即修复根因而非症状且改动必须最小。同时要落实阶段三全面搜索的成果——修复清单上的每一处实例都要一并处理Fix all instances found in the spread check。两条硬性规则必须遵守平台对等parity.ios.ts与.android.ts必须保持同步绝不允许只改一边导致实现分叉API 变更联动声明文件如果修复改变了公开 API必须在同一改动中更新相邻的.d.ts因为foo.d.ts是手工编写、非自动生成的且它才是真正交付给消费者的类型声明JSDoc 也应写在.d.ts中。此外CorePlatformModules.md 还有三条容易被忽略但同样重要的约定共享代码-common.ts等中绝不 import.ios.ts/.android.ts文件平台选择完全交给打包器visionOS 复用 iOS 实现不存在.visionos.ts后缀共享代码内需要运行时平台判断时使用编译期全局变量__ANDROID__、__IOS__、__APPLE__、__VISIONOS__声明于 global-types.d.ts被守卫的分支会在其他平台的构建中被剔除因此平台 API 的访问必须放在守卫内原生类型android.*、UIKit、NS*只能在对应的平台文件中引用。验证单元测试 真机测试的分工阶段五的验证同样遵循双轨分工单元测试轨道阶段三写的失败 spec 必须转绿同时整个包的目标必须全量通过npx nx run core:test常用变体还包括详见 WritingUnitTests.md# 监听模式 npx nx run core:test --watch # 按 describe/it 名称隔离测试 npx nx run core:test -t XmlParser真机测试轨道只在真机/模拟器上才能观察到的行为归属于apps/automated应用其测试源码位于 apps/automated/src覆盖 accessibility、animation-frame、application、ui 等大量目录。这类用例要在 PR 描述中标注为手工测试场景。运行 e2e 套件的命令摘自 DevelopmentWorkflow.mdnpx nx run apps-automated:ios # 或 npx nx run apps-automated:android6. 阶段六收尾 —— 格式、提交与 PR阶段六有三个动作每个都与仓库规范一一对应格式化npx nx format:write提交遵循 conventional commit 格式例如fix(core): subject。CONTRIBUTING.md 对提交消息有完整约定格式为type(scope): subjectheader 不超过 100 字符subject 用祈使句、现在时、首字母小写、结尾无句号type 必须是fix、feat、refactor、test、docs等白名单之一scope 通常是被影响组件如ios/application、action-bar、animationsbody 说明动机并与旧行为对比footer 放BREAKING CHANGE:迁移说明或Closes #issue引用。开 PR通过gh创建必须遵循仓库的 PULL_REQUEST_TEMPLATE.md——模板要求 PR 标题遵循提交指南、关联对应 IssueFixes/Implements/Closes #[Issue Number]、签署 CLA、并包含回归测试。PR 模板的 Checklist 中还引用了完整的贡献指南CONTRIBUTING.md其中关于测试的要求是所有 Android 与 iOS 单元测试保持绿色见 DevelopmentWorkflow.md 的Running unit tests一节并为修复或新特性编写单元测试。这意味着阶段五的验证并不是一次性的而是 PR 审查的门槛。7. 四条先决约定动手前必读的参考文档工作流在正文之前就强调Conventions this workflow depends on (read the ones your change touches before writing code)——本技能依赖以下约定动手写代码前必须阅读与你改动相关的部分参考文档适用场景核心内容CorePlatformModules.md改动packages/core平台拆分文件、手工.d.ts平台拆分文件结构、.d.ts手工声明规则、编译期平台守卫CodeComments.md所有 TypeScript 改动JSDoc 只用于公开导出的函数/接口/类param/returns标签不带类型内联注释仅用于意外的业务逻辑或 workaround最长 12 个单词且必须放在代码上一行禁止解释语言特性、禁止保留死代码/注释块、禁止文件横幅与作者/时间戳WritingUnitTests.md测试编写Vitest 标准 APIdescribe/it/expect/viglobals 已启用测试运行于 Node 而非设备e2e 行为归apps/automatedCONTRIBUTING.md提交与 PRconventional commit 格式、type/scope/subject 规范、BREAKING CHANGE 迁移说明、PR 流程其中CodeComments.md的约束对 AI 生成的代码尤其重要它旨在保持仓库注释的稀疏且高信息量防止 Agent 生成大量解释性废话。例如JSDoc 应写成/** * Concise single-sentence description. * param name Description without type. * returns Description without type. */而不是带类型标注的param {number} id形式。8. 工作流落地示例一次平台分叉型 bug 的完整推演将六个阶段串联起来一个典型的修复过程如下以packages/core内、仅 Android 复现的 bug 为例Phase 1gh issue view 1234 --json title,body,labels,comments提取出Android 上Foo组件行为异常iOS 正常的复现描述。Phase 2同时打开 foo.android.ts 与 foo.ios.ts 对照阅读顺着调用链追踪到报错点用file:line记录下Android 实现在某处多调用了一次原生 API的证据。Phase 3在foo模块目录下写一个复现该差异的失败 spec随后在包内 grep 相同模式确认是否还有其他文件存在同样写法。Phase 4对根因做最小修改同步修改.ios.ts/.android.ts保持对等若公开 API 签名变化同改动内更新相邻.d.ts中的声明与 JSDoc。Phase 5运行npx nx run core:test使失败 spec 转绿并保证全量通过把只能在真机上验证的行为如真实设备上的动画表现记录为 PR 的手工测试场景。Phase 6npx nx format:write格式化以fix(core): subject提交按 PULL_REQUEST_TEMPLATE.md 开 PR引用 Issue 并附上回归测试。整个推演严格对应文档六个阶段的产出物问题简报 → 证据链 → 失败 spec → 对齐补丁 → 绿色测试 → 规范 PR。9. 与仓库其他 Agent 技能的关系.agent/skills目录下并非只有fix一个技能与它并列的还有.agent/skills/feat/SKILL.md—— 新功能开发工作流.agent/skills/refactor/SKILL.md—— 重构工作流.agent/skills/unit-testing/SKILL.md—— 单元测试专项技能且只依赖 WritingUnitTests.md 一份参考。这四个技能共享同一套references/参考文档fix与feat、refactor引用的四份参考完全一致。可以推断仓库希望通过一套统一的编码、测试与提交约定让不同任务的 Agent 行为保持一致——理解这一点有助于你在处理混合任务例如修 bug 顺便补测试时复用fix工作流与unit-testing技能的重叠部分而不必重复阅读约定。结语.agent/skills/fix/SKILL.md看似只是一份短小的 Agent 提示词实际上它浓缩了 NativeScript 仓库多年沉淀的工程纪律平台拆分的双轨阅读、以失败测试钉死根因、最小修复与平台对等、单元测试与真机测试的分工、以及 conventional commit 与 PR 模板的收尾规范。对开发者而言这套六阶段流程本身就是一份可复用的跨平台 bug 排查手册对 Agent 而言它把模糊的修个 bug指令分解成了每一步都有明确输入、明确产出、可被审查的工程流水线。赞分享【免费下载链接】NativeScript⚡ Write Native with TypeScript ✨ Best of all worlds (TypeScript, Swift, Objective C, Kotlin, Java, Dart). Use what you love ❤️ Angular, React, Solid, Svelte, Vue with: iOS (UIKit, SwiftUI), Android (View, Jetpack Compose), Flutter and you name it compatible.项目地址https://gitcode.com/gh_mirrors/na/NativeScript点击查看免费下载相关推荐Voyager 仓库 issue-review Skill 实战指南从 Issue 调查到修复落地的完整工作流Voyager 仓库 issue review Skill 实战指南从 Issue 调查到修复落地的完整工作流 导读 本文系统讲解 Voyager 仓库内置的AI 应用前端AI Agent 端到端修复 Linear Issue 工作流unkey 仓库的自动化实践指南AI Agent 端到端修复 Linear Issue 工作流unkey 仓库的自动化实践指南 本文档解析 unkey 仓库中定义的 AI Agent 工作流后端API网关认证鉴权Exposed 项目 Bug 修复端到端工作流从 Issue 解析、失败复现测试到 PR 合并的完整实战指南Exposed 项目 Bug 修复端到端工作流从 Issue 解析、失败复现测试到 PR 合并的完整实战指南 本文基于 Exposed 仓库内建的 fix bORM后端数据存储上一篇nlohmann/json终极指南3分钟快速上手现代C JSON解析下一篇UserLAnd未来展望容器技术演进与移动端Linux发展趋势创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考