AGENTS.md git:20260803.71f8be9A

Immutable. This exact content is served forever at /api/v1/blob/25026b4f90047c1a.

# AGENTS.md — 开发规范

所有脚本、模块、工具的开发规范。编码时遵循此规范，确保产出可组合、可观测、可复现。

## 编码规范

### Frida 脚本 (JavaScript)

- 语言：JavaScript（Frida QuickJS / V8），非 Node.js，无 `require`、无 npm
- 文件编码：UTF-8 无 BOM
- 缩进：2 空格，不混用 Tab
- 变量名 camelCase，常量 UPPER_SNAKE_CASE
- 函数单一职责，单个 hook 逻辑不超过 50 行
- 不写注释，除非逻辑不直观需要解释 why
- 使用 `utils.js` 提供的工具函数，不重复实现

### Python 工具

- Python 3.9+，使用 frida Python binding
- 配置通过 dict 注入，不硬编码路径/参数
- 模板：`scripts/templates/analysis.py`

### bat 检测脚本

- 放在 `tools/` 目录
- 结构化输出，方便截图取证
- 前置条件在脚本头部注释说明

## 模块结构

```
scripts/
├── core/utils.js        ← 始终首个加载，提供公共工具
├── monitors/            ← 纯观测，不修改行为
├── bypass/              ← 主动干预，修改 app 行为
├── checklist/           ← 检测清单脚本
└── templates/           ← 模板，复制后修改使用
```

新模块导出标准接口：

```javascript
var CONFIG = { ... };
if (typeof CONFIG_OVERRIDE !== 'undefined') {
    Object.assign(CONFIG, CONFIG_OVERRIDE[模块名] || {});
}
```

## Frida API 约定

- **Hook 前先检查目标是否存在**：`Java.use()` 前用 `Java.available`，`Module.findExportByName()` 前用 `Module.findBaseAddress()`
- **大量数据用 `send()` 而非 `console.log()`**：`send()` 走 channel，`console.log()` 走 stdout，大数据会丢
- **Interceptor.attach 比 Interceptor.replace 安全**：replace 替换原函数，签名不匹配会崩
- **Native callback 必须持有引用**：`new NativeCallback(...)` 赋值给全局变量，否则 GC 回收后崩溃
- **Stalker 只在必要时用**：性能开销大，用 `Interceptor.attach` + `Thread.backtrace()` 能解决的不要 Stalker

## 软件工程原则

- **单一职责**：一个模块做一件事，不要把监控和绕过混在一起
- **可组合**：模块通过 `-l` 参数组合，不互相依赖
- **可观测**：所有 hook 点必须有日志输出，不能静默吞掉
- **可复现**：脚本能在其他设备上跑，不依赖特定路径硬编码
- **最小权限**：只 hook 需要的目标，不做全量扫描除非明确要求

## Karpathy 编码准则

写 Frida Agent 脚本时遵循 `karpathy-guidelines` skill 的 4 条原则：

1. **Think Before Coding** — 不假设，暴露不确定性。hook 前先确认目标类/方法存在。
2. **Simplicity First** — 最少代码解决问题。不写投机性 hook，不加未请求的功能。
3. **Surgical Changes** — 只改必须改的。修改现有模块时不顺手重构，匹配已有风格。
4. **Goal-Driven Execution** — 定义可验证的成功标准。hook 有输出 = 成功，无输出 = 需排查。

## 反馈协议

分析过程中遇到以下情况时，往 `feedback/FEEDBACK.md` **追加**一条（不改已有条目）：

- 决策树某个分支走不通或没覆盖
- 模块崩溃 / 无输出 / 逻辑错
- 发现需要但不存在的能力
- AGENTS/SKILL 说明误导了判断

字段约束：
- 类型限 5 种：`decision-tree` / `module-bug` / `missing-module` / `doc` / `tool`
- 复现**必须**给完整 `frida` 命令（开发时原样跑）
- 状态默认 `open`，不自行关闭

## 不重复造轮子

- 写新模块前先查 `scripts/` 是否已有可复用的
- `utils.js` 已有日志格式化、hexdump、backtrace 解析，直接调用
- 配置走 `CONFIG_OVERRIDE` 机制，不硬编码
- 检测类脚本放 `checklist/`，监控类放 `monitors/`，绕过类放 `bypass/`

## 集成新检测项

把新的检测能力集成到 skill 时：

1. 判断类型：Frida 脚本 → `scripts/`，Python 工具 → `tools/` 或 `templates/`，bat 脚本 → `tools/`
2. 遵循上述模块规范（CONFIG、CONFIG_OVERRIDE）
3. 更新 SKILL.md 决策树和模块目录
4. 更新 SKILL.md 常用组合速查表
5. 添加反馈条目（如有）