开发者指南

环境要求

• Node.js 22.11+
• npm
• Android Studio + Android SDK（Android）
• macOS + Xcode + CocoaPods（iOS 原生构建）

安装与仓库检查

npm run check 是提交前的基础门禁，覆盖 TypeScript、ESLint、架构边界和 Jest 自动化测试。行为变化需要同步更新或新增测试。

npm ci
npm run check

Android

Android 构建与 CI 可以验证源码、原生编译和 APK 产物的一部分属性，但设备安装、系统权限、相机 / 麦克风等行为仍应在真机上单独验证。

npm start
npm run android

# 只构建 Debug APK
npm run android:debug

iOS

iOS 源码与原生桥接存在于项目中，但 iOS 编译和真机结果必须与 Android CI 分开记录，不能因为 Android 通过就推断 iOS 通过。

bundle install
cd ios
bundle exec pod install
cd ..
npm run ios

架构规则

• 保持 Feature → Runtime → Domain / Provider / Repository → Native / Infrastructure 的依赖方向。
• UI / Feature 不直接依赖具体原生实现。
• 敏感设备操作必须经过 Capability Runtime 与 Policy。
• Unknown Capability 默认 DENY。
• Trust 不等于 Permission。
• Task 属于 CetaMesh，不属于某个模型 Session。
• Memory 先授权，再检索或同步。
• 不要在没有明确架构批准的情况下引入 unrestricted shell、任意 Native Bridge 或下载后可执行插件代码。

贡献流程

1. 从 README、PROJECT_STATE、AGENTS 和相关 architecture / protocol / security 文档了解当前边界。
2. 一个改动集只解决一个主要问题，避免混入无关重构。
3. 行为变化同步增加或更新测试。
4. 涉及协议、数据库、权限、安全、原生或公开 UI 的变化同步更新对应文档。
5. 运行 npm run check。
6. Pull Request 中写明问题、方案、测试、尚未执行的环境验证和安全影响。

如何记录验证状态

CetaMesh 明确区分代码完成、自动化通过和真实环境验证。没有执行过的原生 / 设备 / 对端检查不要写成 PASS。

• PASS：实际执行并通过。
• NOT_RUN_ENVIRONMENT：当前环境无法执行。
• PENDING_NATIVE_VERIFICATION：需要原生 / 真机验证。
• BLOCKED：存在明确阻塞条件。