Skip to content
Back to search

autoresearch

autodevelop: autoresearch for software development

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/smallnest--autoresearch/badge.svg)](/listings/smallnest--autoresearch)

HTML

<a href="/listings/smallnest--autoresearch"><img src="/api/listings/smallnest--autoresearch/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 508 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Autoresearch for Software Development
  2. ![](docs/autoresearch.png)
  3. > 全自动化软件开发工具,你只需负责喝茶和睡觉。
  4. > 一觉醒来,Features 全自动高质量的实现了。
  5. ![宣传视频](docs/autoresearch-promo-cn.gif)
  6. 基于 [karpathy/autoresearch](https://github.com/karpathy/autoresearch) 思想实现的通用的全自动化开发工具。支持 **GitHub Issue**、**本地 Issue** 和**百度 iCafe** 四种模式,适用于任意 Git 项目(Go、Node.js、Python、Rust、Java 等)。
  7. 使用 autoresearch 实现本项目 Issue#2:
  8. [![asciicast](https://asciinema.org/a/KdHGFHK6pcelUdPg.svg)](https://asciinema.org/a/KdHGFHK6pcelUdPg)
  9. ---
  10. ## 目录
  11. - [快速开始](#快速开始)
  12. - [前置条件](#前置条件)
  13. - [项目架构](#项目架构)
  14. - [工作流程](#工作流程)
  15. - [本地 Issue 模式](#本地-issue-模式)
  16. - [百度 iCafe 模式](#百度-icafe-模式)
  17. - [阿里云效 Codeup 模式](#阿里云效-codeup-模式)
  18. - [工具配置](#工具配置)
  19. - [与 ralph 对比](#与-ralph-对比)
  20. ---
  21. ## 快速开始
  22. ```bash
  23. # 下载项目
  24. git clone git@github.com:smallnest/autoresearch.git
  25. # 处理当前目录项目的 Issue#10
  26. autoresearch/run.sh 10
  27. # 处理指定目录项目的 Issue#10
  28. autoresearch/run.sh -p /path/to/project 10
  29. # 指定最大迭代次数为 16 次
  30. autoresearch/run.sh -p /path/to/project 10 16
  31. # 调整达标线为 90 分
  32. PASSING_SCORE=90 autoresearch/run.sh 10
  33. # 指定全局 model(所有 agent 使用 opus)
  34. AGENT_MODEL=opus autoresearch/run.sh 10
  35. # 单独指定某个 agent 的 model(优先级高于 AGENT_MODEL)
  36. AGENT_MODEL=opus AGENT_MODEL_CLAUDE=sonnet autoresearch/run.sh 10
  37. # 指定启用的 agents 及顺序(首个 agent 做初始实现)
  38. autoresearch/run.sh -a claude,codex 10
  39. # 继续处理 Issue#42,追加 10 次迭代
  40. autoresearch/run.sh -c 42 10
  41. # 处理本地 Issue #8(从 .autoresearch/issues/ 读取)
  42. autoresearch/run.sh --issues-dir=.autoresearch/issues 8
  43. # 百度 iCafe 模式(卡片 #22210)
  44. autoresearch/run.sh --issue-source=baidu --space=cloud-iCafe 22210
  45. # 阿里云效 Codeup 模式(Issue #42)
  46. autoresearch/run.sh --issue-source=codeup --codeup-token=xxx --codeup-org=123 --codeup-repo=456 42
  47. ```
  48. ## 前置条件
  49. 需要安装以下工具(按需安装):
  50. ```bash
  51. gh auth status # GitHub CLI(仅 GitHub 模式需要)
  52. icafe-cli whoami # iCafe CLI(仅百度模式需要)
  53. icode-cli whoami # iCode CLI(仅百度模式需要)
  54. curl --version # 阿里云效 Codeup 模式需要 curl
  55. which claude # Claude Code CLI
  56. which codex # OpenAI Codex CLI
  57. which opencode # OpenCode CLI
  58. which deepseek-tui # DeepSeek CLI (npm install -g deepseek-tui)
  59. ```
  60. 项目需有对应语言的构建工具(Go/Node/Python/Rust/Java)。
  61. ---
  62. ## 项目架构
  63. ![](docs/architecture.png)
  64. 核心流程:
  65. | 组件 | 说明 |
  66. |------|------|
  67. | **GitHub Issue / 本地 Issue / 百度 iCafe / 阿里云效 Codeup** | 触发输入 |
  68. | **run.sh** | 核心运行器 |
  69. | **Claude / Codex / OpenCode / Claude-Mimo / DeepSeek** | Agent 轮转审核 |
  70. | **Score ≥ 85?** | 评分门控 |
  71. | **PASS** | 自动创建 PR → 合并 → 关闭 Issue |
  72. | **FAIL** | 进入下一轮迭代修复 |
  73. Agent 轮转公式:`(iter − 1) % N`
  74. ---
  75. ## 工作流程
  76. ### 单 Issue 流程
  77. ```
  78. Issue → 首个 Agent 实现 → 轮转审核+修复 → 自动 PR → 合并 → 关闭 Issue
  79. ```
  80. - **迭代 1**: `-a` 列表中的第一个 agent 初始实现
  81. - **迭代 2+**: 所有启用的 agents 按顺序轮流审核并修复
  82. - 评分达标(默认 ≥ 85)后自动创建 PR、合并、评论并关闭 Issue
  83. ### 推荐工作流:从 PRD 到自动实现
  84. 完整端到端工作流:**PRD 生成 → Issue 拆分 → autoresearch 实现**
  85. ```
  86. PRD 生成 → Issue 拆分与创建 → 选择 Issue → autoresearch 实现 → 选择下一个 Issue → ...
  87. ```
  88. ![](docs/workflow.png)
  89. #### Step 1: 生成 PRD
  90. 使用 `/prd` skill 生成交付需求文档:
  91. ```
  92. /prd 为本项目创建一个桌面 app
  93. ```
  94. #### Step 2: 拆分为 GitHub Issues
  95. 让智能体基于 PRD 拆分 Issue:
  96. ```text
  97. 基于 PRD 中的 User Stories 拆分为细粒度 Issue,并在 GitHub 上创建这些 issue。
  98. 拆分原则:
  99. - 每个 Issue 可在单次开发会话中完成
  100. - 有明确的验收标准(checkbox)
  101. - 标注依赖关系
  102. ```
  103. #### Step 3: 选择 Issue 并自动实现
  104. ```bash
  105. ./run.sh 22
  106. ```
  107. autoresearch 会:
  108. 1. 规划阶段:拆分 subtasks(如需要)
  109. 2. 迭代实现:首个 agent 实现 → 轮转审核 → 修复 → 评分
  110. 3. 质量门禁:Build/Lint/Test + LLM 评分 ≥ 85
  111. 4. 自动收尾:创建 PR → 合并 → 评论 Issue → 关闭 Issue
  112. #### 完整示例
  113. 以本项目 Desktop App 为例:19 个 Issues (#22 ~ #40) 从 PRD 到全部实现。
  114. 详细过程见 [docs/desktop-app-prd-to-issues.md](docs/desktop-app-prd-to-issues.md)。
  115. ---
  116. ## 本地 Issue 模式
  117. 除了从 GitHub 拉取 Issue,autoresearch 还支持从项目本地目录读取 Issue 文件,无需 GitHub 即可运行。适合本地项目、内网项目或不想创建 GitHub Issue 的场景。
  118. ### 快速开始
  119. ```bash
  120. # 1. 创建 issues 目录
  121. mkdir -p .autoresearch/issues
  122. # 2. 创建 Issue 文件(命名格式:issue-NNN-描述.md)
  123. cat > .autoresearch/issues/issue-008-add-login.md << 'EOF'
  124. # 添加登录功能
  125. 实现用户登录页面,包括:
  126. - 用户名/密码输入框
  127. - 表单验证
  128. - 登录 API 调用
  129. - 错误提示
  130. EOF
  131. # 3. 运行(自动检测本地文件)
  132. ./run.sh 8
  133. ```
  134. ### Issue 文件格式
  135. - **位置**:`$PROJECT_ROOT/.autoresearch/issues/`(默认)或 `--issues-dir` 指定
  136. - **命名**:`issue-NNN-描述.md`,编号补零到 3 位(如 `issue-008-add-login.md`)
  137. - **内容**:第一个 `# 标题` 行作为 Issue 标题,其余内容作为 Issue 正文
  138. - **匹配**:CLI 传入的编号 `8` 会匹配 `issue-008-*.md` 或 `issue-8-*.md`
  139. ### 运行结束后
  140. - 代码提交到本地分支(不推送远程、不创建 PR、不合并)
  141. - 处理结果自动追加到 Issue 文件末尾:
  142. ```markdown
  143. ---
  144. ## 自动处理结果
  145. - **评分**: 92/100
  146. - **迭代次数**: 3
  147. - **实现方式**: autoresearch 多 agent 迭代 (claude codex opencode)
  148. - **分支**: feature/issue-8
  149. - **完成时间**: 2026-04-27 15:30:00
  150. - 子任务: 2/2 完成
  151. ...日志内容...
  152. 该 Issue 已由 autoresearch 自动实现。
  153. ```
  154. ### 命令行参数
  155. ```bash
  156. # 自动检测模式(默认目录下有匹配文件即生效)
  157. ./run.sh 8
  158. # 手动指定 issues 目录
  159. ./run.sh --issues-dir=.autoresearch/issues 8
  160. # 指定项目路径 + 本地模式
  161. ./run.sh -p /path/to/project --issues-dir=.autoresearch/issues 8
  162. # 组合其他参数
  163. ./run.sh --issues-dir=.autoresearch/issues 8 10 # 最多迭代10次
  164. ```
  165. ### 与 GitHub 模式对比
  166. | | GitHub 模式 | 本地模式 | 百度 iCafe 模式 |
  167. |---|---|---|---|
  168. | Issue 来源 | `gh issue view` | 本地 `.md` 文件 | `icafe-cli card get` |
  169. | 需要 `gh` CLI | 是 | 否 | 否 |
  170. | 需要 GitHub remote | 是 | 否 | 否 |
  171. | 需要 `icafe-cli` / `icode-cli` | 否 | 否 | 是 |
  172. | 推送/PR/合并 | 自动执行 | 不执行 | `push_cr` + `submit_review` |
  173. | 评论/关闭 Issue | 自动执行 | 不执行 | 自动执行 |
  174. | 结果记录 | PR 评论 + 关闭 Issue | 追加到文件末尾 | CR 评论 + 关闭卡片 |
  175. ### 模式自动切换
  176. 两种模式完全兼容,互不影响:
  177. - 有匹配的本地 Issue 文件 → 自动进入本地模式
  178. - 没有本地文件 → 走 GitHub 流程(`gh issue view` → push → PR → merge → close)
  179. 同一项目可以混合使用:
  180. ```bash
  181. ./run.sh 8 # .autoresearch/issues/issue-008-*.md 存在 → 本地模式
  182. ./run.sh 42 # 没有对应的本地文件 → GitHub 模式
  183. ```
  184. ---
  185. ## 百度 iCafe 模式
  186. 百度模式使用 [iCafe](https://icafe.baidu.com/)(卡片管理)和 [iCode](https://icode.baidu.com/)(代码评审)替代 GitHub Issue/PR 流程,适合百度内部项目。
  187. ### 前置条件
  188. ```bash
  189. # 安装并登录 icafe-cli
  190. icafe-cli login
  191. # 安装并登录 icode-cli
  192. icode-cli login
  193. # 项目 git remote 需指向 icode.baidu.com
  194. git remote -v
  195. # origin https://icode.baidu.com/path/to/repo (fetch)
  196. ```
  197. ### 快速开始
  198. ```bash
  199. # 显式指定 baidu 模式 + 空间
  200. ./run.sh --issue-source=baidu --space=cloud-iCafe 22210
  201. # 指定最大迭代次数
  202. ./run.sh --issue-source=baidu --space=cloud-iCafe 22210 16
  203. # 指定 CR 目标分支(默认自动检测远程 HEAD,回退到 master)
  204. ./run.sh --issue-source=baidu --space=cloud-iCafe --target-branch=develop 22210
  205. # 使用环境变量设置空间
  206. export ICAFE_SPACE=cloud-iCafe
  207. ./run.sh --issue-source=baidu 22210
  208. ```
  209. ### 自动检测
  210. 如果同时满足以下两个条件,即使不指定 `--issue-source=baidu`,也会自动切换到百度模式:
  211. 1. Git remote 包含 `icode.baidu.com`
  212. 2. `--space` 参数或 `ICAFE_SPACE` 环境变量已设置
  213. ```bash
  214. # 在 iCode 仓库中,设置环境变量即可自动识别
  215. export ICAFE_SPACE=cloud-iCafe
  216. ./run.sh 22210 # 自动检测为 baidu 模式
  217. ```
  218. ### 工作流程
  219. ```
  220. iCafe 卡片 → Agent 实现 → 轮转审核+修复 → icode-cli push_cr → 评分 +2 → 合入 → 关闭卡片
  221. ```
  222. 与 GitHub 模式的主要区别:
  223. | 步骤 | GitHub 模式 | 百度 iCafe 模式 |
  224. |------|------------|----------------|
  225. | 获取 Issue | `gh issue view` | `icafe-cli card get` |
  226. | Commit 消息 | `feat: implement issue #N` | `{space}-{seq} [{type}] {title}` |
  227. | 创建 PR | `gh pr create` | `icode-cli git push_cr` |
  228. | 合并 | `gh pr merge` | `icode-cli api submit_review` |
  229. | 关闭 Issue | `gh issue close` | `icafe-cli card update --status 已关闭` |
  230. | 评论 | `gh issue comment` | `icafe-cli comment create` |
  231. ### 命令行参数
  232. | 参数 | 说明 |
  233. |------|------|
  234. | `--issue-source=baidu` | 指定百度模式(也可自动检测) |
  235. | `--space=<prefixCode>` | iCafe 空间前缀代码(baidu 模式必需) |
  236. | `--target-branch=<name>` | iCode CR 目标分支(默认自动检测) |
  237. | `ICAFE_SPACE` | 环境变量,等效于 `--space` |
  238. ### 项目自定义配置
  239. 在项目目录下创建 `.autoresearch/`:
  240. ```
  241. .autoresearch/
  242. ├── agents/
  243. │ ├── codex.md # 自定义 Codex 指令
  244. │ ├── claude.md # 自定义 Claude 指令
  245. │ ├── claude-mimo.md # 自定义 Claude-Mimo 指令(不设则 fallback 到 claude.md)
  246. │ └── opencode.md # 自定义 OpenCode 指令
  247. ├── issues/ # 本地 Issue 文件(issue-NNN-描述.md)
  248. ├── program.md # 自定义实现规则与约束
  249. ├── workflows/ # 各 Issue 详细记录(自动生成)
  250. └── results.tsv # 处理结果日志(自动生成)
  251. ```
  252. ### 命令行参数
  253. | 参数 | 默认值 | 说明 |
  254. |------|--------|------|
  255. | `-p <path>` | 当前目录 | 项目路径 |
  256. | `-a <agents>` | `claude,codex,opencode` | 指定启用 agents 及顺序 |
  257. | `-c` | 关闭 | 继续模式,从上次中断的迭代继续 |
  258. | `--issues-dir=<path>` | `.autoresearch/issues` | 本地 Issue 目录(启用本地模式) |
  259. | `--issue-source=<mode>` | `github` | Issue 来源:`github` / `local` / `baidu` |
  260. | `--space=<prefixCode>` | - | iCafe 空间前缀代码(baidu 模式必需) |
  261. | `--target-branch=<name>` | 自动检测 | iCode CR 目标分支 |
  262. | `PASSING_SCORE` | 85 | 达标评分线(百分制) |
  263. | `AGENT_MODEL` | - | 全局默认 model(如 sonnet, opus, o3),不设则用 CLI 默认 |
  264. | `AGENT_MODEL_CLAUDE` | - | Claude 专用 model(优先级高于 AGENT_MODEL) |
  265. | `AGENT_MODEL_CODEX` | - | Codex 专用 model |
  266. | `AGENT_MODEL_OPENCODE` | - | OpenCode 专用 model |
  267. | `AGENT_MODEL_CLAUDE_MIMO` | - | Claude-Mimo 专用 model |
  268. | `AGENT_MODEL_DEEPSEEK` | - | DeepSeek 专用 model |
  269. | `MAX_CONSECUTIVE_FAILURES` | 3 | 连续失败停止阈值 |
  270. | `MAX_RETRIES` | 5 | 单次 agent 调用重试次数 |
  271. ### 裁剪 program.md
  272. `program.md` 包含多种语言的规范模板。使用前应根据目标项目语言裁剪,只保留相关规范以减少 token 消耗。
  273. **示例**:Go 后端项目只需保留「通用规范」和「Go 代码规范」章节,删除 Python/TypeScript/Rust/前端等无关章节。
  274. ### 文件说明
  275. | 文件 | 用途 |
  276. |------|------|
  277. | `run.sh` | 主脚本 |
  278. | `lib/agent_logic.sh` | agent 列表解析与轮转共享逻辑 |
  279. | `program.md` | 默认实现规则与约束 |
  280. | `agents/*.md` | Agent 提示词模板 |
  281. | `tests/test_agent_logic.sh` | agent 选择与顺序逻辑测试 |
  282. ---
  283. ## 阿里云效 Codeup 模式
  284. 阿里云效 Codeup 模式使用 [Codeup](https://codeup.aliyun.com/)(代码托管)替代 GitHub Issue/PR 流程,适合使用阿里云效的企业项目。
  285. ### 前置条件
  286. ```bash
  287. # 需要 Codeup Access Token
  288. # 在 Codeup 控制台 -> 设置 -> Access Token 中创建
  289. export CODEUP_TOKEN=your_token_here
  290. # 需要组织 ID 和仓库 ID
  291. # 在 Codeup 项目设置页面可以看到
  292. export CODEUP_ORG_ID=your_org_id
  293. export CODEUP_REPO_ID=your_repo_id
  294. ```
  295. ### 快速开始
  296. ```bash
  297. # 显式指定 codeup 模式
  298. ./run.sh --issue-source=codeup --codeup-token=xxx --codeup-org=123 --codeup-repo=456 42
  299. # 使用环境变量
  300. export CODEUP_TOKEN=xxx
  301. export CODEUP_ORG_ID=123
  302. export CODEUP_REPO_ID=456
  303. ./run.sh --issue-source=codeup 42
  304. # 指定 MR 目标分支
  305. ./run.sh --issue-source=codeup --codeup-branch=develop 42
  306. # 批量处理所有未关闭的 Issues
  307. ./run_all.sh --issue-source=codeup --codeup-token=xxx --codeup-org=123 --codeup-repo=456
  308. ```
  309. ### 工作流程
  310. ```
  311. Codeup Issue -> Agent 实现 -> 轮转审核+修复 -> 创建 MR -> 合入 -> 关闭 Issue
  312. ```
  313. 与 GitHub 模式的主要区别:
  314. | 步骤 | GitHub 模式 | 阿里云效 Codeup 模式 |
  315. |------|------------|---------------------|
  316. | 获取 Issue | `gh issue view` | Codeup REST API |
  317. | 创建 PR | `gh pr create` | Codeup REST API (Create MR) |
  318. | 合并 | `gh pr merge` | Codeup REST API (Merge MR) |
  319. | 关闭 Issue | `gh issue close` | Codeup REST API (Close Issue) |
  320. | 评论 | `gh issue comment` | Codeup REST API (Add Note) |
  321. ### 命令行参数
  322. | 参数 | 说明 |
  323. |------|------|
  324. | `--issue-source=codeup` | 指定阿里云效 Codeup 模式 |
  325. | `--codeup-token=<token>` | Codeup Access Token(也可用 `CODEUP_TOKEN` 环境变量) |
  326. | `--codeup-org=<org_id>` | Codeup 组织 ID(也可用 `CODEUP_ORG_ID` 环境变量) |
  327. | `--codeup-repo=<repo_id>` | Codeup 仓库 ID(也可用 `CODEUP_REPO_ID` 环境变量) |
  328. | `--codeup-branch=<name>` | Codeup MR 目标分支(默认自动检测) |
  329. ---
  330. ## 与 ralph 对比
  331. [ralph](https://github.com/snarktank/ralph) 是类似的自动化开发工具。
  332. ### 核心差异
  333. | 维度 | **autoresearch** | **ralph** |
  334. |------|-----------------|-----------|
  335. | **驱动方式** | GitHub Issue / 本地 Issue / 百度 iCafe | PRD(`prd.json`) |
  336. | **Agent 模型** | 多 Agent 轮转交叉审核 | 单 Agent 反复迭代 |
  337. | **质量门禁** | 硬门禁(Build/Lint/Test)+ 软门禁(LLM 评分) | 纯工具链检查 |
  338. | **审核机制** | 不同 Agent 交叉审核 | 无独立审核 |
  339. | **端到端** | Issue → PR → 合并 → 关闭(全自动闭环) | 止步于代码完成 |
  340. | **Continue 模式** | 支持 `-c` 恢复 | 无 |
  341. | **UI 验证** | 浏览器截图 + LLM 视觉验证 | `dev-browser` skill |
  342. ### 各自优势
  343. **autoresearch 优势:**
  344. - 双轨质量门禁覆盖更广
  345. - 多 Agent 交叉审核提供不同视角
  346. - GitHub 端到端自动化闭环,也支持本地项目、百度 iCafe/iCode 和阿里云效 Codeup 运行
  347. - 上下文溢出自动交接
  348. - Continue 模式支持中断恢复
  349. **ralph 优势:**
  350. - PRD 驱动,语义更丰富
  351. - 四通道记忆形成完整知识体系
  352. - 确定性质量门禁更稳定
  353. - Skills 插件系统可扩展
  354. - 内置流程序可视化
  355. ---
  356. ## 类似项目
  357. - [snarktank/ralph](https://github.com/snarktank/ralph)
  358. - [karpathy/autoresearch](https://github.com/karpathy/autoresearch)(原版思想)
  359. - [达尔文.skill](https://github.com/alchaincyf/darwin-skill): 使用 autoresearch 优化Skill, 花叔出品
  360. - [TheGreenCedar/codex-autoresearch](https://github.com/TheGreenCedar/codex-autoresearch): A codex plugin for running optimization loops inside a codebase.
  361. - [pi-autoresearch](https://github.com/davebcn87/pi-autoresearch): Autonomous experiment loop extension for pi agent
  362. - [good night, have fun](https://github.com/kunchenguid/gnhf): gnhf is a ralph, autoresearch-style orchestrator that keeps your agents running while you sleep
  363. - [Auto-claude-code-research-in-sleep](https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep)
  364. - [autoharness](https://github.com/kayba-ai/autoharness)
  365. - [awesome-autoresearch](https://github.com/yibie/awesome-autoresearch): 一大批的autoresearch思想的落地

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.