feat(git-workflow): add git collaboration policy and safety baseline

.gitattributes

@@ -1,2 +1,33 @@
+# Base normalization
+* text=auto eol=lf
+
+# Native scripts keep LF
+*.sh text eol=lf
+*.ets text eol=lf
+*.ts text eol=lf
+*.js text eol=lf
+*.json text eol=lf
+*.json5 text eol=lf
+*.md text eol=lf
+
+# Windows batch scripts
+*.bat text eol=crlf
+
+# Binary and archive-like artifacts
+*.har -text
+*.so -text
+*.a -text
+*.bin -text
+*.png -text
+*.jpg -text
+*.jpeg -text
+*.gif -text
+*.mp3 -text
+*.flac -text
+*.wav -text
+*.zip -text
+*.7z -text
+
+# Existing LFS mapping
 ijkplayer/libs/arm64-v8a/libijkffmpeg.z.so filter=lfs diff=lfs merge=lfs -text
 ijkplayer/libs/armeabi-v7a/libijkffmpeg.z.so filter=lfs diff=lfs merge=lfs -text

.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## 变更概述
+
+- 变更类型：`feature` / `fix` / `refactor` / `docs` / `chore`
+- 影响模块：
+- 关联需求/Issue：
+
+## Git 协作检查清单（必填）
+
+- [ ] 本分支基于最新基线同步（`status -> fetch -> rebase/merge`）
+- [ ] 未提交改动已妥善保护（commit/stash/backup 分支）
+- [ ] 如发生冲突，已按项目 SOP 处理并验证
+- [ ] 本次提交无高风险破坏性命令导致的隐式覆盖
+
+## 验证记录
+
+- 构建/测试命令：
+- 手工验证步骤：
+- 关键日志/截图：
+
+## 风险与回滚
+
+- 潜在风险：
+- 回滚方案：

.gitignore

@@ -1,17 +1,31 @@
-/node_modules
-/local.properties
-/.idea
-**/build
-package-lock.json
-/.hvigor
-.clang-format
-.clang-tidy
-.clangd
-@ohos
-.vscode
-.vs
-build-profile.json5
-oh_modules
+/node_modules
+/local.properties
+/.idea
+**/build
+package-lock.json
+/.hvigor
+.clang-format
+.clang-tidy
+.clangd
+@ohos
+.vscode
+.vs
+build-profile.json5
+oh_modules
 oh-package-lock.json5
+
 # macOS
 .DS_Store
+
+# Local logs and merge artifacts
+logs/
+*_output.txt
+merge_output.txt
+stash_output.txt
+
+# Local AI/tooling workspace metadata
+.agent/
+.claude/
+.codex/
+.cursor/
+.history/

doc/Git协作规范v1.0.md

