Skip to content

README-zh-TW.md

Latest commit

 

History

History
356 lines (252 loc) · 10.7 KB

README-zh-TW.md

File metadata and controls

356 lines (252 loc) · 10.7 KB

AWK - AI Workflow Kit

CI OpenSSF Scorecard License Go Bash GitHub CLI

「睡前啟動，早上收割」的 AI 開發工作流 Kit：以 Spec → 實作 → PR → 合併 為主線，搭配 Claude Code (Principal) + Codex (Worker) 完成閉環；Spec 格式與 Kiro 相容。

下載

English | 繁體中文

📋 目錄

✨ 特色

核心工作流

  • Spec 驅動：讀取 .ai/specs/<name>/tasks.md（Kiro 相容）決定下一步
  • GitHub 作為狀態機：Issues/PR + labels 追蹤進度
  • 派工 + 審查閉環：派工給 Worker 產 PR，再由 Principal 審查、合併或退回產生修正 issue

Kit 品質

  • Offline Gate：離線可驗證（不需網路）
  • Strict mode：--strict 強制 audit 無 P0（適用 CI/發布前）
  • Extensibility checks：檢查 CI 是否會被 feat/example 觸發（避免分支對齊誤判）

🏗️ 架構概覽

┌─────────────────────────────────────────────────────────────┐
│                                                              │
│  You ──► awkit kickoff ──► Claude Code (Principal)            │
│                              │                               │
│                              ├─► read specs/tasks.md          │
│                              ├─► create GitHub Issue          │
│                              ├─► dispatch to Codex (Worker)   │
│                              ├─► review PR                    │
│                              ├─► merge or reject              │
│                              └─► loop                         │
│                                                              │
│  Morning ──► gh pr list ──► harvest                            │
│                                                              │
└─────────────────────────────────────────────────────────────┘

完整架構文件：docs/ai-workflow-architecture.md

🛠️ 技術棧

Offline（必備）

  • bash（Windows: Git Bash / WSL）
  • git
  • go 1.25+

Offline（可選）

  • python3 + pyyaml + jsonschema + jinja2（僅供 legacy 腳本使用；生成功能已內建於 awkit）

Online / E2E（選配）

  • gh（GitHub CLI）+ gh auth login
  • claude（Claude Code）
  • codex（Worker）

📁 專案結構

.
├── .ai/                         # kit (config/templates/rules/specs)
│   ├── config/workflow.yaml     # main config
│   ├── templates/               # generators (CLAUDE/AGENTS/CI)
│   ├── rules/                   # architecture + git workflow rules
│   ├── docs/evaluate.md         # evaluation standard
│   └── specs/                   # Kiro-style specs
├── .github/workflows/ci.yml     # root CI example
├── backend/                     # directory example (Go)
└── frontend/                    # directory example (Unity skeleton)

🚀 快速開始

0) 安裝 awkit（建議）

awkit 是跨平台的 AWK 安裝 CLI（命名為 awkit 是為了避免和系統內建的 awk 指令衝突）。

curl -fsSL https://github.com/silver2dream/ai-workflow-kit/releases/latest/download/install.sh | bash

Windows（PowerShell）：

irm https://github.com/silver2dream/ai-workflow-kit/releases/latest/download/install.ps1 | iex

把 AWK 安裝到你的專案：

# 在當前目錄初始化 AWK
awkit init

# 使用 preset 並自動建立專案結構
awkit init --preset go --scaffold

# Monorepo：React + Go
awkit init --preset react-go --scaffold

# 預覽會建立哪些檔案
awkit init --preset python --scaffold --dry-run

可用的 Presets

類別 Presets
Single-Repo generic, go, python, rust, dotnet, node
Monorepo react-go, react-python, unity-go, godot-go, unreal-go

執行 awkit list-presets 查看詳細說明。scaffold 檔案結構請參考 Getting Started。

注意：awkit install 是 awkit init 的別名（向後相容）。

0.1) 更新 awkit

確認版本與更新：

awkit version
awkit check-update

更新 CLI：

curl -fsSL https://github.com/silver2dream/ai-workflow-kit/releases/latest/download/install.sh | bash

更新專案內的 kit 檔案（保留你的 workflow.yaml）：

awkit upgrade
awkit generate

其他更新選項：

