Skip to content

Latest commit

 

History

History
115 lines (97 loc) · 8.81 KB

AGENTS.md

File metadata and controls

115 lines (97 loc) · 8.81 KB

DYYY AI Agent 提示文档

本项目是基于 Theos/Logos 的抖音 35.1.0 UI 调整 Tweak。此文档供 AI Agent 或新同学快速理解代码上下文与开发规范，回答需求时请严格按照既有模式执行。

工程关键点

  • Hook 入口：DYYY.xm 负责 Feed、浮窗、全局透明度与 Tab Bar 高度等通用 Hook；DYYYSettings.xm 负责抖音设置页相关 Hook（AWESettingBaseViewController、AWELeftSideBarWeatherLabel 等）并构造 DYYY 自定义设置。
  • 业务核心：DYYYManager 统一处理媒体下载、批量任务、Live Photo/GIF/WebP 转换及保存流程，内部维护 NSOperationQueue、NSCache 和下载任务字典；DYYYSettingsHelper 管理设置依赖、入口查找、用户协议弹窗；DYYYUtils 处理 IP 属地、颜色、窗口查找等可复用逻辑。
  • UI 组件：所有自定义视图/弹窗（如 DYYYBottomAlertView、DYYYFloatSpeedButton、DYYYAboutDialogView 等）都有 .h/.m 配对文件，并在设置控制器中组合使用。
  • 模型/数据：CityManager 负责本地城市映射及 GeoNames API 缓存；DYYYConstants.h、DYYYSettingsHelper中定义的 Key 控制远程配置、ABTest、依赖关系。
  • AwemeHeaders：项目依赖的抖音私有类、Category 声明、宏定义都集中在 AwemeHeaders.h 中，供整个 tweak 引入。

类路径速查（按 UI/功能分组）

  • 入口 Hook / 控制器
    • DYYY.xm、DYYYSettings.xm：全局 Hook、设置页 Hook。
    • DYYYSettingViewController.(h/m)：自定义设置主界面。
    • DYYYSettingsHelper.(h/m)：设置项依赖、入口、协议弹窗。
  • 业务/下载
    • DYYYManager.(h/m)：下载、合成、缓存、授权。
    • CityManager.(h/m)：城市映射与 GeoNames 缓存。
    • AWMSafeDispatchTimer.(h/m)：安全延时定时器。
  • 通用工具/常量
    • DYYYUtils.(h/m)：窗口/颜色/路径等工具。
    • DYYYConstants.h：Keys、URL、通知名。
  • 设置页复用 UI（按交互类型）
    • 列表/选择：DYYYKeywordListView.(h/m)、DYYYOptionsSelectionView.(h/m)、DYYYFilterSettingsView.(h/m)。
    • 输入/图标配置：DYYYCustomInputView.(h/m)、DYYYIconOptionsDialogView.(h/m)、DYYYImagePickerDelegate.(h/m)、DYYYBackupPickerDelegate.(h/m)。
    • 弹窗/提示：DYYYBottomAlertView.(h/m)、DYYYConfirmCloseView.(h/m)、DYYYAboutDialogView.(h/m)、DYYYToast.(h/m)。
  • 浮窗与快捷操作
    • 漂浮按钮：DYYYFloatSpeedButton.(h/m)、DYYYFloatClearButton.(h/xm)。
    • 长按/面板：DYYYLongPressPanel.xm、DYYYBottomAlertView.(h/m)（复用提示）。
  • 辅助代理
    • DYYYImagePickerDelegate.(h/m)、DYYYBackupPickerDelegate.(h/m)：统一封装系统 Picker 逻辑。
    • DYYYCustomInputView.(h/m)：文本输入。
  • ABTest / 远程配置
    • DYYYABTestHook.(h/xm)：抖音 ABTest 注入。

(按上述分组定位 .h/.m/.xm 文件，可快速找到对应 UI 或业务类。若新增类，请将文件放入同类路径并在这里补充。)

开发规范

1. 头文件管理

  1. 所有新增的抖音类/方法声明必须写入 AwemeHeaders.h，保持集中管理，避免在其他文件里散落声明。
  2. 自定义 UIView Category 或辅助宏同样放在 AwemeHeaders.h，必要时按功能分段并维持已有注释风格。
  3. 外部库统一通过已有 AwemeHeaders.h 或对应 .h 引入，避免重复 import。

2. 类与函数组织

  1. 项目内业务类一律使用 DYYY 前缀，并拆分 .h/.m；Logos Hook 保持在 .xm 文件。
  2. 禁止随意添加全局 C 函数。如需新能力，请优先扩展已有类（DYYYManager、DYYYSettingsHelper、DYYYUtils 等）或创建新的 DYYYXXX 类。
  3. 使用 #pragma mark 分隔方法区域，公开方法在 .h，实现细节留在 .m。

3. Hook 实现

  1. 使用 Logos 语法 %hook/%orig/%new。对敏感类（如 AWESettingBaseViewController）需要在 dealloc 中清理 KVO/通知（示例：DYYYRemoveRemoteConfigObserver）。
  2. Hook 中新增的手势、子视图必须通过 objc_setAssociatedObject 或弱引用管理生命周期（天气控件入口即参考）。
  3. 所有 UI 写操作必须在主线程 dispatch_async(dispatch_get_main_queue(), ^{ ... })，避免阻塞抖音线程。