@@ -0,0 +1,136 @@
+# Git 协作规范 v1.0
+
+## 1. 目标与适用范围
+
+本规范用于降低 `git pull` 后冲突率，避免本地改动被覆盖，统一 TTMusic 项目的团队协作流程。
+
+适用范围：所有参与本仓库开发与评审的成员。
+
+## 2. 分支模型与集成规则
+
+- 主干分支（`main`/`master`）仅用于集成，禁止直接提交。
+- 功能开发使用 `feature/*` 分支。
+- 缺陷修复使用 `fix/*` 分支。
+- 主干合入必须通过 PR，并完成代码评审后合入。
+
+分支命名示例：
+- `feature/webdav-upload-refactor`
+- `fix/local-music-crash-on-resume`
+
+## 3. 日常同步 SOP
+
+### 3.1 拉取前强制检查
+
+每次 `pull` / `rebase` / 切分支前，必须执行：
+
+```bash
+git status
+```
+
+判定规则：
+- 工作区干净：可继续同步。
+- 存在未提交改动：必须先 `commit` 或 `stash`，禁止直接同步。
+
+### 3.2 标准同步流程
+
+```bash
+git status
+git fetch origin
+git rebase origin/<base-branch>
+```
+
+适用边界：
+- 个人分支优先使用 rebase 保持线性历史。
+- 对共享分支或已公开历史，若不适合 rebase，可使用 merge，但需在 PR 说明中注明。
+
+### 3.3 推送与集成检查
+
+推送前检查：
+- 提交是否按语义组织，避免把无关改动混到同一 commit。
+- 是否已完成基础构建/自测。
+- PR 描述是否包含：改动范围、风险点、验证结果。
+
+## 4. 冲突处理 SOP
+
+### 4.1 冲突定位
+
+```bash
+git status
+```
+
+定位含冲突文件后，逐个处理冲突标记（`<<<<<<<`、`=======`、`>>>>>>>`）。
+
+### 4.2 手工解决与验证
+
+- 按业务语义合并，不做机械保留。
+- 解决后执行：
+
+```bash
+git add <file>
+git rebase --continue   # 或 git commit（merge 场景）
+```
+
+- 完成后至少执行一次关键路径验证（构建/核心流程冒烟）。
+
+### 4.3 提交与记录
+
+冲突解决提交信息建议包含 `conflict-resolve` 关键字，并在 PR 说明中记录冲突来源与处理原则。
+
+## 5. 本地改动保护与恢复 SOP
+
+### 5.1 命名 stash 规范
+
+```bash
+git stash push -m "<date>-<branch>-<purpose>"
+```
+
+示例：`2026-02-06-feature-webdav-sync-before-rebase`
+
+### 5.2 临时备份分支规范
+
+```bash
+git switch -c backup/<date>-<topic>
+```
+
+用于保护未完成改动，避免误操作覆盖。
+
+### 5.3 恢复流程
+
+```bash
+git stash list
+git stash apply stash@{n}
+```
+
+若冲突，回到“冲突处理 SOP”处理。
+
+## 6. 高风险命令红线
+
+以下命令属于高风险操作，默认禁止直接执行：
+- `git reset --hard`
+- `git checkout -- <path>`（覆盖工作区）
+- `git clean -fd`
+
+允许前置条件：
+- 已创建可恢复点（commit / stash / backup 分支）。
+- 明确知晓影响范围并经过二次确认。
+
+## 7. 仓库基线策略
+
+### 7.1 文本归一化
+
+- 统一通过 `.gitattributes` 管理行尾与文本识别，避免跨平台伪冲突。
+
+### 7.2 二进制与不可安全文本合并文件
+
+- 二进制文件标记为 `-text`，禁止按文本方式合并。
+- 对锁文件、HAR 等生成/归档文件，根据版本管理策略决定是否纳入版本库。
+
+## 8. 已知限制与后续优化
+
+已知限制：
+- 团队尚未建立自动化冲突预警机制，流程依赖人工执行。
+- 某些跨团队紧急变更可能临时偏离标准流程。
+
+后续优化：
+- 结合 PR 模板与 CI 检查增强流程约束。
+- 统计冲突热点文件并优化模块边界。

doc/Git协作试运行计划.md

@@ -0,0 +1,38 @@
+# Git 协作试运行计划（1-2 迭代）
+
+## 1. 目标
+
+验证《Git 协作规范 v1.0》在真实开发中的可执行性，重点观察：
+- 冲突率是否下降
+- 本地改动覆盖事件是否减少
+- 团队操作一致性是否提升
+
+## 2. 试运行范围
+
+- 参与角色：开发、评审、维护者
+- 时间窗口：1-2 个迭代
+- 统计对象：所有 PR 与同步行为
+
+## 3. 记录字段
+
+每次发生冲突或覆盖风险时，记录：
+- 日期
+- 分支
+- 场景（pull/rebase/merge/cherry-pick）
+- 冲突文件
+- 处理时长
+- 根因
+- 是否按 SOP 处理
+- 改进建议
+
+## 4. 评估标准
+
+- 冲突重复率（同类冲突是否反复出现）
+- 覆盖风险事件数
+- 单次冲突平均处理时长
+
+## 5. 输出物
+
+- 试运行记录表
+- 反馈汇总
+- v1.0 -> v1.1 修订建议

openspec/changes/improve-git-collaboration-workflow/change-summary.md

