self

一个基于 Github Workflow / Github 定时任务的自动化软件构建团队。

自述（给所有人看的）

目标

在本仓库下完成基于 self 自身的迭代流程，完善软件开发的需求调研、需求评估、PRD 撰写、PRD 评估、软件开发、软件开发 Review、代码测试、问题分析 & 修复等流程。并在后续将此套流程复用到其他项目中。

这个项目的设计机制如何？

在我看来一个 Long Running 的 Agent 其实解决了几件事：

1. 它可以定时触发任务（这意味着它不需要你来提醒他去做什么）
2. 它可以被某些特定的事件来触发，去完成某件事（这意味着它可能会被打断执行某些事。比如聊天就是一种打断）
3. 它可以启动很多子进程，可以快速 Scale Up 自己和自己的 SubAgent

这样的方案如果放在软件工程领域，那么可以有个简单粗暴的方式来实现：定时任务 + 状态机；我们将软件工程中设计到的流程绘制成状态图，并构建相应的状态机，借助 Github Action Events Trigger （特定的事件触发） + Github Action Schedule Trigger （定时触发），再配合 Github Action 自身的运行环境，来完成 Agent 的运行，就可以构建一个最小集合的 Agent Team，来帮助你完成软件工程的工作。

这个项目参考了哪些项目的机制？

1. 参考了 OpenClaw 对于 SOUL.md 的定义，我将一些明确的、全局使用的重要的 Prompt 也放在了 Prompt.md 当中。

这个项目目前实现了哪些机制？还有哪些在路上？

所有的机制可以按照软件工程的流程来区分：

全局管理

1. [进行中][定时+自动触发]基于需求状态的自动合并机制：目前仍有部分的功能在实现中（比如读取 CI 状态）
2. [待开发][定时+自动触发]基于全局所有需求的优先级判断和重排能力

需求发现机制

1. [已完成][定时]结合当前项目的情况和进展主动发起新的 Backlog ，促进项目的自我进化。
2. [进行中][定时+自动触发]基于需求的评估机制：目前只完成了初次评估和变更评估，未成 Review 评估之后的更新；
3. [已完成][自动触发]合并进仓库的需求会自动创建产品规划单

需求规划机制

1. [已完成][自动触发]基于产品规划单，自动进行 Agent 的分析和追问，并根据人的反馈来更新。
2. [进行中][自动触发]基于产品规划单的需求 Review 能力

需求开发

1. [已完成][定时+自动触发]基于产品规划单，进行项目变更和更新

代码测试

1. [待开发][定时+自动触发]基于项目机制，进行测试的能力

代码修复

1. [进行中][自动触发]基于 Github Actions 的失败日志，自动检测、修复报错的功能。

实现相关（给工程师看的）

仓库结构与用途

路径	用途	典型使用
plans/	存放需求分析与执行计划文档。计划文件可用 FrontMatter status（TODO/DOING/DONE）标记状态。	make filter-todo 筛选待办计划；make create-plan ISSUE=<issue_number> NAME='<plan_name>' 创建新计划。
prompts/	存放可复用提示词，统一 Agent/Workflow 的执行口径。	prompts/reviewer.md 作为 Reviewer 审查基准。
scripts/	存放仓库自动化脚本（计划筛选、计划创建、skill 安装与校验）。	scripts/1-filter-todo-plan.sh、scripts/2-create-plan.sh、scripts/install-gh-actions-engineer-skill.sh。
skills/	存放本仓库维护的本地 skill。	当前内置 skills/gh-actions-engineer/，用于编写/修复/校验 GitHub Actions workflow。
templates/	存放模板文件。	templates/plan_template.md 被创建计划脚本复用。
Makefile	统一命令入口，封装常用操作。	make help、make filter-todo、make create-plan ISSUE=<issue_number> NAME='<plan_name>'。

Workflow 状态与流程图

以下两张 Mermaid 图用于帮助读者快速理解当前仓库中各 Workflow 之间的状态流转与触发关系。

1) 各 Workflow 状态流转图

