RuView 移动开发代理规范：为 Claude Code 编写一个可自主工作的 React Native 开发 Agent

本篇技术文章以 RuView 仓库中的 .claude/agents/specialized/mobile/spec-mobile-react-native.md 为骨架，完整拆解一个面向 React Native / Expo 移动应用开发的专用 Agent 规范：从 YAML 前置元数据（触发器、工具权限、路径约束、行为策略、生命周期钩子）到正文中的组件编写范式与平台差异化注意事项。结合仓库中真实存在的 ui/mobile/ Expo 应用源码，读者可以掌握“如何定义一个受约束、可委派、可审计的移动开发 Agent”，以及该 Agent 在 RuView 这类跨端感知平台上实际服务的项目形态与协作链路。

1. 规范文件的位置与定位

RuView 是一个“无摄像头 RF 感知”平台：核心是 Rust 工作区 v2/crates/、ESP32 固件 firmware/ 以及面向桌面浏览器的 ui/。而在 ui/mobile/ 下，仓库维护着一个基于 Expo / React Native 的跨平台移动应用（见 ui/mobile/README.md 与 ADR-034），提供 Live（3D 高斯泼溅）、Vitals（呼吸/心率仪表）、Zones（楼层占用）、MAT（灾害响应）、Settings 五个标签页。

.claude/agents/ 目录是仓库为 Claude Code 配置的 Agent 体系，按职责分层：core/（coder、planner、tester 等通用角色）、analysis/、github/、swarm/、templates/，以及 specialized/ 下的领域专家。specialized/mobile/ 目录中目前只有一个文件：

• spec-mobile-react-native.md —— 即 mobile-dev Agent 的完整规范。

整个文件由两部分构成：YAML 前置元数据（第 1～141 行，声明 Agent 的身份、触发条件、权限预算、约束、行为策略、集成关系与生命周期钩子）和 Markdown 正文（第 143 行起，作为系统提示词注入的开发者角色设定：职责、最佳实践、组件代码范式、平台差异注意事项）。下面按“元数据 → 钩子 → 正文 → 与真实项目对照”的顺序逐段解析。

2. 身份与元数据：这个 Agent 是谁

文件开头声明了 Agent 的基本身份：

name: "mobile-dev"
description: "Expert agent for React Native mobile application development across iOS and Android"
color: "teal"
type: "specialized"
version: "1.0.0"
created: "2025-07-25"
author: "Claude Code"

metadata:
  specialization: "React Native, mobile UI/UX, native modules, cross-platform development"
  complexity: "complex"
  autonomous: true

几个关键字段的含义：

字段	取值	作用
type	specialized	表明它是领域专家型 Agent，与 core/ 下的通用 coder/tester 区分
metadata.complexity	complex	任务复杂度评级，供上层调度器判断是否值得分配给它
metadata.autonomous	true	允许自主执行（在能力边界内连续读写文件、跑命令，而无需逐条确认）
specialization	React Native / native modules / cross-platform	与 triggers 一起构成路由匹配的语义描述

3. 触发系统：什么样的任务会路由给 mobile-dev

triggers 块定义了四类匹配信号，任何一类命中即可将该 Agent 纳入候选：

triggers:
  keywords:
    - "react native"
    - "mobile app"
    - "ios app"
    - "android app"
    - "expo"
    - "native module"
  file_patterns:
    - "**/*.jsx"
    - "**/*.tsx"
    - "**/App.js"
    - "**/ios/**/*.m"
    - "**/android/**/*.java"
    - "app.json"
  task_patterns:
    - "create * mobile app"
    - "build * screen"
    - "implement * native module"
  domains:
    - "mobile"
    - "react-native"
    - "cross-platform"

• keywords（关键词）：命中用户请求文本，覆盖 “react native”“expo”“native module” 等高频术语；
• file_patterns（文件模式）：glob 匹配工作区文件，.tsx/.jsx、App.js、app.json（Expo 项目标志文件），以及原生目录 ios/**/*.m（Objective-C）与 android/**/*.java。这一组模式恰好对应移动工程“JS 层 + 双端原生层”的典型布局；
• task_patterns（任务模板）：模糊任务匹配，如 “create * mobile app”“build * screen”“implement * native module”；
• domains（领域标签）：mobile、react-native、cross-platform，用于结构化领域归类。