@@ -0,0 +1,20 @@
+# 变更说明（实施结果）
+
+## 最终采用规则
+
+- 采用“主干受保护 + 短生命周期功能分支”模式。
+- 统一同步流程：`git status -> git fetch -> git rebase/merge`。
+- pull/rebase 前必须先处理本地未提交改动（commit/stash/backup 分支）。
+- 高风险命令（`reset --hard`、破坏性 checkout/clean）需满足恢复点与二次确认前置条件。
+- 通过 `.gitattributes` 统一文本归一化，并对二进制文件采用非文本合并策略。
+
+## 已知限制
+
+- 当前主要依赖文档与人工执行，尚未引入强制自动化门禁。
+- 试运行数据尚未沉淀，部分规则需要基于真实冲突样本进一步收敛。
+
+## 后续优化计划
+
+- 在 PR 模板与 CI 检查中强化流程校验。
+- 建立冲突案例统计与热点文件治理机制。
+- 根据试运行反馈迭代规范，发布 v1.1。

openspec/changes/improve-git-collaboration-workflow/design.md

@@ -0,0 +1,82 @@
+/## Context
+
+当前仓库在多人协作时缺少统一 Git 操作约束，开发者在 `pull`、`rebase`、`merge`、`stash` 和分支切换中的行为不一致，导致两类核心问题：
+- 冲突频发且处理方式不一致，重复消耗时间。
+- 本地未提交改动在高风险操作中被覆盖或丢失。
+
+本次设计需要在不改变业务运行时行为的前提下，给出可执行、可落地、可审计的协作机制，覆盖日常开发与异常处置场景。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 形成统一的分支与同步策略，降低无效冲突。
+- 建立 pull 前本地改动保护流程，显式避免“误覆盖”。
+- 通过仓库基线配置（如 `.gitattributes`）减少跨平台伪冲突。
+- 提供冲突与覆盖风险的标准化处置手册，提升团队一致性。
+
+**Non-Goals:**
+- 不改动业务代码逻辑与运行时接口。
+- 不引入复杂的 Git 托管平台自动化体系（如强制机器人流程改造）。
+- 不在本阶段处理历史提交重写或大规模分支清理迁移。
+
+## Decisions
+
+1. 采用“受保护主干 + 短生命周期功能分支”策略。
+- 选择：`main/master` 仅通过 PR 合入，个人开发在 `feature/*`、`fix/*` 分支进行。
+- 原因：隔离日常开发与集成风险，减少直接在主干上产生冲突。
+- 备选：继续允许直接向主干提交。
+- 不选原因：无法有效约束冲突来源，且回溯困难。
+
+2. 统一日常同步基线为“先检查本地改动，再同步远端”。
+- 选择：pull 前执行状态检查（`git status`），发现未提交改动时必须先 `commit` 或 `stash`。
+- 原因：把风险前置，避免 merge/rebase 时混入脏工作区。
+- 备选：允许直接 `git pull` 自动处理。
+- 不选原因：高概率引入隐式冲突和覆盖风险。
+
+3. 默认以 rebase 同步个人分支（保持线性历史），主干集成仍通过 PR merge 策略控制。
+- 选择：开发者本地 `fetch + rebase` 为主，减少无意义 merge commit。
+- 原因：冲突定位更清晰，历史可读性更高。
+- 备选：全面 merge 同步。
+- 不选原因：历史噪音大，冲突来源不直观。
+
+4. 建立“本地改动保护”硬性规则。
+- 选择：禁止在未理解后果时使用 `reset --hard`、`checkout -- .` 等破坏性命令；提供 stash 命名规范和恢复流程。
+- 原因：覆盖问题主要来源于破坏性命令与无保护 pull。
+- 备选：仅口头提醒。
+- 不选原因：不可审计，执行一致性低。
+
+5. 增加仓库冲突预防基线。
+- 选择：补充 `.gitattributes`（统一文本归一化、二进制标注、必要的 merge 策略）与 `.gitignore` 建议项。
+- 原因：减少跨系统换行差异和二进制误合并引发的伪冲突。
+- 备选：维持默认 Git 行为。
+- 不选原因：跨平台团队中冲突噪音无法下降。
+
+6. 文档化并模板化操作流程。
+- 选择：在 `doc/` 增加“日常同步 SOP”“冲突处理 SOP”“本地改动恢复 SOP”。
+- 原因：将经验固化为可执行步骤，降低新人上手成本。
+- 备选：分散在聊天记录或口头传递。
+- 不选原因：知识不可追踪，执行偏差大。
+
+## Risks / Trade-offs
+
+- [Risk] 团队成员对新流程不熟悉，短期操作成本上升 -> Mitigation：提供最小命令清单与示例，PR 阶段进行轻量检查。
+- [Risk] rebase 使用不当可能改写本地历史 -> Mitigation：明确“仅在个人未共享分支 rebase”的规则，并提供回滚指令。
+- [Risk] `.gitattributes` 调整后可能触发一次性大 diff -> Mitigation：分阶段引入并在独立 PR 中完成，避免与业务改动混合。
+- [Risk] 规则过严影响紧急修复效率 -> Mitigation：定义紧急通道，但要求事后补齐规范流程与记录。
+
+## Migration Plan
+
+1. 在文档中发布新协作规范与高风险命令红线。
+2. 引入 `.gitattributes`/`.gitignore` 基线变更，并单独评审。
+3. 团队试运行 1-2 个迭代，收集冲突率与恢复案例。
+4. 根据试运行反馈调整 SOP 细节。
+5. 将规范纳入 PR 模板或开发检查清单。
+
+回滚策略：若新基线导致异常，可先回退文档强制项与 `.gitattributes` 改动，保留最小安全规则（pull 前检查与本地改动保护）。
+
+## Open Questions
+
+- 是否统一要求 `pull.rebase=true`，还是按分支类型区分？
+- 是否需要在仓库内提供一键安全同步脚本（如 `safe-pull`）？
+- PR 模板中哪些检查项必须强制，哪些可选？
+- 是否需要为二进制资源（如媒体文件）制定单独的分支与提交流程？