4. 设置/远程配置

  1. 开关值均来自 NSUserDefaults，统一使用 DYYYGetBool/DYYYGetString 等宏或 DYYYSettingsHelper 提供的方法。
  2. 复杂依赖关系写入 +[DYYYSettingsHelper settingsDependencyConfig]，包括 dependencies/conditionalDependencies/conflicts/synchronizations。
  3. 远程配置与 ABTest 的 key、URL 在 DYYYConstants.h 定义；需要新增配置时保持命名一致、添加对应注释。

5. 下载与媒体处理

  1. 与下载、文件系统相关的逻辑集中在 DYYYManager，复用单例属性（下载队列、任务映射等）。新增流程必须复用 finalizeDownloadWithFileURL: 一类的公共清理方法。
  2. 操作 PHPhotoLibrary 前必定请求授权并回到主线程触发 UI（参考 +saveMedia:mediaType:completion:）。
  3. 转码/合成任务使用 dispatch_queue_t 或 NSOperationQueue，并通过回调通知 UI 层，避免阻塞 Hook。

6. UI 与交互

  1. 所有弹窗、输入框、选择视图均继承自 UIView 或自定义控件，负责自己的布局和动画，控制器或 Hook 仅负责组装。
  2. 新的设置项请沿用 AWESetting 模型（AWESettingSectionModel、AWESettingItemModel）的构造方式，保持 icon/identifier/type 配置完整。
  3. Toast、提示统一调用 DYYYToast / DYYYBottomAlertView，不要直接 UIAlertController。

7. 资源与缓存

  1. DYYYCustomAssetsDirectory、NSCache 等资源缓存均用 dispatch_once 初始化。新增缓存时务必限制容量或提供清理策略。
  2. 自定义图片命名遵循 DYYYCustomIconFileNameForButtonName 中的映射逻辑，保持文件夹结构一致。

8. 代码风格

  1. 注释与 UI 文案使用简体中文，文案集中在对应视图或 DYYYConstants 中。
  2. 常量使用 static const 或 #define，根据是否需要编译期常量选择，命名与现有风格一致（如 kDYYYGlobalTransparencyDidChangeNotification）。
  3. 统一 clang 格式：4 空格缩进，@interface 属性使用 nonatomic, strong/assign/copy 顺序。

9. 调试与日志

  1. 允许在调试时使用 NSLog(@"[DYYY] ...")，发布前要确保不会过度刷屏。
  2. 关键路径失败时发送 UI 反馈（DYYYToast showToast:）并写 log，保证用户可感知。

10. 最终检查

  • 新增 Hook 是否受开关保护并能恢复默认行为。
  • 是否确保弱引用/通知/定时器释放（AWMSafeDispatchTimer 用于延时场景）。
  • 所有新增抖音类声明已写入 AwemeHeaders.h。
  • 是否在对应类/文件中添加函数，并补充必要头文件 import。

常见工作流示例

  1. 新增抖音 UI Hook
    • 在 AwemeHeaders.h 声明目标类/属性。
    • 于 DYYY.xm 或 DYYYSettings.xm 新增 %hook，逻辑用 NSUserDefaults 开关控制。
    • 如果需要 UI，则在 DYYY 前缀视图中实现并在 Hook 内调用。
  2. 扩展设置开关
    • 在 DYYYSettingsHelper 为依赖体系补充 key。
    • 在设置面板中创建 AWESettingItemModel，identifier 与 NSUserDefaults key 对齐。
    • 在 DYYYManager / DYYYUtils 中实现实际功能。
  3. 新增媒体处理能力
    • 在 DYYYManager 内添加对应实例/类方法，并封装异步流程。
    • 通过现有回调（下载完成、进度回调等）向 UI 传递状态。

构建与测试（make）

  • 本地验证务必执行 make clean package，确认 tweak 能在当前环境编译并生成 .deb。
  • 需要安装到设备验证时，执行 make package INSTALL=1（依赖 THEOS_DEVICE_IP 配置），编译完成后会通过 after-package 自动推送并 dpkg -i。
  • 切换不同包方案（roothide/rootless）时，通过 make package SCHEME=rootless 之类的命令指定 SCHEME，保持与目标设备一致。
  • CI 或无人值守只需运行 GITHUB_ACTIONS=true make package，脚本会自动跳过安装并将产物放在 packages/。
  • 每次回答涉及编译/测试的需求前，先说明是否已运行上述 make 命令以及结果，避免 AI 漏检构建错误。

复查清单（AI 回复前自检）

  • 需求涉及的类是否已存在，若无应在 AwemeHeaders.h 与对应 DYYY 类中创建。
  • 逻辑是否保持线程安全（UI→主线程，IO→后台）。
  • 是否引用了现有工具（DYYYUtils、DYYYSettingsHelper、DYYYToast），避免重复造轮子。
  • 是否描述了用户可见的行为及开关，确保可通过设置界面操作。

遵循以上约定可以保证 tweak 的 Hook 安全性和可维护性，也方便 AI Agent 在回答问题或生成补丁时保持统一风格。