stateDiagram-v2
  [*] --> BacklogIdea : schedule / workflow_dispatch

  state "Backlog 候选需求" as BacklogIdea
  state "Backlog PR" as BacklogPR
  state "Backlog PR Review" as BacklogReview
  state "Backlog Issue" as BacklogIssue
  state "Plan Issue" as PlanIssue
  state "Plan PR" as PlanPR
  state "Plan PR Review" as PlanReview
  state "Plan 已合并" as PlanMerged
  state "Engineer 执行" as EngineerRun
  state "实现 PR" as ImplPR
  state "实现 PR Review" as ImplReview
  state "实现已合并" as ImplMerged
  state "DeepResearch 报告" as DeepResearchReport
  state "Fixer 执行" as FixerRun

  BacklogIdea --> BacklogPR : Backlog Discovery 创建 PR
  BacklogPR --> BacklogReview : event: pull_request.opened
  BacklogReview --> BacklogPR : event: review/comment 反馈更新
  BacklogPR --> BacklogIssue : event: pull_request.merged / Backlog PR Merged 创建 issue

  BacklogIssue --> PlanIssue : event: issues.opened/edited/reopened
  PlanIssue --> PlanPR : Product Designer 创建/更新计划 PR
  PlanPR --> PlanReview : event: pull_request.opened/synchronize/reopened
  PlanReview --> PlanPR : event: review comment 反馈更新
  PlanPR --> PlanMerged : Pull Request Merger 或人工合并

  PlanMerged --> EngineerRun : event: pull_request.closed(merged)
  EngineerRun --> ImplPR : Engineer 创建实现 PR
  ImplPR --> ImplReview : event: pull_request.opened/synchronize/reopened
  ImplReview --> ImplPR : event: review comment 反馈更新
  ImplPR --> ImplMerged : Pull Request Merger 或人工合并

  BacklogIssue --> DeepResearchReport : event: issues.opened / title 匹配 [backlog]
  DeepResearchReport --> PlanIssue : 产出跟进 issue

  EngineerRun --> FixerRun : event: workflow_run.failed (设计链路)
  PlanIssue --> FixerRun : event: workflow_run.failed (设计链路)
  FixerRun --> ImplPR : 自动修复并创建 PR
  FixerRun --> PlanIssue : needs_decision / 结果回写 issue

Loading

2) 各 Workflow 触发流程图

flowchart TD
  S10["schedule: */10 * * * *"] --> BD["Backlog Discovery"]
  WDBD["workflow_dispatch"] --> BD
  WRRV["workflow_run: Reviewer.completed"] --> BD
  ICBD["issue_comment"] --> BD
  PRRBD["pull_request_review / review_comment"] --> BD

  BD -->|"创建 backlog PR"| PR1["Backlog PR"]
  PR1 -->|"event: pull_request.opened/synchronize/reopened"| RV["Reviewer"]
  RV -->|"评审意见（review/comment）"| PR1
  PR1 -->|"event: pull_request.closed + merged"| BPM["Backlog PR Merged"]
  BPM -->|"创建 [backlog] issue"| I1["Issue: backlog"]

  I1 -->|"event: issues.opened([backlog])"| DR["DeepResearch"]
  DR -->|"提交 research + 创建跟进 issue"| I2["Issue: DeepResearch: ..."]

  I1 -->|"event: issues.opened/edited/reopened"| PD["Product Designer"]
  ICPD["issue_comment"] --> PD
  PD -->|"创建/更新计划 PR"| PR2["Plan PR"]

  PR2 --> RV
  PR2 -->|"gate 通过"| PRM["Pull Request Merger"]
  PRM -->|"auto-merge eligible PR"| MRG["Merged PR"]

  S30["schedule: */30 * * * *"] --> ENG["Engineer"]
  WDENG["workflow_dispatch"] --> ENG
  MRG -->|"event: pull_request.closed + merged"| ENG
  ENG -->|"创建实现 PR"| PR3["Implementation PR"]

  PR3 --> RV
  PR3 --> PRM

  SD["schedule: 0 1 * * *"] --> SU["Self Engineer"]
  WDSU["workflow_dispatch"] --> SU
  SU -->|"创建 [SELF-UPGRADE] issue"| I3["Issue: self-upgrade"]
  SU -->|"创建计划 PR"| PR4["Self-upgrade Plan PR"]
  PR4 --> RV
  PR4 --> PRM

  WRF["workflow_run.failed (设计链路)"] -.-> FX["Workflow Engineer (Fixer)"]
  FX -->|"自动修复 + 创建 PR"| PRF["Fix PR"]
  FX -->|"needs_decision / 结果评论"| IANY["Related Issue"]