openspec/changes/improve-git-collaboration-workflow/proposal.md

@@ -0,0 +1,27 @@
+## Why
+
+当前项目缺少统一、可执行的 Git 协作规范，导致 `git pull` 后频繁出现可避免冲突，以及本地未提交文件被覆盖或误处理。需要尽快建立分支、同步、提交与冲突处理的标准流程，降低协作成本并提升代码安全性。
+
+## What Changes
+
+- 新增团队级 Git 协作与同步规范，覆盖分支命名、日常同步、提交与推送、冲突处理。
+- 新增“本地改动保护”机制要求，包括 pull 前检查、stash/临时分支保护策略和高风险命令禁用约定。
+- 新增统一的 `.gitattributes` 与基础忽略策略建议，用于减少跨平台与文本归一化引发的伪冲突。
+- 新增仓库内操作手册与故障排查流程，明确遇到冲突、覆盖风险时的标准处置步骤。
+
+## Capabilities
+
+### New Capabilities
+- `git-collaboration-policy`: 定义团队分支策略、提交规范、同步与合并基线流程。
+- `local-change-protection`: 定义本地改动保护与 pull 前安全检查、回滚与恢复流程。
+- `conflict-prevention-baseline`: 定义减少无效冲突的仓库基线配置（如 `.gitattributes` 与相关规范）。
+
+### Modified Capabilities
+- 无
+
+## Impact
+
+- 影响代码与文档：`doc/` 下新增或更新协作手册，可能新增仓库根目录 `.gitattributes` 与 `.gitignore` 规则。
+- 影响开发流程：所有开发者的日常 pull/rebase/merge 操作将遵循统一流程。
+- 影响 CI/质量门禁：可选接入提交前检查或 PR 模板校验，确保流程落地。
+- 对运行时 API 与业务功能无直接破坏性变更。

