@fudiandong/trellis-android-tv 1.0.0 → 1.0.8

package/spec/dpad_focus_rule.md

@@ -0,0 +1,89 @@
+# D-pad 焦点导航规范
+
+## 核心原则
+
+所有 TV UI 必须实现**闭环焦点导航**，确保用户按任意方向键时焦点始终在可控范围内。
+
+## 焦点配置
+
+### 1. 基础配置
+```xml
+<!-- 焦点控件必须设置 -->
+android:focusable="true"
+android:focusableInTouchMode="true"
+```
+
+### 2. 首次焦点
+```xml
+<!-- 页面默认焦点：根布局设置 -->
+android:defaultFocusHighlightEnabled="true"
+```
+
+## 方向导航
+
+### 3. nextFocusDown/Up/Left/Right
+```xml
+<!-- 明确指定各方向的下一个焦点控件 -->
+android:nextFocusDown="@+id/btn_confirm"
+android:nextFocusUp="@+id/btn_cancel"
+android:nextFocusLeft="@+id/btn_prev"
+android:nextFocusRight="@+id/btn_next"
+```
+
+### 4. 禁止焦点越界
+```xml
+<!-- 边缘控件必须指定环绕方向 -->
+<Button
+    android:id="@+id/btn_first"
+    android:nextFocusLeft="@+id/btn_last" />  <!-- 左边界环绕到最后一个 -->
+```
+
+## 焦点丢失处理
+
+### 5. ViewGroup 焦点容器
+```xml
+<!-- 动态区域使用 FocusableRelativeLayout 包裹 -->
+<FocusableRelativeLayout
+    android:focusable="true"
+    android:focusableInTouchMode="true">
+    <!-- 子控件 -->
+</FocusableRelativeLayout>
+```
+
+### 6. 焦点状态监听
+```java
+// 监听焦点变化，处理边界情况
+view.setOnFocusChangeListener((v, hasFocus) -> {
+    if (hasFocus) {
+        // 焦点进入：放大/高亮效果
+    }
+});
+```
+
+## 常见错误
+
+### ❌ 禁止
+- 动态添加 View 后未设置 nextFocus 属性
+- Recyclerview item 内嵌套可聚焦控件未指定导航
+- 使用.requestFocus() 而不处理焦点状态
+
+### ✅ 正确
+- 静态布局完整配置 nextFocus 四方向
+- 动态区域使用 FocusChangeListener 手动处理
+- 边缘控件使用 `nextFocusUp/Down/Left/Right` 形成闭环
+
+## 触摸兼容
+
+### 7. 触摸点击
+```java
+// 触摸模式下支持点击
+if (isInTouchMode()) {
+    performClick();
+}
+```
+
+### 8. 触摸模式焦点
+```xml
+<!-- 触屏设备需要 -->
+android:focusableInTouchMode="true"
+```

package/spec/guides/code-reuse-thinking-guide.md

@@ -0,0 +1,105 @@
+# Code Reuse Thinking Guide
+
+> **Purpose**: Stop and think before creating new code - does it already exist?
+
+---
+
+## The Problem
+
+**Duplicated code is the #1 source of inconsistency bugs.**
+
+When you copy-paste or rewrite existing logic:
+- Bug fixes don't propagate
+- Behavior diverges over time
+- Codebase becomes harder to understand
+
+---
+
+## Before Writing New Code
+
+### Step 1: Search First
+
+```bash
+# Search for similar function names
+grep -r "functionName" .
+
+# Search for similar logic
+grep -r "keyword" .
+```
+
+### Step 2: Ask These Questions
+
+| Question | If Yes... |
+|----------|-----------|
+| Does a similar function exist? | Use or extend it |
+| Is this pattern used elsewhere? | Follow the existing pattern |
+| Could this be a shared utility? | Create it in the right place |
+| Am I copying code from another file? | **STOP** - extract to shared |
+
+---
+
+## Common Duplication Patterns
+
+### Pattern 1: Copy-Paste Functions
+
+**Bad**: Copying a validation function to another file
+
+**Good**: Extract to shared utilities, import where needed
+
+### Pattern 2: Similar Components
+
+**Bad**: Creating a new component that's 80% similar to existing
+
+**Good**: Extend existing component with props/variants
+
+### Pattern 3: Repeated Constants
+
+**Bad**: Defining the same constant in multiple files
+
+**Good**: Single source of truth, import everywhere
+
+---
+
+## When to Abstract
+
+**Abstract when**:
+- Same code appears 3+ times
+- Logic is complex enough to have bugs
+- Multiple people might need this
+
+**Don't abstract when**:
+- Only used once
+- Trivial one-liner
+- Abstraction would be more complex than duplication
+
+---
+
+## After Batch Modifications
+
+When you've made similar changes to multiple files:
+
+1. **Review**: Did you catch all instances?
+2. **Search**: Run grep to find any missed
+3. **Consider**: Should this be abstracted?
+
+---
+
+## Gotcha: Asymmetric Mechanisms Producing Same Output
+
+**Problem**: When two different mechanisms must produce the same file set (e.g., recursive directory copy for init vs. manual `files.set()` for update), structural changes (renaming, moving, adding subdirectories) only propagate through the automatic mechanism. The manual one silently drifts.
+
+**Symptom**: Init works perfectly, but update creates files at wrong paths or misses files entirely.
+
+**Prevention checklist**:
+- [ ] When migrating directory structures, search for ALL code paths that reference the old structure
+- [ ] If one path is auto-derived (glob/copy) and another is manually listed, the manual one needs updating
+- [ ] Add a regression test that compares outputs from both mechanisms
+
+---
+
+## Checklist Before Commit
+
+- [ ] Searched for existing similar code
+- [ ] No copy-pasted logic that should be shared
+- [ ] Constants defined in one place
+- [ ] Similar patterns follow same structure

