Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/tytsxai/autonomous-coding

autonomous-coding 汉化版，自主编码代理的中文本地化
https://github.com/tytsxai/autonomous-coding

ai-coding anthropic-fork autonomous-coding codex-cli two-agent-loop web-app-builder

Last synced: 6 days ago
JSON representation

autonomous-coding 汉化版，自主编码代理的中文本地化

Awesome Lists containing this project

README 

          
# 自主编码代理 / autonomous-coding (Codex CLI fork)



[![Release](https://img.shields.io/github/v/release/tytsxai/autonomous-coding)](https://github.com/tytsxai/autonomous-coding/releases) · [llms.txt](llms.txt) · [Changelog](CHANGELOG.md) · [Upstream (Anthropic)](https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding) · [Issues](https://github.com/tytsxai/autonomous-coding/issues)



> **关键词**:自主编码代理 · AI 自主构建 Web 应用 · Codex CLI 自主构建 · 双代理编码循环 · feature_list.json 自动迭代 · 停滞检测修复 · autonomous-coding 中文版 · Codex CLI autonomous coding fork

>

> **Keywords**: autonomous coding agent · autonomous web app builder · Codex CLI autonomous coding fork · two-agent coding loop · feature_list.json autonomous build · stagnation detection coding agent · alternative to Devin · alternative to SWE-agent



基于 Codex CLI 的自主编码代理,可自动构建完整 Web 应用。**这是 Anthropic 官方 quickstart `autonomous-coding` 的衍生分叉**,把 agent 后端从 Anthropic SDK 切到 Codex CLI(Claude 路径仍可选);加上停滞检测 + 修复代理、断点续跑、多凭证解析、Bash 白名单。



> ⚠️ **安全提示 — Codex 后端默认走「高权限」自主模式**

>

> 为了让无人值守的自主编码循环可以推进,Codex 后端在 `codex exec` 调用上固定加了 `--dangerously-bypass-approvals-and-sandbox`,允许 Codex CLI 在工作目录**执行任意 shell 命令、读写任意文件、访问任意网络**。

>

> **使用前提**:只在受信任的 *generations/* 子目录下、用受信任的 prompt 启动。不要把这个工具指向系统目录、不要用陌生人发来的 `app_spec.txt`。如果你需要更严格的命令白名单和文件系统沙箱,请改用 Claude 后端(`--backend claude`),由 `security.py` 强制白名单。



## 上游(原版)仓库



本项目源自 Anthropic 的 quickstart 示例 `autonomous-coding`：



- https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding



需要对照原始实现、查看英文说明或跟踪上游更新时，请以该上游为准。



### 跟踪上游更新（可选）



```bash

git remote add upstream https://github.com/anthropics/claude-quickstarts.git

git fetch upstream

```



## 特性



- **技能驱动** - 在 Claude Code 中输入 `/autonomous` 即可启动

- **Codex 执行** - 所有编码工作由 Codex CLI 循环完成

- **双代理模式** - 初始化代理 + 编码代理协作

- **自动持久化** - 进度保存，可随时中断继续



---



## 快速开始



### 步骤一：创建应用规范



**方式 A：交互式创建（推荐）**

```

/create-spec

```

AI 会引导你完成需求收集，自动生成 `prompts/app_spec.txt`。



**方式 B：手动编辑**



直接编辑 `prompts/app_spec.txt`，写清楚你想要的应用。



---



### 步骤二：启动自主编码



**方式 A：Claude 技能（推荐）**

```

/autonomous my_project

```



**方式 B：命令行**

```bash

python3 autonomous_agent_demo.py --project-dir generations/my_project

```



---



## 前置条件



```bash

npm install -g @openai/codex

pip install -r requirements.txt

```



> 推荐 Python 3.11+；3.10 及以下会自动使用 `tomli` 兼容解析 toml。



## 自检（开发/CI）



```bash

venv/bin/python -m compileall -q -x "venv|generations" .

venv/bin/python -m unittest discover -v -s tests

venv/bin/python test_security.py

```



## 认证配置



Codex CLI 支持多种认证方式，按优先级顺序：



1. **环境变量** - `OPENAI_API_KEY`

2. **auth.json** - `~/.codex/auth.json`

3. **第三方渠道** - `~/.codex/config.toml`（如 yunyi）



### 第三方渠道配置（推荐）



如果使用第三方激活渠道（如 yunyi），在 `~/.codex/config.toml` 中配置：



```toml

model_provider = "yunyi"

model = "gpt-5.2"



[model_providers.yunyi]

name = "yunyi"

base_url = "https://yunyi.cfd/codex"

wire_api = "responses"

experimental_bearer_token = "YOUR_TOKEN"

```



程序会自动检测并加载第三方凭证，无需设置环境变量。



---



## 命令行参数



| 参数 | 说明 | 默认值 |

|------|------|--------|

| `--project-dir` | 项目目录 | `generations/autonomous_demo_project` |

| `--max-iterations` | 最大迭代次数 | 无限制 |

| `--model` | 模型名称 | `gpt-5.2-codex` |



---



## 工作流程



### 双代理模式



1. **初始化代理（会话 1）：** 读取 `app_spec.txt`，创建包含 200 个测试用例的 `feature_list.json`，设置项目结构，并初始化 git。



2. **编码代理（会话 2+）：** 从上次会话中断处继续，逐个实现特性，并在 `feature_list.json` 中标记为通过。



### 会话管理



- 每个会话都使用全新的上下文窗口

- 进度通过 `feature_list.json` 与 git 提交持久化

- 代理在会话间自动继续（3 秒延迟）

- 按 `Ctrl+C` 可暂停；再次运行相同命令可继续



## 安全模型



本演示采用纵深防御安全策略（见 `security.py` 和 `client.py`）：



1. **OS 级沙箱：** Bash 命令在隔离环境中运行

2. **文件系统限制：** 文件操作仅限项目目录

3. **Bash 允许列表：** 仅允许特定命令：

   - 文件检查：`ls`、`cat`、`head`、`tail`、`wc`、`grep`

   - Node.js：`npm`、`node`

   - 版本控制：`git`

   - 进程管理：`ps`、`lsof`、`sleep`、`pkill`（仅限开发进程）



补充规则：

- 禁止命令替换与进程替换（如 `` `...` ``、`$(...)`、`<(...)`）以防绕过白名单

- `rm` 仅允许安全的相对路径删除（禁止 `/`、`~`、`..` 等）



不在允许列表中的命令会被安全钩子阻止。



> 注意：Codex 后端默认使用 `--dangerously-bypass-approvals-and-sandbox`（高权限）。如需更严格的沙箱与白名单，请使用 Claude 后端。



## 项目结构



```

autonomous-coding/

├── autonomous_agent_demo.py  # 主入口

├── agent.py                  # Agent 会话逻辑

├── base_client.py            # 抽象客户端接口

├── claude_client.py          # Claude SDK 后端

├── codex_client.py           # Codex CLI 后端

├── client_factory.py         # 客户端工厂

├── security.py               # Bash 命令白名单验证

├── progress.py               # 进度追踪工具

├── prompts.py                # Prompt 加载工具

├── prompts/

│   ├── app_spec.txt          # 应用规格说明

│   ├── initializer_prompt.md # 初始化会话 Prompt

│   └── coding_prompt.md      # 编码会话 Prompt

├── requirements.txt          # Python 依赖

└── .env.example              # 环境变量模板

```



## 生成的项目结构



运行后，你的项目目录将包含：



```

generations/my_project/

├── feature_list.json         # Test cases (source of truth)

├── app_spec.txt              # Copied specification

├── init.sh                   # Environment setup script

├── claude-progress.txt       # Session progress notes

├── .claude_settings.json     # Security settings

└── [application files]       # Generated application code

```



## 运行生成的应用



代理完成（或暂停）后，你可以运行生成的应用：



```bash

cd generations/my_project



# Run the setup script created by the agent

./init.sh



# Or manually (typical for Node.js apps):

npm install

npm run dev

```



应用访问地址以终端输出或 `init.sh` 为准（Vite 项目常见是 `http://localhost:5173`）。



## 命令行选项



| 选项             | 描述                   | 默认值                      |

| ---------------- | ---------------------- | --------------------------- |

| `--backend`        | 后端类型               | `codex`                     |

| `--project-dir`    | 项目目录               | `generations/autonomous_demo_project` |

| `--max-iterations` | 最大代理迭代次数       | 无限制                      |

| `--model`          | 模型名称               | Codex: `gpt-5.2-codex`，Claude: `claude-opus-4-5-20251101` |



## 自定义



### 修改应用



编辑 `prompts/app_spec.txt` 以指定要构建的不同应用。



### 调整特性数量



编辑 `prompts/initializer_prompt.md`，将“200 个特性”的要求改为较小数量以加快演示。



### 修改允许的命令



编辑 `security.py`，在 `ALLOWED_COMMANDS` 中添加或移除命令。



## N8N Webhook 集成（可选）



当测试通过时，代理可以向 N8N webhook 发送进度通知。这对于监控长时间运行的代理会话很有用。



### 设置



在 `.env` 文件中添加 webhook URL：



```bash

PROGRESS_N8N_WEBHOOK_URL=https://your-n8n-instance.com/webhook/your-webhook-id

```



### Webhook 载荷



当测试进度增加时，代理会发送一个 POST 请求，JSON 结构如下（按 N8N 的期望包装为数组）：



```json

[

  {

    "event": "test_progress",

    "passing": 45,

    "total": 200,

    "percentage": 22.5,

    "previous_passing": 42,

    "tests_completed_this_session": 3,

    "completed_tests": [

      "[Authentication] User can log in with valid credentials",

      "[Dashboard] Display user profile information",

      "[API] GET /users endpoint returns user list"

    ],

    "project": "my_project",

    "timestamp": "2025-01-15T14:30:00.000Z"

  }

]

```



### 载荷字段



| 字段                           | 类型   | 描述                                  |

| ------------------------------ | ------ | ------------------------------------- |

| `event`                        | string | 始终为 `"test_progress"`              |

| `passing`                      | number | 当前通过的测试数量                    |

| `total`                        | number | 测试总数                              |

| `percentage`                   | number | 完成百分比（0-100）                   |

| `previous_passing`             | number | 本次更新前通过的测试数量              |

| `tests_completed_this_session` | number | 自上次通知以来完成的测试数量          |

| `completed_tests`              | array  | 新通过测试的描述                      |

| `project`                      | string | 项目名称（来自 `--project-dir` 参数） |

| `timestamp`                    | string | ISO 8601 时间戳（UTC）                |



### 说明



- 通知仅在进度**增加**时发送（不会每次检查都发送）

- 如果未配置 webhook URL，不会发送通知（静默跳过）

- webhook 调用失败会记录日志，但不会停止代理



## 故障排查



**"首次运行看起来卡住了"**

这是正常现象。初始化代理正在生成 200 个详细测试用例，需要较长时间。观察 `[Tool: ...]` 输出以确认代理正在工作。



**"命令被安全钩子阻止"**

代理尝试运行不在允许列表中的命令。安全系统按预期工作。如有需要，在 `security.py` 的 `ALLOWED_COMMANDS` 中添加该命令。



**"Codex 后端不可用"**

检查凭证配置：

```bash

python3 -c "from codex_client import CodexAgentClient; print(CodexAgentClient.get_credential_info())"

```

应返回 `{'source': 'config.toml', 'provider': 'yunyi'}` 或类似信息。



**"API key 未设置"**

请确认以下任一配置：

- 环境变量 `OPENAI_API_KEY`

- `~/.codex/config.toml` 中的第三方渠道配置

- `.env` 文件中的 `ANTHROPIC_API_KEY`（Claude 后端）



## 自动闭环机制



代理具备三层自动闭环能力，无需人工干预即可完成任务：



1. **完成检测**：当 `feature_list.json` 中所有测试通过时自动停止

2. **初始化自愈**：若初始化未生成测试清单，自动重试（最多 2 次）

3. **停滞检测**：连续 5 轮无进展时进入修复模式，修复 2 轮仍无效则停止



## 已知限制



- **首次运行耗时**：初始化代理生成 200 个测试用例需 10-20 分钟

- **应用类型**：目前仅针对 Node.js/Web 应用优化

- **命令白名单**：Bash 命令受 `security.py` 白名单限制

- **上下文窗口**：每个会话使用全新上下文，不保留历史对话

- **进度依赖**：依赖 `feature_list.json` 跟踪进度，删除该文件会重置进度



## 许可



本项目基于 MIT License 开源。原始代码源自 Anthropic 的 quickstart 示例，

版权归原始作者和贡献者所有。



## Star History



[![Star History Chart](https://api.star-history.com/svg?repos=tytsxai/autonomous-coding&type=Date)](https://www.star-history.com/#tytsxai/autonomous-coding&Date)