openspec/changes/improve-git-collaboration-workflow/specs/conflict-prevention-baseline/spec.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Repository text normalization baseline
+The repository MUST define a `.gitattributes` baseline that normalizes text handling rules across developer environments.
+
+#### Scenario: Text file is committed from different operating systems
+- **WHEN** contributors commit text files from mixed platforms
+- **THEN** line-ending behavior MUST follow repository-defined normalization rules to avoid platform-only diffs
+
+#### Scenario: New text-like file type is introduced
+- **WHEN** a file type with line-based content is added to the project
+- **THEN** the baseline policy MUST define whether it is treated as text and how normalization applies
+
+### Requirement: Binary and generated artifact merge safety
+The repository baseline MUST identify binary or generated artifacts that should not use normal text merge semantics.
+
+#### Scenario: Binary asset is modified in parallel branches
+- **WHEN** a merge involves binary files with conflicting revisions
+- **THEN** the repository rules MUST avoid unsafe text merge behavior and require explicit conflict resolution
+
+#### Scenario: Generated output appears in a pull request
+- **WHEN** generated artifacts are changed
+- **THEN** repository ignore and tracking rules MUST determine whether those files are versioned or excluded
+
+### Requirement: Conflict resolution operational guidance
+The project MUST provide a documented conflict-resolution procedure that developers can follow consistently.
+
+#### Scenario: Developer encounters merge conflict
+- **WHEN** a sync or integration action results in conflict markers
+- **THEN** the developer MUST follow the documented resolution steps and verification checklist before completing the merge
+
+#### Scenario: Team identifies recurring conflict hotspot
+- **WHEN** the same files repeatedly conflict across iterations
+- **THEN** the process MUST require adding mitigation actions (ownership, file split, or baseline rule update) to reduce recurrence

openspec/changes/improve-git-collaboration-workflow/specs/git-collaboration-policy/spec.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Protected trunk and short-lived working branches
+The repository workflow MUST require all feature development to happen on short-lived branches, and trunk branches MUST be integrated through reviewed pull requests.
+
+#### Scenario: Developer starts new work item
+- **WHEN** a developer starts implementation for a new task
+- **THEN** the developer MUST create and use a `feature/*` or `fix/*` branch instead of committing directly to trunk
+
+#### Scenario: Code is merged to trunk
+- **WHEN** a branch is ready for integration
+- **THEN** the change MUST be merged through a pull request with review instead of direct push to trunk
+
+### Requirement: Standard daily sync flow
+The team sync process MUST use a consistent sequence (`status` check, `fetch`, then branch update) to reduce avoidable merge conflicts.
+
+#### Scenario: Branch is up to date before coding
+- **WHEN** a developer begins or resumes work
+- **THEN** the developer MUST verify working tree status and synchronize the branch using the documented standard sequence
+
+#### Scenario: Shared branch update occurs
+- **WHEN** remote commits are detected on the tracked base branch
+- **THEN** the developer MUST update local branch history using the defined sync strategy before continuing new commits
+
+### Requirement: Consistent commit and integration checkpoints
+The workflow MUST define minimum checkpoints for commit quality and pull request readiness before integration.
+
+#### Scenario: Developer prepares to push
+- **WHEN** local commits are ready to publish
+- **THEN** commit messages and change grouping MUST follow the repository contribution policy
+
+#### Scenario: Pull request is opened
+- **WHEN** a pull request is submitted for review
+- **THEN** it MUST include required context (scope, impact, validation evidence) defined by the collaboration policy

openspec/changes/improve-git-collaboration-workflow/specs/local-change-protection/spec.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Pull safety check for local modifications
+The workflow MUST require developers to inspect and protect local modifications before any pull, rebase, or branch switch operation.
+
+#### Scenario: Working tree contains uncommitted changes
+- **WHEN** a developer is about to run a sync operation and local changes exist
+- **THEN** the process MUST require explicit protection through commit or stash before sync continues
+
+#### Scenario: Working tree is clean
+- **WHEN** a developer runs pre-sync checks and no local changes exist
+- **THEN** the sync operation MAY proceed directly using the standard update flow
+
+### Requirement: Recoverable stash and temporary backup strategy
+The workflow MUST define a recoverable backup path for temporary local work, including naming and restore steps.
+
+#### Scenario: Developer parks in-progress work
+- **WHEN** a developer cannot commit current changes but must synchronize first
+- **THEN** the workflow MUST support creating a named stash or temporary backup branch with restoration instructions
+
+#### Scenario: Developer restores protected changes
+- **WHEN** sync is complete and in-progress work needs to be resumed
+- **THEN** the workflow MUST provide deterministic restore steps and conflict-handling guidance
+
+### Requirement: High-risk command guardrails
+The collaboration policy MUST define restricted destructive Git commands and required safeguards before any forced history or workspace reset action.
+
+#### Scenario: Developer considers destructive cleanup
+- **WHEN** a developer plans to use commands that can discard local changes
+- **THEN** the workflow MUST require explicit confirmation and a documented recovery point first
+
+#### Scenario: Accidental overwrite risk is identified
+- **WHEN** a potential overwrite or data-loss situation is detected
+- **THEN** the workflow MUST direct the developer to the documented recovery SOP instead of continuing destructive operations