Loading

图例：

• event:* 表示主要 GitHub 事件触发来源。
• 虚线表示当前仓库中作为设计意图或可选链路的触发关系。

注：fixer.yml 里的 workflow_run.workflows 当前配置为 Engineer Plan Executor 与 Product Issue Planner。上图保留了该失败修复链路的设计意图，便于理解整体闭环。

Skill Bootstrap（Claude Code + Codex）

本仓库包含 gh-actions-engineer，用于编写和校验 GitHub Actions workflow。

首次在本机安装（创建到本仓库 skill 的软链接）：

bash scripts/install-gh-actions-engineer-skill.sh

验证安装状态：

bash scripts/verify-gh-actions-engineer-skill.sh

安装完成后，建议重启 Claude Code/Codex 会话以确保立即生效。

ACTIONS_PR_TOKEN 要求（GitHub Actions）

当 Workflow 可能修改 .github/workflows/* 文件并推送分支/创建 PR 时，必须使用 ACTIONS_PR_TOKEN。
github.token（GitHub App token）在很多仓库配置下不具备 workflow 文件写权限，会出现类似报错：

refusing to allow a GitHub App to create or update workflow ... without workflows permission

最小权限要求

推荐使用 Fine-grained Personal Access Token（FGPAT）：

• Repository access: 仅选择当前仓库
• Repository permissions:
• Contents: Read and write
• Pull requests: Read and write
• Workflows: Read and write

如果使用 Classic PAT，至少需要：

• repo
• workflow

Pull Request Merger（.github/workflows/pull-request-merger.yml）补充说明

该 workflow 会根据仓库变量 PR_MERGER_USE_ACTIONS_PR_TOKEN 决定 token 来源：

• 若变量显式为 true，优先使用 ACTIONS_PR_TOKEN（为空时回退到 github.token）。
• 若变量显式为 false，强制使用 github.token。
• 若变量未设置，且 ACTIONS_PR_TOKEN 非空，则自动使用 ACTIONS_PR_TOKEN；否则使用 github.token。

如果你显式启用了 ACTIONS_PR_TOKEN，它至少需要：

• Pull requests: Read and write
• Checks: Read
• Commit statuses: Read
• Contents: Read

可使用以下命令诊断 token scope（会打印 X-OAuth-Scopes 和 X-Accepted-OAuth-Scopes）：

GITHUB_TOKEN=<YOUR_TOKEN> \
GITHUB_REPOSITORY=<OWNER/REPO> \
bash scripts/workflows/pr-merger/inspect-token-scopes.sh

Token 创建路径（GitHub 页面）

路径 1：Fine-grained PAT（推荐）

1. GitHub 右上角头像 -> Settings
2. 左侧底部 -> Developer settings
3. Personal access tokens -> Fine-grained tokens
4. Generate new token
5. 配置仓库范围和上述权限后生成 token

路径 2：Classic PAT（备选）

1. GitHub 右上角头像 -> Settings
2. 左侧底部 -> Developer settings
3. Personal access tokens -> Tokens (classic)
4. Generate new token (classic)
5. 勾选 repo 与 workflow 后生成 token

仓库中配置路径（Actions Secret）

1. 进入仓库首页 -> Settings
2. Secrets and variables -> Actions
3. New repository secret
4. Name 填：ACTIONS_PR_TOKEN
5. Secret 填：上一步生成的 token

建议

• 使用最小权限原则，只授权当前仓库。
• 定期轮换 token。
• 若还会调用 Codex Action，同时确认 OPENAI_API_KEY 与 OPENAI_API_PATH 已配置。