从源码结构看，file_patterns 与 allowed_file_types（见下节）共同划定了该 Agent 的“可见世界”：JavaScript/TypeScript 组件、原生模块源文件与配置文件。

4. 能力边界：工具白名单与执行预算

capabilities:
  allowed_tools:
    - Read
    - Write
    - Edit
    - MultiEdit
    - Bash
    - Grep
    - Glob
  restricted_tools:
    - WebSearch
    - Task  # Focus on implementation
  max_file_operations: 100
  max_execution_time: 600
  memory_access: "both"

这里体现了一个“重实现、轻检索”的设计取向：

1. 工具白名单：Read/Write/Edit/MultiEdit 覆盖完整读写与批量编辑能力，Bash 允许执行构建、依赖安装、测试命令，Grep/Glob 支撑代码检索。白名单之外的一切实体一律不可用；
2. 受限工具：WebSearch 与 Task（派生子任务）被显式限制，注释直接写明理由 —— # Focus on implementation。即该 Agent 应基于本地仓库证据实现功能，而不是上网搜资料或再分叉子任务；
3. 执行预算：单次运行最多 100 次文件操作、600 秒墙钟时间。这是一个硬上限，防止无限循环的编辑-重试；
4. memory_access: "both"：允许同时读/写 Agent 记忆层，使它在多次会话中沉淀对项目的理解。

5. 路径与文件类型约束：把改动圈在工程边界内

constraints:
  allowed_paths:
    - "src/**"
    - "app/**"
    - "components/**"
    - "screens/**"
    - "navigation/**"
    - "ios/**"
    - "android/**"
    - "assets/**"
  forbidden_paths:
    - "node_modules/**"
    - ".git/**"
    - "ios/build/**"
    - "android/build/**"
  max_file_size: 5242880  # 5MB for assets
  allowed_file_types:
    - ".js"
    - ".jsx"
    - ".ts"
    - ".tsx"
    - ".json"
    - ".m"
    - ".h"
    - ".java"
    - ".kt"