package/spec/guides/cross-layer-thinking-guide.md

@@ -0,0 +1,162 @@
+# Cross-Layer Thinking Guide
+
+> **Purpose**: Think through data flow across layers before implementing.
+
+---
+
+## The Problem
+
+**Most bugs happen at layer boundaries**, not within layers.
+
+Common cross-layer bugs:
+- API returns format A, frontend expects format B
+- Database stores X, service transforms to Y, but loses data
+- Multiple layers implement the same logic differently
+
+---
+
+## Before Implementing Cross-Layer Features
+
+### Step 1: Map the Data Flow
+
+Draw out how data moves:
+
+```
+Source → Transform → Store → Retrieve → Transform → Display
+```
+
+For each arrow, ask:
+- What format is the data in?
+- What could go wrong?
+- Who is responsible for validation?
+
+### Step 2: Identify Boundaries
+
+| Boundary | Common Issues |
+|----------|---------------|
+| API ↔ Service | Type mismatches, missing fields |
+| Service ↔ Database | Format conversions, null handling |
+| Backend ↔ Frontend | Serialization, date formats |
+| Component ↔ Component | Props shape changes |
+
+### Step 3: Define Contracts
+
+For each boundary:
+- What is the exact input format?
+- What is the exact output format?
+- What errors can occur?
+
+---
+
+## Common Cross-Layer Mistakes
+
+### Mistake 1: Implicit Format Assumptions
+
+**Bad**: Assuming date format without checking
+
+**Good**: Explicit format conversion at boundaries
+
+### Mistake 2: Scattered Validation
+
+**Bad**: Validating the same thing in multiple layers
+
+**Good**: Validate once at the entry point
+
+### Mistake 3: Leaky Abstractions
+
+**Bad**: Component knows about database schema
+
+**Good**: Each layer only knows its neighbors
+
+---
+
+## Checklist for Cross-Layer Features
+
+Before implementation:
+- [ ] Mapped the complete data flow
+- [ ] Identified all layer boundaries
+- [ ] Defined format at each boundary
+- [ ] Decided where validation happens
+
+After implementation:
+- [ ] Tested with edge cases (null, empty, invalid)
+- [ ] Verified error handling at each boundary
+- [ ] Checked data survives round-trip
+
+---
+
+## Cross-Platform Template Consistency
+
+In Trellis, command templates (e.g., `record-session.md`) exist in **multiple platforms** with identical or near-identical content. This is a cross-layer boundary.
+
+### Checklist: After Modifying Any Command Template
+
+- [ ] Find all platforms with the same command: `find src/templates/*/commands/trellis/ -name "<command>.*"`
+- [ ] Update all platform copies (Markdown `.md` and TOML `.toml`)
+- [ ] For Gemini TOML: adapt line continuations (`\\` vs `\`) and triple-quoted strings
+- [ ] Run `/trellis:check-cross-layer` to verify nothing was missed
+
+**Real-world example**: Updated `record-session.md` in Claude to use `--mode record`, but forgot iFlow, Kilo, OpenCode, and Gemini — caught by cross-layer check.
+
+---
+
+## Generated Runtime Template Upgrade Consistency
+
+Some generated files are both documentation and runtime input. In Trellis,
+`.trellis/workflow.md` is parsed by `get_context.py`, `workflow_phase.py`,
+SessionStart filters, and per-turn hooks. Template changes must be validated
+against both fresh init and upgrade paths.
+
+### Checklist: After Modifying A Runtime-Parsed Template
+
+- [ ] Identify every runtime parser that reads the template, not just the file
+  writer that installs it
+- [ ] Check whether relevant syntax lives outside obvious managed regions
+  such as tag blocks
+- [ ] Verify fresh `init` output and a versioned `update` scenario that writes
+  the older `.trellis/.version`
+- [ ] Add an upgrade regression using an older pristine template fixture, then
+  assert the installed file reaches the current packaged shape
+- [ ] Update the backend spec that owns the runtime contract
+
+**Real-world example**: Codex inline mode changed workflow platform markers from
+`[Codex]` / `[Kilo, Antigravity, Windsurf]` to `[codex-sub-agent]` /
+`[codex-inline, Kilo, Antigravity, Windsurf]`. Fresh init was correct, but
+`trellis update` only merged `[workflow-state:*]` blocks and preserved stale
+markers outside those blocks. Result: upgraded projects got new hook scripts
+but old workflow routing, so `get_context.py --mode phase --platform codex`
+could return empty Phase 2.1 detail.
+
+---
+
+## Mode-Detection Probe Checklist
+
+When a CLI auto-detects a mode by probing a remote resource (e.g., checking if `index.json` exists to decide marketplace vs direct download):
+
+### Before implementing:
+- [ ] Probe runs in **ALL** code paths that use the result (interactive, `-y`, `--flag` combos)
+- [ ] 404 vs transient error are distinguished — don't treat both as "not found"
+- [ ] Transient errors **abort or retry**, never silently switch modes
+- [ ] Shared state (caches, prefetched data) is **reset** when context changes (e.g., user switches source)
+- [ ] **Shortcut paths** (e.g., `--template` skipping picker) must have the same error-handling quality as the probed path — check that downstream functions don't call catch-all wrappers
+
+### After implementing:
+- [ ] Trace every path from probe result to the mode-decision branch — no fallthrough
+- [ ] External format contracts (giget URI, raw URLs) are tested or at least documented as comments
+- [ ] Metadata reads consume a complete response or use a streaming parser — never parse a fixed-size prefix as full JSON
+- [ ] When reconstructing a composite identifier from parsed parts, verify **all** fields are included and in the **correct position** (e.g., `provider:repo/path#ref` not `provider:repo#ref/path`)
+- [ ] Verify that **action functions** called after a shortcut don't internally use the old catch-all fetch — they must use the probe-quality variant when error distinction matters
+
+**Real-world example**: Custom registry flow had 8 bugs across 3 review rounds: (1) probe only ran in interactive mode, (2) transient errors fell through to wrong mode, (3) giget URI had `#ref` in wrong position, (4) prefetched templates leaked across source switches, (5) `--template` shortcut bypassed probe but `downloadTemplateById` internally used catch-all `fetchTemplateIndex`, turning timeouts into "Template not found".
+
+**Real-world example**: Agent-session update hints fetched npm `latest` metadata with `response.read(4096)` and then parsed it as complete JSON. The `@mindfoldhq/trellis` package metadata exceeded 4 KB, so the JSON was truncated, parse failed silently, and the first session injection showed no update hint. Fix: read the complete response before parsing, and add a regression where `version` is followed by an 8 KB metadata tail.
+
+---
+
+## When to Create Flow Documentation
+
+Create detailed flow docs when:
+- Feature spans 3+ layers
+- Multiple teams are involved
+- Data format is complex
+- Feature has caused bugs before

package/spec/guides/index.md

@@ -0,0 +1,79 @@
+# Thinking Guides
+
+> **Purpose**: Expand your thinking to catch things you might not have considered.
+
+---
+
+## Why Thinking Guides?
+
+**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
+
+- Didn't think about what happens at layer boundaries → cross-layer bugs
+- Didn't think about code patterns repeating → duplicated code everywhere
+- Didn't think about edge cases → runtime errors
+- Didn't think about future maintainers → unreadable code
+
+These guides help you **ask the right questions before coding**.
+
+---
+
+## Available Guides
+
+| Guide | Purpose | When to Use |
+|-------|---------|-------------|
+| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
+| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
+
+---
+
+## Quick Reference: Thinking Triggers
+
+### When to Think About Cross-Layer Issues
+
+- [ ] Feature touches 3+ layers (API, Service, Component, Database)
+- [ ] Data format changes between layers
+- [ ] Multiple consumers need the same data
+- [ ] You're not sure where to put some logic
+
+→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
+
+### When to Think About Code Reuse
+
+- [ ] You're writing similar code to something that exists
+- [ ] You see the same pattern repeated 3+ times
+- [ ] You're adding a new field to multiple places
+- [ ] **You're modifying any constant or config**
+- [ ] **You're creating a new utility/helper function** ← Search first!
+
+→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
+
+---
+
+## Pre-Modification Rule (CRITICAL)
+
+> **Before changing ANY value, ALWAYS search first!**
+
+```bash
+# Search for the value you're about to change
+grep -r "value_to_change" .
+```
+
+This single habit prevents most "forgot to update X" bugs.
+
+---
+
+## How to Use This Directory
+
+1. **Before coding**: Skim the relevant thinking guide
+2. **During coding**: If something feels repetitive or complex, check the guides
+3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
+
+---
+
+## Contributing
+
+Found a new "didn't think of that" moment? Add it to the relevant guide.
+
+---
+
+**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.

package/spec/mvvm_rule.md

@@ -0,0 +1,100 @@
+# MVVM 架构规范
+
+## 项目架构
+
+基于 Google Android Architecture Components，采用 **MVVM + ViewBinding** 模式。
+
+## 目录结构
+
+```
+com.stb.duer.apps.xtvott
+├── ui/                    # Activity/Fragment/Adapter
+│   ├── main/
+│   ├── player/
+│   └── common/
+├── vm/                    # ViewModel
+├── model/                 # 数据模型
+│   ├── entity/           # 数据库实体
+│   └── data/             # 数据类
+├── repository/           # 数据仓库
+├── data/                 # 数据层
+│   ├── local/            # 本地存储
+│   └── remote/           # 远程接口
+└── util/                 # 工具类
+```
+
+## ViewModel 规范
+
+### 1. ViewModel 创建
+```java
+// 使用 ViewModelProvider
+ViewModelProvider provider = new ViewModelProvider(this);
+MyViewModel vm = provider.get(MyViewModel.class);
+```
+
+### 2. LiveData 使用
+```java
+// 暴露 LiveData
+private final MutableLiveData<String> statusLiveData = new MutableLiveData<>();
+public LiveData<String> getStatus() {
+    return statusLiveData;
+}
+```
+
+### 3. 生命周期感知
+```java
+// 使用 observe 绑定到 lifecycleOwner
+viewModel.getData().observe(this, data -> {
+    // 自动在 onDestroy 时解绑
+});
+```
+
+## 数据绑定
+
+### 4. ViewBinding 使用
+```java
+// Activity 中
+private ActivityMainBinding binding;
+
+@Override
+protected void onCreate(Bundle savedInstanceState) {
+    super.onCreate(savedInstanceState);
+    binding = ActivityMainBinding.inflate(getLayoutInflater());
+    setContentView(binding.getRoot());
+}
+```
+
+### 5. 双向绑定（少量使用）
+```xml
+<!-- 仅用于简单表单 -->
+android:text="@={viewModel.inputText}"
+```
+
+## Repository 模式
+
+### 6. 数据仓库封装
+```java
+public class UserRepository {
+    private final UserApi api;
+    private final UserDao dao;
+
+    public LiveData<User> getUser(int id) {
+        // 优先使用本地缓存，支持离线
+        return dao.getUser(id);
+    }
+}
+```
+
+## 常见错误
+
+### ❌ 禁止
+- 在 ViewModel 中直接操作 View
+- 使用 LiveData 而不 observe
+- ViewModel 中使用 Context（使用 Application Context）
+- 在主线程进行网络/数据库操作
+
+### ✅ 正确
+- ViewModel 通过 LiveData 通知 View
+- 使用 Executor/AsyncTask 处理异步
+- 使用 Application Context 或 LiveDataScope
+- 数据操作在 Repository 层统一处理

package/spec/res_resource.md

@@ -0,0 +1,111 @@
+# 资源文件规范
+
+## AutoSize 框架适配
+
+项目使用 **Android AutoSize** 框架实现屏幕适配，无需编写多套 dimens 文件。
+
+### 1. 启用 AutoSize
+```xml
+<!-- AndroidManifest.xml -->
+<manifest>
+    <application>
+        <meta-data
+            android:name="design_width_in_dp"
+            android:value="1920" />
+        <meta-data
+            android:name="design_height_in_dp"
+            android:value="1080" />
+    </application>
+</manifest>
+```
+
+### 2. 单位使用
+```xml
+<!-- 优先使用 dp/sp，禁止使用 px -->
+<dimen name="text_size_title">48sp</dimen>
+<dimen name="margin_standard">24dp</dimen>
+
+<!-- 禁止 -->
+<!-- <dimen name="wrong_size">100px</dimen> -->
+```
+
+### 3. 布局约束
+```xml
+<!-- 优先使用约束布局 + wrap_content/match_constraint -->
+<TextView
+    android:layout_width="0dp"
+    app:layout_constraintWidth_default="wrap"
+    android:textSize="@dimen/text_size_title" />
+```
+
+## 布局文件
+
+### 4. 命名规范
+```
+activity_xxx_tv.xml     # TV Activity 布局
+fragment_xxx_tv.xml     # TV Fragment 布局
+item_xxx.xml            # 列表项布局
+layout_xxx.xml          # 可复用布局
+```
+
+### 5. TV/触屏共用
+```xml
+<!-- 同一布局文件，AutoSize 自动适配 -->
+<!-- 不需要 values-sw720dp 等额外适配 -->
+```
+
+## 字体适配
+
+### 6. sp 单位字体
+```xml
+<!-- 所有字体使用 sp 单位，AutoSize 自动缩放 -->
+<TextView
+    android:textSize="@dimen/text_size_body"
+    android:textColor="@color/text_primary" />
+```
+
+## 颜色资源
+
+### 7. 颜色定义
+```xml
+<!-- res/values/colors.xml -->
+<color name="primary">#FF6200EE</color>
+<color name="text_primary">#FFFFFFFF</color>
+<color name="text_secondary">#B3FFFFFF</color>
+```
+
+## 字符串资源
+
+### 8. 字符串规范
+```xml
+<!-- 禁止硬编码字符串 -->
+<!-- 错误：android:text="确定" -->
+<!-- 正确 -->
+android:text="@string/btn_confirm"
+```
+
+## Selector 选择器
+
+### 9. 焦点/按压状态
+```xml
+<!-- 必须同时定义遥控器焦点和触屏按压状态 -->
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:state_focused="true" android:drawable="@drawable/bg_focused"/>
+    <item android:state_pressed="true" android:drawable="@drawable/bg_pressed"/>
+    <item android:drawable="@drawable/bg_normal"/>
+</selector>
+```
+
+## 常见错误
+
+### ❌ 禁止
+- 使用 px 单位
+- 硬编码尺寸数值
+- 硬编码字符串
+- 布局中缺少 focusable 属性
+
+### ✅ 正确
+- 使用 dp/sp 单位
+- 统一管理颜色/字符串资源
+- TV 控件设置 focusable="true"
+- 使用 ConstraintLayout 减少嵌套

package/spec/tv_touch_layout.md

@@ -0,0 +1,31 @@
+# TV+触屏双端布局规范
+
+## 1. 布局结构
+根布局优先ConstraintLayout，杜绝多层LinearLayout嵌套（TV渲染卡顿）
+
+## 2. 焦点配置
+焦点控件默认设置focusable=true，触屏环境focusableInTouchMode=true
+
+## 3. 控件尺寸
+TV端控件偏大(最小高48dp起)，触屏复用同套layout，使用 AutoSize 框架自动适配各尺寸屏幕
+- 基准设计稿：1920x1080dp
+- 单位：dp/sp（禁止px）
+
+## 4. 点击状态
+selector必须同时配置state_focused(遥控器选中)、state_pressed(触屏按压)
+
+## 5. 布局约束
+禁止写死宽高match_parent+固定dp混用，优先wrap_content+layout_constraint约束
+
+## 6. 列表控件
+RecyclerView统一封装TvRecyclerView，内置焦点跳转+触屏滑动兼容
+
+## 7. AutoSize 配置
+```xml
+<meta-data
+    android:name="design_width_in_dp"
+    android:value="1920" />
+<meta-data
+    android:name="design_height_in_dp"
+    android:value="1080" />
+```

package/workflow.md

@@ -0,0 +1,10 @@
+# Android TV+触屏 标准化开发工作流
+1. 需求录入：解析页面功能，生成标准目录结构（Activity + Fragment + ViewModel + 布局文件）
+2. 布局编写：基于 ConstraintLayout 实现布局，默认开启焦点、触屏双适配属性
+3. 业务代码：采用 Java + AndroidX + MVVM 架构，强制继承项目基础基类，启用 ViewBinding
+4. 自动化校验：依次执行内置技能
+   - tv_focus_check：校验并修复 Dpad 焦点问题
+   - touch_compat：补全触屏兼容逻辑与交互效果
+   - layout_adapt：抽离硬编码尺寸，完成多分辨率适配
+5. 代码评审：code_review_tv 全量检查编码规范、架构、适配规则
+6. 最终输出：可直接编译运行的完整代码