zafiro: Instructions file for Claude Code

AGENT RULES

项目定位

Zafiro 是一个 Android 应用，使用 Kotlin 技术栈。它通过 compose UI 结合 Root/Shizuku 等权限给 Agent 提供丰富的脚手架。同时支持通过基于 Binder + LSPosed 的接管系统将部分厂商语音助手换源为 Zafiro

重要优先级: 主应用 > Okia > py >> 宿主

术语（你在对话中会用到这些词）

• 宿主 / Host：被 Hook 的语音助手 App。Breeno（ColorOS，com.heytap.speechassist）和 XiaoAi（HyperOS，com.miui.voiceassist）
• 主 App：Zafiro 自己的进程（com.niki914.zafiro），跑设置 UI + Runtime Service
• takeover：本轮 query 的接管决策——InjectedLLM（Zafiro 替换回答）或 NativeTakeover（放行原生回复），由 TakeoverResolver 判定
• turn：一轮"用户问 → 回答呈现"的完整生命周期，ConversationTurnState 跟踪
• store：一个命名的 JSON 持久化单元（如 agent.main.config、rules.takeover），原子写入 filesDir/ 下对应路径
• render pipeline：LLM 响应注入宿主 UI 的链路。Breeno 走卡片全量刷新，XiaoAi 走响应目标捕获 + 指令分片注入

进程与 IPC 骨架

• 宿主进程：Xposed Hook 注入点。通过 AgentRuntimeClient（Binder）向主 App 提交 LLM 查询，通过 XIpcBridge.StoreClient（Binder）读写 settings store
• 主 App 进程：运行 AgentRuntimeService（前台 Service，Binder IPC），持有 store 持久化的本地访问权
• 两条 IPC 通道：XIpcBridge（配置读写/通知，走 StoreClient Binder 接口） + AgentRuntimeService（LLM query 提交与 RenderFrame 流式回调）

Engineering principles

• Do not preserve backward compatibility. Remove obsolete paths instead of adding compatibility layers, fallbacks, or migrations.
• Choose the simplest implementation that fully meets the current requirements. Avoid speculative abstractions, configuration, and indirection.
• Grow the system in layers. Start from the smallest version that works end to end, and add each new capability on top of a product that already works. Never trade a working product for unfinished complexity.
• Keep components modular and concerns clearly separated.
• Prefer established, well-maintained libraries when they reduce overall complexity or improve reliability. Do not reimplement common functionality without a clear reason.
• Lean on the dependencies already in the project before writing your own implementation or adding packages. Do not assume a library lacks a capability without checking its documentation and types.
• Make architectural decisions for the long term. Do not accept a stopgap that only works for now and is meant to be replaced later.
• Ask the user for help when a task is easy for the user but hard for you, such as refactoring code in Android Studio.
• When a feature is hard to implement (difficulty above 6/10) and low in value, negotiate scope with the user before building it.
• Use the android CLI for Android-related operations: build, install, device management, screenshots, UI inspection. Load the android-cli skill first.
• Only implement code changes when the user explicitly requests implementation (e.g., 开发 / 改 / 开始实现). Otherwise, plan and discuss without editing files.
• Before implementing, present the proposed solution and get the user's decision on the design.
• The user wants to decide anything that affects architecture or code quality. Surface such decisions for them to make. For trivial choices that no architect would weigh in on, decide yourself and mention them in passing.
• After implementing, recap the key changes. Do not commit unless the user asks.