git:20260803.71f8be9 to git:20260804.8e42194

# 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/` 目录

- 结构化输出，方便截图取证

- 前置条件在脚本头部注释说明

## 模块结构

```

```

新模块导出标准接口：

```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）

5. 添加反馈条目（如有）