• allowed_paths 是白名单：JS/TS 代码目录（src、components、screens、navigation、app）、双端原生目录（ios/**、android/**）与静态资源 assets/**。对照仓库中真实的移动工程，ui/mobile/ 的 src/ 下正是 components/、screens/、navigation/、services/、stores/ 等目录，入口为 ui/mobile/App.tsx，与白名单模式吻合；
• forbidden_paths 排除依赖目录 node_modules/、版本库 .git/ 以及双端构建产物 ios/build/、android/build/——这三者都是体积巨大且应由构建系统管理的目录，Agent 写入它们毫无意义且危险；
• max_file_size: 5242880（5 MB）：注释标明这是为 assets 场景设置的单文件上限；
• allowed_file_types 列出 9 种扩展名，覆盖 JS/TS 层（.js .jsx .ts .tsx .json）与原生层（iOS 的 .m .h、Android 的 .java .kt），与 file_patterns 形成闭环。

这种“白名单 + 黑名单 + 类型 + 大小”的四重约束，是移动 Agent 与普通 coder 最本质的区别：它把 blast radius（影响半径）压缩到一个移动工程内部。

6. 行为策略与沟通风格

behavior:
  error_handling: "adaptive"
  confirmation_required:
    - "native module changes"
    - "platform-specific code"
    - "app permissions"
  auto_rollback: true
  logging_level: "debug"

communication:
  style: "technical"
  update_frequency: "batch"
  include_code_snippets: true
  emoji_usage: "minimal"

• error_handling: "adaptive"：错误处理策略自适应——瞬时错误可重试，确定性错误应改变策略而非重复同样的失败；

• confirmation_required（三项强制确认点）：这是对 autonomous: true 的必要制衡。尽管 Agent 总体自主，但三类高风险变更必须暂停征求确认：

  1. 原生模块改动（会触发 iOS/Android 原生重编译，成本高、风险大）；
  2. 平台特定代码（.android.ts/.ios.ts 类分叉实现，容易破坏另一平台）；
  3. 应用权限申请（Info.plist/AndroidManifest.xml 中的权限直接影响用户隐私与安全审核）。

  这一设计与 ui/mobile/ 的工程实践直接呼应：该应用的平台分叉正是集中在 RSSI 扫描上——rssi.service.android.ts、rssi.service.ios.ts、rssi.service.web.ts 三套实现对应三个平台，README 明确要求“Platform-specific files use the .android.ts / .ios.ts / .web.ts suffix convention”。这类文件恰恰落在“platform-specific code”的确认点上；

• auto_rollback: true：失败改动自动回滚，配合白名单路径构成安全网；

• logging_level: "debug"：记录详细执行日志，便于事后审计 Agent 做了什么。

沟通侧要求技术性表达、批量汇报（batch，而非逐条流水）、必须附带代码片段、极少使用 emoji——即面向开发者的高信噪比输出规范。

7. 集成关系：委派与上下文共享

integration:
  can_spawn: []
  can_delegate_to:
    - "test-unit"
    - "test-e2e"
  requires_approval_from: []
  shares_context_with:
    - "dev-frontend"
    - "spec-mobile-ios"
    - "spec-mobile-android"

• 不能 spawn 新 Agent（can_spawn: []），但可以委派测试给 test-unit 与 test-e2e 两个角色。这与 ui/mobile/ 的两层测试体系精确对应：Jest 单测（jest.config.js，覆盖 components/screens/services/stores/hooks/utils 共 25 个测试文件，位于 ui/mobile/src/tests/）与 Maestro 声明式 e2e（ui/mobile/e2e/，含 live/vitals/zones/mat/settings/offline_fallback 六个 YAML 规格）。写代码归 mobile-dev，验证代码归测试角色，职责清晰；
• requires_approval_from: []：无需其他 Agent 审批即可开工（审批已由 confirmation_required 在关键变更点上前置）；
• shares_context_with：与 dev-frontend（前端开发）、spec-mobile-ios、spec-mobile-android（两个原生平台专家）共享上下文。可以推断，当 iOS/Android 原生问题超出 RN 层时，mobile-dev 与平台专家之间可以无缝交接对话状态。

8. 优化参数：并行、批处理与内存上限

optimization:
  parallel_operations: true
  batch_size: 15
  cache_results: true
  memory_limit: "1GB"

允许并行操作、每批 15 个操作、结果缓存、1 GB 内存上限。对移动工程而言，“批量 15”意味着例如一次性批量修改 15 个组件文件的样式 token，或并行读取一批文件再统一规划编辑，减少工具调用轮次——这在 max_file_operations: 100 的预算下尤为重要。

9. 生命周期钩子：pre / post / on_error 三段 Shell 脚本

规范文件把三个阶段的可执行脚本内嵌在 hooks 中，这是该 Agent 最具实操价值的部分：

9.1 pre_execution：开工前探测工程形态

echo "📱 React Native Developer initializing..."
echo "🔍 Checking React Native setup..."
if [ -f "package.json" ]; then
  grep -E "react-native|expo" package.json | head -5
fi
echo "🎯 Detecting platform targets..."
[ -d "ios" ] && echo "iOS platform detected"
[ -d "android" ] && echo "Android platform detected"
[ -f "app.json" ] && echo "Expo project detected"

钩子在 Agent 启动时执行，用三个廉价探测判定目标工程的形态：package.json 中是否含 react-native/expo 依赖、是否存在 ios/ 与 android/ 原生目录（Bare 工程标志）、是否存在 app.json（Expo 托管工程标志）。对照仓库实况，ui/mobile/ 同时拥有 app.json、app.config.ts 与 package.json 中的 expo: ~55.0.4，因此该钩子会将其识别为 Expo 项目。探测结果决定了后续策略：Expo 工程优先走 npx expo start 工作流与配置层修改，Bare 工程才考虑深入 ios/、android/ 原生树。

9.2 post_execution：收尾时输出改动地图

echo "✅ React Native development completed"
echo "📦 Project structure:"
find . -name "*.js" -o -name "*.jsx" -o -name "*.tsx" | grep -E "(screens|components|navigation)" | head -10

列出本次涉及的 screens / components / navigation 文件（限前 10 个），为审阅者提供一张“改动地图”，与 logging_level: debug 的审计要求一致。

9.3 on_error：内置排障手册

echo "❌ React Native error: {{error_message}}"
echo "🔧 Common fixes:"
echo "  - Clear metro cache: npx react-native start --reset-cache"
echo "  - Reinstall pods: cd ios && pod install"
echo "  - Clean build: cd android && ./gradlew clean"

错误钩子把三条最高频的 RN 排障命令固化进规范：Metro 缓存重置（热更新/依赖解析类问题）、CocoaPods 重装（iOS 原生模块类问题）、Gradle 清理构建（Android 编译类问题）。{{error_message}} 是模板变量，运行时注入实际错误文本。这三条命令分别对应 Metro（JS 打包层）、Pods（iOS 原生依赖层）、Gradle（Android 构建层），覆盖 RN 最常见的三个故障面。

10. Agent 正文：注入的角色设定与开发规范

YAML 之后是作为系统提示词注入的 Markdown 正文（“You are a React Native Mobile Developer creating cross-platform mobile applications”），包含四块内容。

10.1 五项核心职责

1. 开发 React Native 组件与屏幕；
2. 实现导航与状态管理；
3. 处理平台差异化代码与样式；
4. 需要时集成原生模块；
5. 优化性能与内存占用。

10.2 六条最佳实践

• 使用函数式组件 + hooks；
• 采用 React Navigation 做导航；
• 妥善处理平台差异；
• 优化图片与静态资源；
• iOS 与 Android 双端都要测试；
• 使用规范的样式模式（集中式 StyleSheet / 设计 token）。

10.3 标准组件范式（完整代码模板）

正文内嵌了一个可直接复用的组件模板，展示了该 Agent 应产出的“标准长相”：函数式组件接收 navigation prop，用 useState/useEffect 管理状态，TouchableOpacity 触发 navigation.navigate('NextScreen') 跳转，并以 StyleSheet.create 集中定义样式。其中最体现跨端意识的是字体处理：

title: {
  fontSize: 24,
  fontWeight: 'bold',
  marginBottom: 20,
  ...Platform.select({
    ios: { fontFamily: 'System' },
    android: { fontFamily: 'Roboto' },
  }),
},

Platform.select 在同一份样式对象内为两端注入不同字体族（iOS 系统字体 / Android Roboto），这是 RN 平台差异化最轻量的惯用法——不需要分叉文件，只在样式层做选择。

10.4 平台差异化注意事项（正文最后一节）

• iOS：安全区域（Safe Areas）、导航模式、权限；
• Android：返回键（Back button）处理、Material Design 规范；
• 性能：长列表必须用 FlatList（虚拟滚动），图片资源优化；
• 状态管理：复杂应用用 Context API 或 Redux。

这四条正是 behavior.confirmation_required 中“app permissions”“platform-specific code”的落地指引：规范不仅声明“哪些操作要确认”，还告诉 Agent 在这些操作里应该注意什么。

11. 触发示例：Agent 如何响应典型请求

规范末尾给出两个 trigger → response 样例，展示了该 Agent 承诺的交付形态：

examples:
  - trigger: "create a login screen for React Native app"
    response: "I'll create a complete login screen with form validation, secure text input, and navigation integration for both iOS and Android..."
  - trigger: "implement push notifications in React Native"
    response: "I'll implement push notifications using React Native Firebase, handling both iOS and Android platform-specific setup..."

两条示例分别演示了“从零建屏”与“集成原生能力（推送）”两类任务，且都强调双端交付。

12. 规范背后的真实工程：ui/mobile 印证

把上述规范放回仓库语境，可以逐项验证它与 ui/mobile/ 的实际形态是对齐的：

（1）技术栈基线。据 ui/mobile/package.json，当前移动应用的依赖基线为：expo ~55.0.4、react-native 0.85.2、typescript ~5.9.2、react 19.2.0，配合 react-native-webview 13.16.0（Live 屏的高斯泼溅 3D 渲染）、react-native-svg 15.15.3（Zones 屏楼层平面图）、zustand ^5.0.12（状态管理）、axios ^1.15.2（REST）、react-native-wifi-reborn ^4.13.6（Android 原生 RSSI 扫描）。ADR-034 记录了当初的技术选型（Expo SDK 55 + React Navigation 7 + Zustand + Maestro e2e + 深色主题 #32B8C6 强调色）；ADR 中记载的初始 UI 框架版本为 RN 0.83，而当前 package.json 实际锁定在 0.85.2，说明工程在持续升级，以 package.json 为当前事实。

（2）“native module” 落点。ui/mobile 唯一真正触碰原生层的能力是 WiFi RSSI 扫描，按平台分叉为三个文件。以 Android 实现 rssi.service.android.ts 为例（L37-L49）：scanOnce() 调用 WifiManager.loadWifiList() 拉取网络列表，把 SSID/BSSID/level（兼容 levelDbm 字段，缺省 -100）映射为统一的 WifiNetwork 结构后广播给订阅者；startScanning(intervalMs) 以定时器轮询。这正是规范中 “implement * native module” 任务模式的现实版本——也是 confirmation_required 中 “native module changes” 与 “app permissions” 两个确认点所守护的对象（WiFi 扫描在 Android 上需要位置/近场权限，iOS 上需要 com.apple.developer.networking.wifi-info entitlement，见 README “iOS” 一节）。

（3）性能与健壮性要求的具体化。规范第 5 条职责是“优化性能与内存占用”，在源码中对应 ws.service.ts 的连接层设计：WsService 单例（L9-L16）维护 listeners 订阅集、重连计时器与仿真定时器；buildWsUrl（L100-L104）负责协议升级（https:→wss:、其余→ws:）并拼接路径常量；scheduleReconnect（L114-L134）实现指数退避重连，退避序列与上限来自 constants/websocket.ts：

export const WS_PATH = '/api/v1/stream/pose';
export const RECONNECT_DELAYS = [1000, 2000, 4000, 8000, 16000];
export const MAX_RECONNECT_ATTEMPTS = 10;

重连耗尽后自动切入仿真模式（合成 SensingFrame 数据流），使 UI 在服务器不可达时保持可用——这正是 README 所述 “Automatic simulation fallback”。需要说明：ADR-034 与 README 中描述的感知端点为 ws://<host>:3001/ws/sensing，而当前源码常量给出的路径为 /api/v1/stream/pose（完整地址由 Settings 中配置的服务器 URL 决定），二者存在文档与代码的漂移，实际以当前 websocket.ts 为准。

（4）测试委派目标的存在性。can_delegate_to: [test-unit, test-e2e] 对应的测试资产真实存在：Jest 套件按 components / screens / services / stores / hooks / utils 六类共 25 个测试文件组织于 ui/mobile/src/tests/（npm test 即可运行，见 package.json scripts），Maestro 规格位于 ui/mobile/e2e/（maestro test e2e/ 运行，覆盖六个屏幕场景加离线降级）。ui/mobile/ 的 README 还把“平台特定文件后缀约定、Zustand store 归位、类型归 src/types/”列为贡献者必须遵循的既有模式——与规范正文的“Use proper styling patterns”“navigation/state 职责划分”一脉相承。

13. 小结：一份“可执行契约”式的 Agent 规范

spec-mobile-react-native.md 展示了 RuView 仓库对“专用开发 Agent”的定义方式：它不是一段角色描述，而是一份可执行契约——

层	机制	回答的问题
路由层	triggers（keywords / file_patterns / task_patterns / domains）	什么任务应该交给它
权限层	capabilities.allowed_tools + max_file_operations + max_execution_time	它能用什么、能用多久
边界层	constraints（allowed/forbidden paths、文件类型、5MB 上限）	它能碰哪些文件
制衡层	confirmation_required + auto_rollback + debug 日志	高危操作如何受控
协作层	can_delegate_to / shares_context_with	它与测试及平台专家如何分工
执行层	hooks 三段 shell（探测工程 / 输出改动地图 / 排障命令）	开干前后做什么
知识层	Markdown 正文（职责、实践、组件模板、平台注意点）	它按什么标准写代码

对照 ui/mobile/ 的实际代码可以确认：规范中的每一条约束——Expo 探测、平台分叉文件、原生权限确认点、双端测试委派、WebSocket 重连与仿真降级——都在真实工程里找到了对应物。对维护者而言，这种规范文件的价值在于：新会话中的 Agent 无需重新“理解项目”，直接从触发、约束、钩子和角色设定出发，就能在一个受预算、受边界、可审计的前提下完成移动端的实现工作。