# flutter-issue-autofix

**Repository Path**: simplelove520/flutter-issue-autofix

## Basic Information

- **Project Name**: flutter-issue-autofix
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: feat/initial-autofix
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Issue Autofix

`issue-autofix` 是面向 Flutter 与 React Native Issue 修复的本地工作流：用户在编码
Agent 对话中提供问题描述，以及 GitCode URL 或本机源码绝对路径；Agent 负责理解问题和
实施修改，Python Runner 负责可恢复状态、隔离工作区、验证证据、安全交付与可选 Draft PR。

目录：

- [五分钟快速开始](#五分钟快速开始)
- [安装 Runner、接入 Agent](#安装-runner接入-agentcodex-desktop-为例)
- [在 Agent 对话框提交问题](#在-agent-对话框提交问题)
- [恢复、取消和重试](#恢复取消和重试)
- [开发者指南](#开发者指南)

## 项目定位与能力边界

用户无需填写 Web 表单。在一个兼容的编码 Agent 对话中给出以下两项即可开始：

- 原始 Issue 描述；
- `https://gitcode.com/<owner>/<repo>`，或一个已存在、可读的本机源码绝对目录。

这里的“兼容 Agent”是指能够执行本机 CLI、读写文件、解析 JSON 与 `AgentTask`，并只在
Runner 分配的 `worktreePath` 中修改代码的编码 Agent。Codex Desktop Plugin/Skill 是仓库
随附的参考集成，不是唯一调用方，也不代表所有第三方 Agent 都经过了兼容性认证。Runner
本身不启动嵌套 Agent，也不直接调用模型 API。

Runner 管理隔离 worktree 或目录快照、状态恢复、命令策略、red/green 证据、构建、设备
验证、secret scan、source-specific delivery，以及适用时的 GitCode Draft PR。当前边界为：

- 远程输入仅支持 credential-free `https://gitcode.com/<owner>/<repo>` URL；GitHub 与 SSH
  URL 不受支持。
- 本地 Git 输入必须 clean。修复发生在隔离 worktree，原 checkout 不会被直接编辑；成功
  交付的是与已验证 tree 精确对应的 commit。
- 普通非 Git 目录会复制到隔离工作区。验证成功后，Runner 才复核原目录指纹、创建 private
  backup，并通过 journaled writeback 回写；失败时按 journal 回滚或报告人工恢复要求。
- Android 支持 Emulator 与已授权 physical device；iOS 自动化覆盖 Simulator，不自动配置
  iOS physical-device signing。

> 工具可发现、fixture 测试通过，并不证明某个真实业务 App 已修复。真实结果还取决于问题能否
> 稳定复现、项目依赖与构建环境是否完整，以及目标设备场景是否可自动执行。

## 五分钟快速开始

以下路径从源码准备 Runner；需要 macOS、Python 3.12、`uv` 与 Git：

```bash
uv sync --extra dev
uv run autofix doctor --json
uv build
uv tool install --python 3.12 dist/issue_autofix-0.1.0-py3-none-any.whl
autofix --help
```

然后选择接入方式：

```bash
# Codex Desktop 参考集成：把返回的 bundlePath 作为本地 Plugin 目录
autofix bundle-path --json

# 其他 shell/file-capable Agent：使用同一 CLI、JSON、AgentTask 协议
autofix start --help
```

最后在 Agent 对话框提供问题描述和一个 source。例如：

```text
请修复这个问题：Android 14 上从详情页返回后偶发白屏。
源码：https://gitcode.com/acme/mobile-app
请在 Android Emulator 上复现并验证；通过全部门禁后可以创建 Draft PR。
```

或：

```text
请修复 `/Users/me/projects/mobile-app` 中从详情页返回后偶发白屏的问题，
完成验证，但不要推送分支或创建 PR。
```

Agent 会把原始描述保存到独立的 `--issue-file`，选择 `--repo-url` 或 `--source-path`
（两者必须且只能提供一个），并保存 `start --json` 返回的 `jobId`。私有仓库先按
[GitCode 凭证](#gitcode-凭证)配置 token。

## 环境和设备准备

基础要求：

- macOS；
- Python `>=3.12,<3.13`，推荐由 `uv` 管理；
- Git；
- Flutter 项目需要 Flutter SDK；
- React Native 项目需要 Node.js，以及仓库选择的 npm、Yarn 或 pnpm client；
- Android 需要 Android SDK platform tools 和至少一个 Emulator 或已授权 physical device；
- iOS Simulator 需要 Xcode command-line tools 与可用 Simulator。

先运行：

```bash
autofix doctor --json
```

Android 可用性可用 `adb devices -l` 复核：Emulator 应已启动，physical device 应为
`device`，`offline` 或 `unauthorized` 会被拒绝。iOS 可用性可用
`xcrun simctl list devices --json` 复核；当前 Runner 只自动执行 Simulator build/run，
不会修改 physical device 的证书或 provisioning。

`doctor` 成功只说明相关工具或设备可被发现。它不等于依赖安装成功、业务测试通过、App 构建
成功或目标 Issue 已在设备上修复。

## 安装 Runner、接入 Agent（Codex Desktop 为例）

### 从源码开发或安装 wheel

开发仓库中运行：

```bash
uv sync --extra dev
uv run autofix --help
```

安装构建产物：

```bash
uv build
uv tool install --python 3.12 dist/issue_autofix-0.1.0-py3-none-any.whl
autofix doctor --json
```

### 通用 Agent bootstrap

Agent 必须执行本机 `autofix` 命令、解析 `--json` 与 Runner 生成的 `AgentTask`，保留实际
JSON 字段 `jobId`，只修改 `worktreePath`，并严格按 `next`/`agent-complete` 推进同一个任务。
下面是 Agent-neutral 协议示例，不包含任何特定 Agent 的专有语法：

```bash
# SOURCE_FLAG 只能是 --repo-url 或 --source-path；绝不能同时提供。
ISSUE_FILE=/absolute/path/issue.txt
SOURCE_FLAG=--source-path
SOURCE_VALUE=/absolute/path/to/source

autofix doctor --json
START_JSON="$(autofix start "$SOURCE_FLAG" "$SOURCE_VALUE" \
  --issue-file "$ISSUE_FILE" --json)"
AUTOFIX_JOB_ID="$(printf '%s' "$START_JSON" | python -c \
  'import json,sys; print(json.load(sys.stdin)["jobId"])')"
printf '%s\n' "$AUTOFIX_JOB_ID" > ./autofix-job-id.txt

# 每次只推进一个可审计阶段，并在 Agent/应用重启后继续使用同一 jobId。
NEXT_JSON="$(autofix next --job "$AUTOFIX_JOB_ID" --json)"
printf '%s\n' "$NEXT_JSON"
```

当返回的 `kind` 为 `agent_required` 时，Agent 必须：

1. 打开 `taskFile`，校验其中的 `jobId`、`taskId`、`handoffNonce`、`kind`、
   `worktreePath`、`expectedResultFile` 与 `deadlineAt`。
2. 只在 `worktreePath` 执行任务，不编辑原 source。
3. 将符合 `schemas/agent-result.schema.json` 的结果写到 `expectedResultFile`。
4. 使用同一 `jobId` 与返回的 `stage` 提交结果，然后继续调用 `next`：

```bash
autofix agent-complete \
  --job "$AUTOFIX_JOB_ID" \
  --stage '<reproduce-or-repair>' \
  --result-file '/absolute/path/from/expectedResultFile' \
  --json
autofix next --job "$AUTOFIX_JOB_ID" --json
```

### Codex Desktop 参考 Plugin

安装 wheel 后运行：

```bash
autofix bundle-path --json
```

把返回的 `bundlePath` 作为 Codex Desktop 的本地 Plugin 目录。该目录包含
`.codex-plugin/`、`skills/` 与 `schemas/`。从源码运行时，`bundle-path` 返回仓库根目录。
这一命令专用于 Codex 参考集成；Runner CLI、JSON contracts 与 `AgentTask` 协议本身保持
Agent-neutral。详细安装说明见 [docs/installation.md](docs/installation.md)。

## GitCode 凭证

公共仓库 clone 和验证不需要 token。私有仓库访问或创建 Draft PR 前，为 repository owner
配置 operating-system keychain 中的 token：

```bash
autofix credential-set --owner acme --username your-gitcode-login
autofix credential-status --owner acme --json
```

`credential-set` 会隐藏输入并要求确认；`--username` 可选，未提供时使用 owner。不要把 token
写入 repository URL、命令参数、shell history、Issue 描述、日志或 `.autofix.yml`。

本地非 Git 目录不需要 GitCode 凭证。本地 Git 始终先交付 verified commit；只有检测到
credential-free GitCode HTTPS remote 且用户允许发布时，才具备 push/Draft PR capability。
remote 缺失或不受支持时，publication 为 `skipped`，不会把已验证的本地交付误报为失败。

## 在 Agent 对话框提交问题

自然语言输入应包含问题描述和唯一 source；还可给出 base branch、设备偏好、测试账号说明或
发布偏好。`--base-branch` 只适用于 Git source。只有缺少继续运行所需的关键输入时，Agent
才应请求补充，而不是启动 Web intake 或另一个 Agent 流程。

三类 source 的处理差异如下：

| 输入 | 前置条件 | 隔离方式 | 原目录/原仓库 | 验证后本地交付 | 远程发布 |
| --- | --- | --- | --- | --- | --- |
| `--repo-url` | credential-free GitCode HTTPS URL | mirror + isolated worktree | 远程默认不变 | verified candidate；无需回写本机原目录 | capability 与 gates 通过时 push 并创建 Draft PR |
| local Git `--source-path` | 已存在的 absolute directory，Git 状态 clean | isolated Git worktree | 原 checkout 不直接编辑 | 创建与 verified tree 精确一致的 commit | 仅 GitCode HTTPS remote 可发布；缺失/unsupported 时 `skipped` |
| non-Git `--source-path` | 已存在、可读且通过路径安全检查的 absolute directory | authenticated snapshot/copy | Agent 不直接编辑；交付前复核指纹 | verified copy + private backup + journaled writeback | `not_applicable` |

### 公共 GitCode 仓库

```text
请修复这个 Flutter 问题：Android 14 从详情页返回后白屏。
仓库：https://gitcode.com/acme/mobile-app
请自动选择可用设备；完成 red/green、构建和设备验证后，可以创建 Draft PR。
```

### 私有 GitCode 仓库

```text
请修复私有仓库 https://gitcode.com/acme/private-mobile 中登录后崩溃的问题。
开始前先检查 owner `acme` 的 GitCode 凭证；使用 base branch `release/2.x`，
并在 Android Emulator 上验证。通过全部门禁后创建 Draft PR。
```

Agent 应调用 `credential-status --owner acme --json`；缺少凭证时报告最小外部操作，不应索要
或回显 token。

### clean 本地 Git 目录

```text
请修复 `/Users/me/projects/mobile-app` 中从详情页返回后白屏的问题。
这是 clean Git checkout；请在隔离 worktree 工作，不要修改原 checkout。
优先使用 Android physical device `R58M123456A` 验证。
```

成功后应分别报告 exact verified commit 与 publication 状态。若 origin 是 GitCode HTTPS，
Runner 才可能 push/Draft PR；其他 origin 或无 origin 时 publication `skipped`。

### 普通非 Git 目录

```text
`/Users/me/scratch/mobile-app` 不是 Git 仓库。
请修复列表刷新后重复显示的问题，在隔离副本中验证；验证通过后安全回写原目录。
```

Agent 只编辑 Runner 返回的 `worktreePath`。目录验证成功后，Runner 复核 baseline fingerprint，
保留 `verifiedCopyPath` 和 `backupPath`，再执行 journaled writeback；如果用户并发修改了原目录，
交付会阻塞而不是强制覆盖。

### `no-publish`

```text
请修复 `/Users/me/scratch/mobile-app` 中的启动崩溃并完成 Android 验证，
但不要推送分支或创建 PR。
```

Agent 使用 `--no-publish`。它只禁用 remote branch/PR publication，不跳过验证，不禁用 local
Git verified commit，也不禁用 non-Git 目录的安全写回。

更多完整对话见 [docs/conversation-examples.md](docs/conversation-examples.md)。

## 自动修复流程与结果解读

Runner 与 Agent 沿以下顺序推进：

1. `preflight`：检查输入、工具、配置与设备可见性。
2. `source prepare`：创建隔离 worktree 或 authenticated directory snapshot。
3. `baseline`：确认修复前项目基线可用。
4. `reproduce/red`：Agent 加入最小回归；Runner 只接受匹配问题的 assertion failure。
5. `diagnose/fix`：Agent 定位 root cause 并做最小修改。
6. `freeze candidate`：冻结候选 tree 与变更范围。
7. `green twice`：用与 red 相同的 targeted check 连续通过两次。
8. `build` 与 `device verification`：执行 static analysis、项目测试、目标 build 和设备 smoke。
9. `latest-base verification`：在最新 base 上重放并重新验证。
10. `secret scan` 与 `change policy`：检查敏感信息、精确文件及变更限制。
11. `verified result` 与 `source-specific delivery`：生成报告，并按 source 类型交付。
12. 仅适用且允许时执行 GitCode push 与 Draft PR。

解读结果时不要混淆以下证据：

| 信号 | 能证明什么 | 不能证明什么 |
| --- | --- | --- |
| `doctor` 成功 | 本机工具或设备可被 Runner 发现 | 业务项目可以构建、Issue 已修复 |
| repository fixture 测试成功 | 仓库内合成样例的确定性流程通过 | 真实 remote、真实 emulator/Simulator/physical device 或业务 App 已通过 |
| 本次业务任务 gates 通过 | 绑定的命令、tree hash、build 与实际记录的 device evidence 通过 | 任意视觉行为正确、人工 review 已完成 |
| local delivery 成功 | local Git exact verified commit，或 non-Git backup/writeback/摘要核对完成 | 已经远程发布 |
| Draft PR 创建成功 | publish gates 通过并创建/复用了 Draft PR | PR 已人工审查、merge 或 deploy |

最终以 `reportPath` 指向的 report 为准，并分别读取 `sourceKind`、`deliveryStatus`、
`publicationStatus`、`publishDecision`、`finalCommit`、`verifiedCopyPath`、`backupPath`、
`gates` 和 `deviceRuns`。`completed` action 还可能返回 `deliveryPath`、`backupPath` 与
`pullRequestUrl`；字段缺失或为 `null` 时不要自行推断成功。

## 常用 CLI

所有命令都支持 `--help`；标注的命令支持 `--json` machine-readable output。

| 命令 | 用途 | 常见调用 |
| --- | --- | --- |
| `doctor` | 检查本机 Runner prerequisites | `autofix doctor --json` |
| `bundle-path` | 输出 Codex reference Plugin bundle 目录 | `autofix bundle-path --json` |
| `credential-set` | 在 OS keychain 存储 owner-scoped GitCode token | `autofix credential-set --owner acme --username login` |
| `credential-status` | 只检查 token 是否存在，不显示 token | `autofix credential-status --owner acme --json` |
| `start` | 创建 recoverable job | `autofix start --source-path /abs/src --issue-file /abs/issue.txt --json` |
| `status` | 查看当前 job state | `autofix status --job <job-id> --json` |
| `next` | 最多推进一个 auditable stage | `autofix next --job <job-id> --json` |
| `retry` | 从 Runner 记录的 safe stage 重试 | `autofix retry --job <job-id> --stage <stage> --json` |
| `cancel` | 取消运行中的 job | `autofix cancel --job <job-id> --json` |
| `agent-complete` | 校验并记录当前 Agent result | `autofix agent-complete --job <job-id> --stage repair --result-file /abs/result.json --json` |
| `publish-check` | 只读评估 publish gate | `autofix publish-check --job <job-id> --json` |
| `publish` | 发布 verified candidate 并创建/复用 Draft PR | `autofix publish --job <job-id> --json` |

`start` 的核心形式为：

```bash
autofix start \
  --repo-url https://gitcode.com/owner/repository \
  --issue-file /absolute/path/issue.txt \
  --base-branch main \
  --platform android \
  --device-kind simulator \
  --json

# 或者使用 --source-path，不能与 --repo-url 同时提供：
autofix start \
  --source-path /absolute/path/to/source \
  --issue-file /absolute/path/issue.txt \
  --device-id emulator-5554 \
  --no-publish \
  --json
```

完整 option、`retry --stage` 的合法 enum 和默认值以当前
`autofix <command> --help` 为准。

## 恢复、取消和重试

- 环境或设备未就绪：先修复 `doctor --json` 报告的工具或设备问题，再按 Runner 返回的
  safe stage 操作。
- Agent 或应用重启：保存并复用 `jobId`；先运行
  `autofix status --job <job-id> --json`，再继续同一个 AgentTask 或调用 `next`。不要为同一
  repair 新建第二个 job。
- job 被 `blocked`：保留触发 blocker 的原始 `next --json` 输出；它的 `BlockedAction` 公开
  `reasonCode`、`stage`、`message` 与 `recoverable`。只执行 `message` 要求的最小外部操作；
  `BlockedAction.stage` 和 `recoverable` 只是 blocker evidence，不是通用 retry target 或重试授权。
  不要从后续 `status` 或这两个字段猜测 retry target。

<!-- contract: BlockedAction -->
```json
{
  "kind": "blocked",
  "jobId": "job_20260804090000_ab12cd34",
  "stage": "source_delivery",
  "reasonCode": "writeback_failed",
  "message": "writeback rolled back",
  "recoverable": true
}
```

- `status` 返回当前 `JobStatus`，可查看 `stage`、`blockReason`、source/delivery/publication
  状态和已交付路径；
  failure 之后当前 `stage` 通常是 `failed`。`status` 不提供 retry target，也不返回失败事件的
  previousStage。下面是关注字段节选，不是完整输出：

<!-- contract: JobStatus -->
```json
{
  "stage": "failed",
  "blockReason": "writeback_failed",
  "sourceKind": "local_directory",
  "deliveryStatus": "rolled_back",
  "publicationStatus": "not_applicable",
  "deliveryPath": null,
  "verifiedCopyPath": "/absolute/runtime-home/jobs/job_example/artifacts/verified-source",
  "backupPath": "/absolute/runtime-home/jobs/job_example/backup"
}
```

- `autofix retry --stage` 是高级且受校验的操作：只能使用当前 `JobStore.retry`
  接受的 safe target，错误 target 会被拒绝，也不能跳过失败 gate。Agent-stage
  failure 会按下表规范化；表中是当前稳定的状态机映射，不是从 blocker 字段推断的规则：

  | 失败前 stage | 规范化 safe target |
  | --- | --- |
  | `reproduce_agent_required` | `baseline_verified` |
  | `repair_agent_required` | `regression_red_verified` |

  其他失败只能使用 Runner/Agent 集成或维护者明确给出的 safe target，再调用
  `autofix retry --job <job-id> --stage <stage> --json`。若原始 blocked 输出已丢失，
  `status` 无法补回 retry target，也不能根据 `status.stage`、`BlockedAction.stage` 或
  `recoverable` 猜测；保留 job artifacts 并请求维护者确认。
- Agent 完成修改：把 schema-valid result 写到 `expectedResultFile`，然后调用
  `agent-complete`，不能自行宣布 green。
- 需要停止：立即调用 `autofix cancel --job <job-id> --json`。取消保留已有证据，不会发布
  未验证的 partial result。
- 发布前诊断：`publish-check` 是只读操作。只有 job 已处于 `publish_check` 且返回
  `applicable: true`、`allowed: true` 时，才可调用 `publish`。完整返回字段如下：

<!-- contract: PublishCheckResult -->
```json
{
  "applicable": true,
  "allowed": true,
  "reasons": [],
  "reportPath": "/absolute/runtime-home/jobs/job_example/artifacts/final-report.md"
}
```

本地非 Git 特别处理：

- `source_changed`：原目录 baseline fingerprint 已变化；不覆盖并发修改。恢复原指纹后，
  只按 Runner 或维护者明确给出的 safe target 重试，或从当前源码启动一个新任务。
- `writeback_failed` 或 writeback 期间中断：先用同一 runtime home 执行 `status` 查看当前
  `deliveryStatus`、`verifiedCopyPath` 与 `backupPath`，再仅按明确的 Runner 提示执行
  `retry`/`next`；用户要求停止时使用 `cancel`。`next` 进入
  `source_delivery` 和 `cancel` 完成取消前都会优先恢复未完成的 writeback。
- `recovery_required`：无论出现在 preparation 还是 delivery，都绝不能 `retry`；不要
  手工编辑原 source、backup 或 journal。保留整个 job runtime directory，交给维护者按
  受认证的 recovery evidence 处理。

`writeback-journal.json` 不是 `ValidationReport`、final report、`status` 或 `completed` action
的公开字段，而是 Runner private runtime artifact。当前实现中的位置为
`<home>/jobs/<jobId>/artifacts/writeback-journal.json`；只有实际开始 writeback 后才可能存在。
默认 `<home>` 是 `~/.codex/issue-autofix`。如果 `start` 使用了自定义 `--home`，后续
job-scoped 命令也必须显式传入同一个 absolute runtime home；当前没有查询某个 `jobId`
所属 runtime home 的 CLI。该路径只用于保留和受控诊断，不要手工编辑。常用恢复调用为：

```bash
autofix status --job <job-id> --home /absolute/runtime-home --json
autofix next --job <job-id> --home /absolute/runtime-home --json
autofix cancel --job <job-id> --home /absolute/runtime-home --json
```

并非所有失败都能自动恢复。缺少签名、不可自动化的人机交互、仓库脚本错误、私有依赖凭证
缺失或无法稳定复现时，Runner 会返回可操作的阻塞原因。详见
[docs/operations.md](docs/operations.md)。

## `.autofix.yml`

配置文件可选，位于 repository root；未知字段会被拒绝。下面字段与当前 config model 一致：

<!-- contract: AutofixConfig -->
```yaml
version: 1

project:
  root: .
  framework: auto

commands:
  flutter:
    targeted_test:
      - flutter
      - test
      - test/regression/issue_test.dart
  react_native:
    typecheck:
      - pnpm
      - run
      - typecheck

devices:
  preferred:
    platform: android
    kind: simulator
  android:
    package_name: com.example.app
    activity: .MainActivity
  ios:
    bundle_id: com.example.app

policy:
  allowed_write_globs:
    - lib/**
    - src/**
    - test/**
    - __tests__/**
    - android/**
    - ios/**
  denied_write_globs:
    - "**/*.jks"
    - "**/*.keystore"
    - "**/*.p12"
    - "**/*.mobileprovision"
    - "**/.env*"
  max_changed_files: 30
  max_changed_lines: 1500
```

`project.framework` 的 enum 为 `auto`、`flutter`、`react-native`；device `platform` 为
`android` 或 `ios`，`kind` 为 `simulator` 或 `physical`。command override 必须是 argument
array；shell string 与 shell interpreter 被拒绝。repository policy 只能收紧 Runner 的
global policy，不能放宽默认 denied globs 或扩大上限。字段、推断与优先级见
[docs/configuration.md](docs/configuration.md)。

## Flutter 与 React Native 注意事项

### Flutter

- 准备 Flutter SDK，并保证项目自身的 dependency、analyze、test 与 target-platform debug
  build 能在本机运行。
- targeted test 通常由 Flutter test runner 执行；具体 override 使用
  `commands.flutter.targeted_test` argument array。
- Android package/activity 与 iOS bundle ID 可从项目推断；推断有歧义时必须在配置中给出。

### React Native

- 准备 Node.js 和项目已选择的 npm、Yarn 或 pnpm；不要擅自切换 package manager。
- React Native command 必须使用已有 package script 或本地安装的 approved runner；
  Agent-supplied direct `node` script 与任意 executable path 会被拒绝。
- 可用 `commands.react_native.typecheck` 配置 typecheck argument array。

两类项目都可以使用 Android Emulator 或 authorized physical device。iOS 当前只自动化
Simulator；iOS physical-device signing 未被自动 provision 或修改。launch-and-observe smoke
能发现启动命令失败和常见 crash signature，但不能证明任意视觉行为正确。

## 安全模型和限制

采用本工具即表示操作者愿意执行目标仓库的 dependency、build 与 test scripts；这些脚本会以
本地用户权限运行，属于明确的 code-execution trust boundary。对第三方仓库先评估风险。

Runner 仍执行以下 fail-closed 规则：

- Issue 与 source data 按 untrusted input 处理；credential-bearing repository URL 被拒绝。
- Agent 只能修改 Runner 分配的 absolute `worktreePath`，不得直接编辑原 source。
- local Git 必须 clean；Runner 不自动 stash、discard 或混入 staged、unstaged、untracked
  用户修改。
- non-Git Agent 修改只发生在隔离副本；验证通过后才做 fingerprint check、private backup、
  journaled writeback 和必要回滚。并发修改不会被强制覆盖。
- source symlink、unresolved/external symlink、path traversal、`/`、用户 home、source/runtime
  ancestor overlap、unsafe control character 与 special file 均会拒绝或 fail closed。
- red 必须是匹配问题的 assertion failure；compile、dependency、toolchain、timeout 或任意
  non-zero exit 都不能冒充 reproduction。green 必须用同一 targeted check 连续通过两次。
- regression test 不得删除、skip、弱化或替换；change policy 限制可写路径、文件数与行数。
- macOS validation command 使用 `sandbox-exec` 将 candidate 中 tracked 与 non-ignored 文件
  设为只读。这是 write-integrity sandbox，不是完整的 network/credential sandbox。
- publish 绑定 verified Git tree hash 和 exact commit/staging；latest-base、device、secret scan
  与 change-policy gates 必须通过，只创建 Draft PR，绝不 merge 或 deploy。
- secret scan 与日志脱敏是 publish gates 的一部分，但不能替代人工安全 review。raw logs 为
  private runtime artifacts，仍可能包含仓库输出，应妥善保护与清理。
- changed binary file 和超过 2 MB 的 changed file 在 v1 中 fail closed。

完整威胁模型和已知边界见 [docs/security.md](docs/security.md)。

## 开发者指南

职责与数据流：

```mermaid
flowchart LR
    U["用户 / Agent 对话"] --> A["Agent 集成层"]
    A --> R["Python Runner"]
    R --> S["SourceAdapter"]
    S --> W["隔离 worktree / 目录快照"]
    R --> V["构建与设备验证"]
    R --> D["安全回写 / verified commit"]
    R --> P["GitCode Draft PR（适用时）"]
    W --> R
    V --> R
    R --> A
```

- Agent 集成层理解 Issue、调用 Runner、读取 `AgentTask`，并在受控 worktree 中实施
  reproduction 与 repair。Codex Desktop Plugin/Skill 是参考实现。
- Runner 负责 deterministic state machine、evidence、command/change policy、delivery 与
  publication；它不生成修复思路，也不调用模型 API。
- `SourceAdapter` 统一 `gitcode_remote`、`local_git` 与 `local_directory` 的 workspace prepare
  和 final delivery。

常用目录：

```text
src/issue_autofix/
  agent/          AgentTask 与 AgentResult handoff
  commands/       CLI command implementations
  contracts/      Pydantic/JSON contract models
  device/         Android 与 iOS providers
  framework/      Flutter 与 React Native adapters/config
  source/         source resolution、workspace、delivery/writeback
  state/          atomic state、events、locks、runtime paths
  validation/     red/green、full、device、latest-base reports
  publish/        publish policy、secret scan、GitCode Draft PR
schemas/          exported JSON Schema
skills/           Codex reference Skill bundle source
tests/            unit、integration、failure injection、e2e、device、Skill
```

核心 `JobStage` 流为：

```text
prepared → workspace_ready → baseline_verified
→ reproduce_agent_required → regression_red_verified
→ repair_agent_required → targeted_green_verified
→ full_verification → device_verification
→ latest_base_verification → source_delivery → publish_check → published
                                                        ↘ completed
```

`failed`、`cancelled`、`interrupted` 是显式状态。每次 `next` 最多推进一个阶段；任何新 adapter
或 verifier 都必须保留 closed schemas、absolute workspace boundary、exact red/green replay、
source integrity 与不可跳过的 publish gates。主要公开契约见
[schemas/issue-request.schema.json](schemas/issue-request.schema.json)、
[schemas/next-action.schema.json](schemas/next-action.schema.json)、
[schemas/agent-task.schema.json](schemas/agent-task.schema.json)、
[schemas/agent-result.schema.json](schemas/agent-result.schema.json) 与
[schemas/validation-report.schema.json](schemas/validation-report.schema.json)。

## 开发、测试、打包和发布检查

准备开发环境：

```bash
uv sync --extra dev
```

不依赖真实设备的 release checks：

```bash
uv run ruff check .
uv run mypy src
uv run pytest -m "not device" -v
uv run pytest tests/unit/contracts/test_schema_export.py -q
uv run pytest tests/skill -q
uv build
```

`tests/unit/contracts/test_schema_export.py` 校验 committed schemas 与当前 models 一致；
`tests/skill` 校验 bundled reference Skill 与 live CLI/schema contract。`uv build` 同时验证
wheel 可包含 Plugin/Skill/schemas。发布前还应在隔离环境安装构建出的 wheel，并运行：

```bash
uv tool install --python 3.12 dist/issue_autofix-0.1.0-py3-none-any.whl
autofix doctor --json
autofix bundle-path --json
```

按环境执行 device tests 与真实 App acceptance。普通 CI/e2e 中的 fixture providers 不连接
真实 GitCode remote，不访问真实 Emulator、Simulator 或 physical device；它们只能证明
orchestration 对合成 fixture 的确定性行为。真实发布前至少应让代表性的 Flutter 与 React
Native App 完成 red、两次 green、full build、目标设备、latest-base、secret scan 和 Draft PR
人工检查。详见 [docs/acceptance.md](docs/acceptance.md)。

## FAQ 与专题文档索引

### 是否需要 Web 页面或 OpenAI API key？

不需要。输入发生在编码 Agent 对话中，Runner 不提供 Web UI、不启动 hosted service，也不读取
OpenAI API key 或直接调用模型 API。

### 是否只能使用 Codex Desktop？

不是。Codex Desktop Plugin/Skill 是随仓库提供的 reference integration。其他
shell/file-capable coding Agent 只要能执行本机 CLI、解析 JSON/`AgentTask`、保留 `jobId`、
只编辑 `worktreePath`，并遵守 `next`/`agent-complete` 状态协议即可接入；这不表示第三方 Agent
已经逐一通过兼容性认证。

### 支持 GitHub、SSH、Android 真机和 iOS 真机吗？

GitHub remote 与 SSH URL 当前不受支持；远程 v1 只支持 GitCode HTTPS。Android 支持 Emulator
和 authorized physical device。iOS 支持 Simulator；iOS physical-device signing 自动化当前
不受支持。

### 三类 source 的结果写到哪里？

GitCode URL 生成 verified candidate，并在 capability 与 gates 允许时创建 Draft PR。local Git
保留原 checkout 不变，在 isolated candidate 中创建 exact verified commit；GitCode HTTPS
remote 才可能继续发布。non-Git 目录在 isolated copy 验证，并在 fingerprint check、backup 与
journal 保护下写回原目录。

### 为什么 local Git 必须 clean？为什么 non-Git 写回会阻塞？

clean 要求避免把用户 staged、unstaged 或 untracked 变更混入 candidate；Runner 不会自动
stash 或 discard。non-Git 写回前复核 baseline fingerprint，发现并发修改时阻塞，防止静默
覆盖用户的新内容。

### 为什么 red/green 如此严格？

red 证明修复前确实存在与 Issue 匹配的 assertion failure；同一 check 连续两次 green 用于
降低 flaky 或被替换测试造成的 false success。build success 本身不等于问题已修复。

### 为什么测试通过却没有 PR？

delivery 与 publication 是独立结果。可能原因包括用户选择 `--no-publish`、source 没有
GitCode HTTPS publication capability、token/permission 不可用、latest-base 或其他 publish
gate 未通过。查看 `publish-check` 的 `applicable`、`allowed`、`reasons` 和 report。

### 如何继续、恢复或取消任务？

保存 `jobId`，使用 `status` 查看现状、`next` 继续、仅在 Runner 允许时用 `retry`，用户要求
停止时用 `cancel`。`recovery_required` 时保留所有 artifact，不要自行覆盖 source。

### 可以只验证不发布吗？

可以，启动时使用 `--no-publish`。它不降低验证要求，也不禁用 local Git commit delivery 或
non-Git journaled writeback。

### `.autofix.yml` 必需吗？

不是。Runner 有默认探测与 policy；只有需要明确 project root/framework、command override、
device identifier/preference 或更严格 policy 时才添加。

专题文档：

- [安装与设备准备](docs/installation.md)
- [repository 配置](docs/configuration.md)
- [运行、恢复与 source delivery](docs/operations.md)
- [验收与证据边界](docs/acceptance.md)
- [安全模型](docs/security.md)
- [Agent 对话示例](docs/conversation-examples.md)