# 只套用不同的 preset 到 workflow.yaml
awkit init --preset react-go --force-config

# 升級 kit 檔案，並覆蓋 workflow.yaml（需要 --preset）
awkit upgrade --force-config --preset react-go

# 完整重置：更新 kit 檔案並套用 preset 到 workflow.yaml
awkit init --preset react-go --force

1) 生成輸出

awkit generate

2)（選配）跑完整工作流

gh auth login

# 使用 awkit CLI（建議）
awkit kickoff --dry-run    # 預覽會執行什麼
awkit kickoff              # 啟動工作流
awkit kickoff --resume     # 從上次狀態恢復
awkit validate             # 只驗證設定

# Legacy bash 腳本已移除；請使用上方的 awkit 命令

停止：

touch .ai/state/STOP

⚙️ 設定

主設定：.ai/config/workflow.yaml

Repo type

AWK 支援三種專案結構類型，在 .ai/config/workflow.yaml 中設定：

Type 說明 使用情境
root 單一 repository 獨立專案
directory Monorepo 子目錄 共用 .git 的 monorepo
submodule Git submodule 獨立 .git 的 monorepo

各類型行為差異：

  • root：所有操作在 repo 根目錄執行。Path 必須是 ./。
  • directory：操作在 worktree root 執行，變更限定在子目錄。
  • submodule：commit/push 先在 submodule 執行，再更新 parent reference。

範例：

repos:
  - name: backend
    path: backend/
    type: directory  # 或: root, submodule
    language: go
    verify:
      build: "go build ./..."
      test: "go test ./..."

Specs

Spec 資料夾結構（Kiro 相容）：

.ai/specs/<feature-name>/
├── requirements.md   # optional
├── design.md         # optional
└── tasks.md          # required

要啟用 spec，將 spec 資料夾名稱加入 .ai/config/workflow.yaml 的 specs.active。

📦 Directory Monorepo 範例

這個 repo 內建一個可用的 directory 範例：

  • backend/：最小 Go module + unit test（go test ./...）
  • frontend/：Unity skeleton（CI 只做結構與 JSON sanity，不需要 Unity Editor）
  • Spec 範例：.ai/specs/example/
  • 入門指南：docs/getting-started.md

🔁 CI

Root CI workflow：.github/workflows/ci.yml

使用者專案：

  • awkit init 會自動為你的專案建立 CI workflow
  • awkit upgrade 會自動遷移舊版 CI 設定（移除過時的 awk job）

此 repo（awkit 本身）： 此 repo 內建的是手寫 CI 範例。awkit generate 預設不會改動 workflows；需要從模板生成時才使用 --generate-ci。

包含：

  • AWK evaluation：awkit evaluate --offline 與 --offline --strict
  • Kit tests：go test ./...
  • Backend：go test ./...（在 backend/）
  • Frontend：frontend/Packages/manifest.json JSON 檢查 + 資料夾存在性

🧪 評估

  • 僅供 kit 維護者 / CI 使用，一般使用者可跳過。
  • 標準：.ai/docs/evaluate.md
  • 執行器：awkit evaluate

📚 文件

使用者文件

文件 說明
Getting Started 快速入門指南
Configuration workflow.yaml 參考
Troubleshooting 錯誤排解
FAQ 常見問題

開發者文件

文件 說明
Architecture 系統內部架構
API Reference Scripts & modules
Contributing 開發指南
Testing 測試框架

其他

🤝 貢獻

詳見 Contributing Guide：

  • 開發環境設定
  • 程式碼規範
  • PR 工作流

快速參考：

  • 分支策略與 commit 格式：.ai/rules/_kit/git-workflow.md
  • PR base 預設 target feat/example

📄 授權

本專案採用 Apache License 2.0 授權。

🔒 安全性與信任

AWK 遵循開源安全最佳實踐，並由 OpenSSF Scorecard 持續監控。

OpenSSF Scorecard

安全功能

功能 狀態 說明
SECURITY.md ✅ 弱點回報政策與 SLA
Branch Protection ✅ 必要的審查與 CI 檢查
CI/CD ✅ 所有 PR 自動化測試
Dependency Updates ✅ 已啟用 Dependabot
Static Analysis ✅ CodeQL 掃描
Token Permissions ✅ 最小化 GitHub token 權限

完整安全政策與弱點回報方式請參閱 SECURITY.md。