openspec/changes/improve-git-collaboration-workflow/tasks.md

@@ -0,0 +1,25 @@
+## 1. 协作规范与文档落地
+
+- [x] 1.1 在 `doc/` 新增 Git 协作总览文档，明确分支模型（`feature/*`、`fix/*`、主干 PR 合入）。
+- [x] 1.2 编写“日常同步 SOP”，固化 `status -> fetch -> rebase/merge` 标准流程与适用边界。
+- [x] 1.3 编写“冲突处理 SOP”，定义冲突定位、手工解决、验证与提交步骤。
+- [x] 1.4 编写“本地改动恢复 SOP”，覆盖 `stash` 命名、恢复、误操作回滚与应急路径。
+
+## 2. 仓库基线配置
+
+- [x] 2.1 新增或更新仓库根目录 `.gitattributes`，定义文本归一化和关键文件类型策略。
+- [x] 2.2 审核并更新 `.gitignore`，补充生成物与本地环境噪音文件规则。
+- [x] 2.3 对二进制或不可安全文本合并文件补充策略说明，并在文档中标注处理方式。
+
+## 3. 本地改动保护机制
+
+- [x] 3.1 在协作文档中定义 pull/rebase 前强制检查项（工作区是否干净、是否需要 commit/stash）。
+- [x] 3.2 定义高风险命令红线（如 `reset --hard`、破坏性 checkout）和使用前置条件。
+- [x] 3.3 补充“临时备份分支”与“命名 stash”规范，确保未完成改动可追踪、可恢复。
+
+## 4. 团队流程对齐与验证
+
+- [x] 4.1 更新 PR 模板或检查清单，加入协作流程必填项（同步方式、冲突处理、验证记录）。
+- [ ] 4.2 组织一次试运行（1-2 个迭代），收集团队冲突案例与本地覆盖风险案例。
+- [ ] 4.3 根据试运行反馈修订文档与策略，形成 v1.0 稳定协作规范。
+- [x] 4.4 在变更说明中记录最终采用规则、已知限制与后续优化计划。

scripts/git-safe-sync.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_BRANCH="${1:-main}"
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "Not a git repository"
+  exit 1
+fi
+
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+if [ "$CURRENT_BRANCH" = "HEAD" ]; then
+  echo "Detached HEAD is not supported by this script"
+  exit 1
+fi
+
+if [ "$CURRENT_BRANCH" = "$BASE_BRANCH" ]; then
+  echo "Refusing to run on base branch: $BASE_BRANCH"
+  echo "Please switch to a feature/fix branch first."
+  exit 1
+fi
+
+if [ -n "$(git status --porcelain)" ]; then
+  STASH_NAME="$(date +%F)-${CURRENT_BRANCH}-safe-sync"
+  echo "Working tree is dirty, stashing as: ${STASH_NAME}"
+  git stash push -u -m "$STASH_NAME" >/dev/null
+  STASHED=1
+else
+  STASHED=0
+fi
+
+echo "Fetching latest refs..."
+git fetch origin --prune
+
+echo "Rebasing ${CURRENT_BRANCH} onto origin/${BASE_BRANCH}..."
+git rebase "origin/${BASE_BRANCH}"
+
+if [ "$STASHED" -eq 1 ]; then
+  echo "Restoring stashed changes..."
+  git stash pop || {
+    echo "stash pop has conflicts; resolve manually, then continue."
+    exit 2
+  }
+fi
+
+echo "Safe sync done."