# AlpacaLoop

把 issue tracker 中的目标变成可见、可控的 AI coding workflow。

[English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)

![AlpacaLoop workflow banner](https://unpkg.com/alpacaloop/assets/alpacaloop-readme-workflow.png)

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Status: early release](https://img.shields.io/badge/status-early_release-blue.svg)](package.json)
[![GitHub](https://img.shields.io/badge/github-alpacaloop%2Falpacaloop-24292e.svg?logo=github)](https://github.com/alpacaloop/alpacaloop)

AlpacaLoop 面向希望把 AI coding worker 的有用状态留在一次性 chat 之外的团队。你在 GitHub、Gitea 或 GitLab 中描述工作；AlpacaLoop 会把 worker 的 plan、progress、blocker 和 handoff 绑定到 tracker issue 上，同时让 Codex、Claude 或 OpenAI-compatible custom worker 通过 repo-local workflow 执行工作。

AlpacaLoop 是 early release。现在可以使用，但 1.0 之前 API 和行为可能会变化。

## Why People Use It

当 worker 能记住目标、展示状态、并在该停下时停下，AI coding 才更容易被团队使用。AlpacaLoop 专注于这个 operating loop：

- 把工作留在团队本来就会看的地方。issue 仍然是 goal、constraint、status 和 follow-up 的 source of truth。
- 让 AI 进展可检查。plan、label、managed comment、log、blocker 和 handoff 让 run 更容易 review。
- 复用团队自己的流程。repository 中的 workflow template 可以引导 planning、implementation、pull request review、unplanned work、follow-up 和 improvement。
- 从 tracker 持续推进。background service 会 polling ready issue；需要时也可以从 CLI 执行一次 one-off manual run。
- 保留人工控制。遇到需要输入、approval、不明确判断或 setup 问题时，AlpacaLoop 会停下来，而不是默默猜测。

## What to Expect

AlpacaLoop 管理 tracker-visible state 和 local worker run。它不会替代你的 code review、CI 或 release process。

- `alpaca init` 会连接一个 repository，并写入 `alpaca.config.json`。
- worker sign-in 是 machine-local 的。secret 和 OAuth browser login 仍然是人工 handoff step。
- 普通 managed issue 会获得 `AI: Ready` queue label，因此 enabled service 可以拾取它。
- 如需停止 polling 或运行一次 manual cycle，可以 disable background service。
- workflow template 和 system prompt 只有在相关 local change publish 后，才会影响 background automation。

## Install

macOS / Linux：

```bash
curl -fsSL https://raw.githubusercontent.com/alpacaloop/alpacaloop/main/install.sh | bash
```

installer 会检查 Node.js、安装 AlpacaLoop CLI，并输出下一步设置。AlpacaLoop 使用 native Git。只有显式传入参数时，它才会自动安装缺失依赖：

```bash
curl -fsSL https://raw.githubusercontent.com/alpacaloop/alpacaloop/main/install.sh | bash -s -- --install-deps
```

默认 Git install 需要 `git`、`npm` 和 Node.js `>=22.19.0`。使用 `--install-deps` 时，缺失的 Node.js tooling 会通过 `fnm` 安装；`git` 仍需预先存在。

在 Linux / WSL2 上，建议使用 fnm/nvm 等 user-writable npm prefix。有些发行版的 Node.js package 只安装 `node` 而不包含 `npm`；这种情况下请同时安装 `npm`，或使用 `--install-deps` 让 installer 使用 fnm-managed Node.js。如果 global `npm install -g` 因 EACCES 失败，请修正 npm prefix，而不要用 sudo 运行 AlpacaLoop setup。

当前的 npm registry beta channel 可通过以下命令安装：

```bash
npm install -g alpacaloop@beta
```

默认 npm install 使用 `latest` dist-tag；在 stable promotion 前，它可能落后于 beta channel：

```bash
npm install -g alpacaloop
```

如果需要从未发布的 `main` 做 source install，请使用 Git URL：

```bash
npm install -g 'git+https://github.com/alpacaloop/alpacaloop.git#main'
```

development checkout 使用 `pnpm`；执行下面的 checkout command 前请确保它可用。

development checkout：

```bash
git clone https://github.com/alpacaloop/alpacaloop.git
cd alpacaloop
pnpm install
pnpm build
```

本 README 中统一使用 primary command `alpaca ...`。安装后也可以使用 `alpacaloop ...`；issue comment command 是 `/alpaca`。从 checkout 运行时，请改用 `pnpm alpaca ...`。

查看 help：

```bash
alpaca --help
alpaca <command> --help
alpaca docs list --with-description
alpaca docs show quick-start
```

完整 command reference 请使用 `alpaca help --all` 或 `man alpacaloop`。

## Quick Start

首次安全评估路径是：安装 CLI，连接一个 repository，创建一个 managed issue，运行一次 foreground cycle，检查结果，然后再决定是否启用 background service。

开始前，请准备好：

- 一个连接到 GitHub、Gitea 或 GitLab 的 Git repository
- 对应 provider 的 tracker credentials
- 至少一个 Codex 或 Claude worker sign-in，或在 `customWorkers` 中配置的 OpenAI-compatible custom worker endpoint
- 一个可以写成 issue 的明确初始 goal

### 1. Sign in a worker

`alpaca init` 可能会提示 worker sign-in。你也可以先执行：

```bash
alpaca auth setup
```

支持的 worker sign-in method，包括 API key environment variable fallback，可通过 `alpaca docs show setup` 查看。

custom worker 不使用 `alpaca auth setup`；请在 `alpaca.config.json` 的 `customWorkers` 中配置 OpenAI-compatible endpoint 和 `${ENV}` secret。

custom worker 配置示例：

```json
{
  "customWorkers": {
    "kimi-k2": {
      "baseUrl": "https://api.moonshot.ai/v1",
      "model": "kimi-k2.6",
      "apiKey": "${MOONSHOT_API_KEY}",
      "requestParams": {
        "thinking": { "type": "disabled" }
      }
    }
  },
  "workers": {
    "default": ["kimi-k2"],
    "thinking": ["kimi-k2", "codex"]
  }
}
```

`apiKey` 是 Bearer auth shorthand。只有在需要提供完整 header 值时才使用 `headers.Authorization`；两者不能同时设置。`requestParams` 会在 AlpacaLoop 构建请求后 shallow-merge 到 OpenAI-compatible POST body 中，不用于 URL query parameters 或 headers。provider-specific 参数必须遵循对应 provider 的 API 规范，AlpacaLoop 不会验证这些值的语义。custom worker 只使用 OpenAI-compatible endpoint。AlpacaLoop 不会启动、下载或管理 local model。Repo skill 会从 `.agents/skills` 和 `skills` 读取，custom worker MCP server 会通过 Pi MCP adapter 从 `.mcp.json` 或 `.pi/mcp.json` 读取。

### 2. Connect the repository

GitHub：

```bash
export ALPACA_GITHUB_TOKEN=...
# 或使用 gh auth login 作为本地 CLI 凭据。

alpaca init
alpaca doctor
```

Gitea：

```bash
export ALPACA_GITEA_USERNAME=...
export ALPACA_GITEA_PASSWORD=...

alpaca init --repo-provider gitea
alpaca doctor
```

如需一步创建并注册新的 Gitea 仓库：

```bash
alpaca init --cwd ./my-repo --create-repo --repo-provider gitea --repo https://gitea.example.com/user/my-repo
```

GitLab：

```bash
export ALPACA_GITLAB_TOKEN=...
# 使用具备 `api` scope 和 repository access 的 token。

alpaca init
alpaca doctor
```

`alpaca doctor` 会检查 config、worker 认证、标签、repo 注册、远程基础分支是否存在，以及 workflow template 状态。

不要把 Git user name、email、token 或 password 放进 `alpaca.config.json`；该文件会提交到 repository。background service 的 Bot commit 请使用 machine-local env：

```bash
export ALPACA_GIT_USER_NAME="AlpacaLoop Bot"
export ALPACA_GIT_USER_EMAIL="bot@example.com"
```

这些值会在首次 `alpaca service enable` 时写入 service 定义。如果 service 已存在后再修改它们，请运行 `alpaca service enable --refresh-env` 或 `alpaca service restart --refresh-env`。

worker workspace 的 dependency setup 可以通过 `workspaces.setupCommand` 配置。详情请查看 `alpaca docs show config`。

### 3. Create the first managed issue

如果想在发布到 tracker 前先 review，请先保存 local draft。检查输出的 JSON path 后，用 `--apply-draft` 发布同一个 draft：

```bash
alpaca issue create --prompt "Fix flaky login tests." --save-draft
alpaca issue create --apply-draft ~/.alpaca/drafts/.../issue-create-....json
```

如果可以立即创建 issue：

```bash
alpaca issue create --prompt "Fix flaky login tests."
```

普通 unscheduled issue 会获得 `AI: Ready` workflow label。scheduled、recurring 或 disabled issue option 会设置不同的 queue state，详见 `alpaca docs show workflow-state`。

### 4. Run one foreground cycle

启用 continuous polling 前，先手动处理一次新 issue：

```bash
alpaca run --issue 123
```

background service enabled 时不要运行 `alpaca run`。如果需要一般性的 one-cycle run，请先检查 option：

```bash
alpaca run --help
```

### 5. Inspect the result

```bash
alpaca issue list --days 7 --limit 10
alpaca issue show --issue 123 --children 1 --limit 5
alpaca issue log show --issue 123 --tail 50
```

如果只想查看分配给当前已认证 tracker user 的 issue，可以给 `issue list` 加上 `--me`。如果要查看特定 assignee，请重复指定 `--assignee <login>`。

把这些 command 当作 first-run success check。`issue list` 和 `issue show` 会展示 managed issue 的 current status、workflow label、workflow update 和相关 child issue；`issue log show` 会展示该 issue 的 local log。如果 issue 已经不再是 `AI: Ready`，先查看 visible status：`AI: Running` 表示 run 或 accepted continuation 正在进行，`AI: Needs Human` 表示需要人工输入，`AI: Working in PR` 表示工作已经转移到 pull request。源 issue 的 PR handoff comment 会显示 pull request 链接，后续 review 可以从那里继续。完整 label set 请运行 `alpaca docs show workflow-state`。

### 6. Enable background polling

理解 foreground run 后，启用 service，并确认它已注册且正在 polling：

Linux / WSL2 的 service mode 需要可用的 systemd user session（`systemctl --user`）。WSL2 support 假设 systemd 已启用；如果不可用，请继续使用 foreground `alpaca run`。

```bash
alpaca service enable
alpaca service status
alpaca service log show --tail 50
```

更换 Node / npm manager 或 global install path 后，请再次运行 `alpaca service enable`。它会保留已保存的 service 环境变量，并把 service 定义刷新为当前使用的 `alpaca` command。只有在你想用当前 shell 环境替换已保存的 service 环境变量时，才使用 `alpaca service enable --refresh-env` 或 `alpaca service restart --refresh-env`。

回到 manual `alpaca run` 前，请先 disable service：

```bash
alpaca service disable
```

### Optional: create repository workflows

如需创建或更新 workflow template，请在 prompt 中说明 repository 用途，并显式绑定内置 workflow maintenance system workflow：

```bash
alpaca issue create --prompt "This repository is a TypeScript CLI for task automation. Create reusable workflows for bug fixes, PR reviews, unplanned maintenance, and follow-up work." --workflow __system/workflow-maintenance.md --pr-workflow no_template --unplanned-workflow no_template --followup-proposal off
```

该示例中的 `no_template` 会使用对应 target 的内置 default workflow。

如果 workflow maintenance 需要 recurring，或需要使用特定 worker，请使用普通 `issue create` scheduling 和 worker options。

## How It Works

1. `alpaca init` 会把 repository 连接到 GitHub、Gitea 或 GitLab，并创建 `alpaca.config.json`。
2. tracker issue 提供 goal、context、constraint 和 done criteria。
3. `.alpaca/workflows/*.md` 中的 workflow template 会引导 worker 进入下一步，例如 planning、design、execution、review、unplanned work、follow-up 或 improvement。
4. AlpacaLoop 运行选定的 configured worker，并校验返回的 workflow contract。
5. label 和 managed comment 会把 current state、blocker、dependency 和 next action 映射回 tracker。

## Core Commands

| Command | Purpose |
| --- | --- |
| `alpaca init` | 创建或更新 `alpaca.config.json`，并处理初始 sign-in 要求 |
| `alpaca detach [--cwd <path>] [--purge]` | 将 repository 从 service 管理中移除；普通 detach 保留文件，`--purge` 还会删除 repo-local AlpacaLoop 文件和 workspace |
| `alpaca doctor` | 检查 config、worker、service connection 和 sign-in 状态 |
| `alpaca publish [--path <path>] [--reviewer <name[,name...]>] [--no-merge] [--restart-service]` | 确定本地 repository 修正内容；worker 可用时生成 PR 正文，未指定 reviewer 且未使用 `--no-merge` 时通过 commit / PR / merge 反映到 base branch |
| `alpaca run [--issue 123]` | 手动单次处理 runnable workflow issue；`--issue` 会限定到特定 issue |
| `alpaca service enable` | 启动后台 polling service，并在需要时将 service 定义刷新为当前 CLI |
| `alpaca service status` | 显示 service 状态和已注册 repository |
| `alpaca service log show [--tail <lines>]` | 显示 background service log，可限制为最后 N 行 |
| `alpaca service restart` | 在当前 service work 完成后，用当前 CLI 重启 service |
| `alpaca service disable` | 在当前 service work 完成后停止 service |
| `alpaca state patch --dry-run --state open` | 预览 open issue 的 canonical workflow state comment 是否能迁移到 current schema，而不更新 tracker comment |
| `alpaca eject ...` | 将内置 system assets 复制到 repository 中以便编辑 |
| `alpaca issue create ...` | 创建、预览或发布已审核 draft 的 managed issue |
| `alpaca issue list` | 查看当前 managed issue；只看自己的负责人项目请加 `--me`，查看 override 请加 `--format text --view detailed`，打开 tracker issue 列表请加 `--web` |
| `alpaca issue search --title "keyword" --state all --limit 10` | 在 `issue list` / `issue show` 找不到相关 issue 时进行轻量搜索 |
| `alpaca issue show --issue 123` | 查看单个 managed issue 的详细信息 |
| `alpaca issue approve --issue 123` | 以负责人身份通过评论批准 foreign input approval |
| `alpaca issue log list` | 列出 local issue run log |
| `alpaca issue log show --issue 123 --tail 50` | 读取单个 issue 的 worker run log，可限制为最后 N 行 |
| `alpaca issue log search --query "error" --context 2` | 搜索 local issue run log，并可显示 context 行 |
| `alpaca issue followup --issue 123 [--prompt <text>] [--dry-run]` | 从现有 issue 创建 follow-up issue；`--prompt` 中的时间或频率可由常规 setup/autofill 推断为 schedule，添加 `--dry-run` 可先预览 |
| `alpaca issue broadcast --message "..." --open --dry-run` | 预览向 selected open queue issue 发送 shared comment |
| `alpaca issue disable --issue 123` | 在保留当前 workflow status 的同时添加 `AI: Disabled` rule |
| `alpaca issue enable --issue 123` | 只移除 `AI: Disabled` rule，不 approve、start、unlock，也不移动到 `AI: Ready` |
| `alpaca issue unlock --issue 123` | 将 `AI: Running` ownership 释放回 `AI: Ready` |
| `alpaca workflow create ...` | 创建可复用的 workflow template |
| `alpaca workflow update ...` | 使用 worker 改进已有 workflow template |
| `alpaca workflow lint` | 校验 template 结构和 nested reference；指定 `--path` 时也严格校验 required skill/MCP，完整 lint 则将 capability 缺失显示为 warning |
| `alpaca workflow list` | 按 target 列出非 system workflow template；如需 system workflow 请添加 `--include-system` |
| `alpaca event-hook ...` | configure、create、register、list、remove、update 或 test publish event hook |
| `alpaca skill list` | 以 JSON 列出 worker 可用 skill 和可写入 `requires.skills` 的 ref |
| `alpaca catalog topics list` | 以 JSON 列出 catalog 共用 topic ID 和说明 |
| `alpaca capability list/search` | 横向 discovery skill 和 MCP。默认隐藏已从 workflow requires 排除的候选；需要调查时可用 `--include-excluded` 查看原因 |
| `alpaca skill search <query> [--with-worker]` | 以 JSON 搜索已安装、catalog 和 marketplace 的 worker skill 候选；添加 `--with-worker` 可让 worker 做 semantic selection |
| `alpaca skill install ...` | 为一个 worker 下载或放置一个可安装的 skill 候选 |
| `alpaca skill create ...` | 让 worker 生成 title / capability summary，然后预览或创建 skill-resolution issue |
| `alpaca skill catalog list` | 列出 repo-visible 的可安装 skill catalog entry |
| `alpaca skill catalog add ...` | 将 install source 注册到 repo-local skill catalog |
| `alpaca skill catalog import-github ...` | 批量注册 GitHub `SKILL.md` directory 到 skill catalog |
| `alpaca skill catalog remove ...` | 删除 repo-local skill catalog entry |
| `alpaca mcp list` | 以 JSON 列出 worker 已配置的 MCP server |
| `alpaca mcp search <query> [--with-worker]` | 搜索已配置、catalog-backed 和 discovery-only catalog entry 的 MCP 候选；添加 `--with-worker` 可让 worker 做 semantic selection |
| `alpaca mcp install ...` | 使用带有 safeAutoInstall 和 server spec 的 catalog entry 注册 MCP 配置 |
| `alpaca mcp create ...` | 让 worker 生成 title / capability summary，然后预览或创建 MCP-resolution issue |
| `alpaca mcp verify` | 静态验证可写入 `requires.mcp` 的 MCP ref |
| `alpaca mcp catalog list/add/remove ...` | 管理 repo-visible MCP catalog entry |
| `alpaca labels sync` | 在 tracker 中补齐缺失的 managed label |

`skill search` / `skill install --search` 使用 installed inventory、repo/system catalog 和 provider marketplace。`mcp search` / `mcp install --search` 使用 installed inventory 和 MCP catalog。运行时不再搜索 GitHub registry metadata。没有 `servers` 的 MCP catalog entry 只是 discovery-only 线索；要安装它，请先在 catalog 中添加 server spec 和 `setup.safeAutoInstall: true`。

capability 策略：先用 `alpaca capability list/search` 横向查看 skill 和 MCP，再按用途 fit、目标范围是否足够窄、source 可信度、stars / updatedAt / createdAt 等质量信号比较。只有在同一目的上同样合适时才优先 skill；如果 MCP 更合适，或确实需要 live service/API/resource/server/tool access，则使用 MCP。

后台 service 会检测已安装的 AlpacaLoop package 版本变化，并在当前 service work 完成后自动重启。
只有在需要不等待当前 service work、立即执行请求的操作时，才为 `alpaca service restart` 或 `alpaca service disable` 添加 `--force`。

## Workflow Templates

workflow template 会从 `.alpaca/workflows/` 以及 `__system/` 下的内置 system workflow 加载。已 eject 的 `.alpaca/workflows/__system/` 文件会覆盖内置版本。文件名只是标识符；可用范围用 frontmatter 的 `targets` 声明，是否允许自动选择用 `autoSelect` 声明，template update 权限用 `updateMode` 声明。示例如下。

在 template 正文中引用其他 template 时，只有希望被引用 template 在 planning 中展开为独立 nested workflow step，才使用 `@workflow <template-path>`。如果当前 workflow 只是需要读取另一份 workflow document 作为参考指导，请在正文中直接写 `.alpaca/workflows/...md` 路径。

删除或移动 template 前，请先用 `alpaca workflow list --references-to <template.md>` 检查引用来源。`alpaca workflow delete --path <template.md>` 只删除 repo-local template，并会在仍有引用时停止。`--cleanup-references --save-draft` 不会 cascade delete 其他 template，只会为可编辑的引用方 template 生成待 review 的 cleanup update draft。

```text
.alpaca/workflows/
  engineering/implementation.md
  docs/maintenance.md
  review/pull-request.md
  unplanned/remediation-verification-blocker.md
  workflow/retrospective.md
```

在编写或编辑可复用 template 前，请运行 `alpaca docs show workflow-template-authoring`，确认 template 的 responsibility boundary、required shape 和 validation steps。repository-specific authoring preference 通过 `workflow-create` system prompt 调整；它不是 system workflow template。

使用 `workflow create` 创建或 scaffold template；在 interactive terminal 中可用 `workflow update --prompt <text>` 选择并改进已有 template，已知目标时可用 `workflow update --path <template.md> --prompt <text>` 显式指定。使用 `workflow lint --path <template.md>` 严格校验目标 template 及 nested workflow 的结构、metadata 和 required skill/MCP ref；完整 `workflow lint` 会将未选中 template 的 required capability 缺失显示为 warning。使用 `workflow list --target <target>` 查看非 system template，如需包含 system workflow 请使用 `workflow list --include-system --target <target>`，使用 `eject workflows` 将内置 system workflow template（包括 `no_template` default workflow）复制到 `.alpaca/workflows/__system/`，使用 `eject system-prompts` 将可选 repository guidance prompt 复制到 `.alpaca/system-prompts/`，使用 `eject catalog` 将内置 system skill、MCP 和 catalog metadata 复制到 `.alpaca/catalog/__system/{skill.json,mcp.json,metadata.json}`。service automation 会从 configured base branch 读取 workflow template 和 system prompt file；本地 workflow 编辑需要运行 `alpaca publish --path .alpaca/workflows`，本地 system prompt 编辑需要运行 `alpaca publish --path .alpaca/system-prompts`，如果 `paths.systemPrompts` 指向其他 path，也需要 publish 对应 path。workflow selector 接受 `auto`、`auto_select`、`no_template` 或 path。`auto` 让 worker 决定使用候选 template、通过 `no_template` 使用内置 default workflow，或请求缺失 template。`auto_select` 只会选择已有候选或 `no_template`；没有候选时，AlpacaLoop 不运行 worker，直接 fallback 到 `no_template` 并使用对应 target 的内置 default workflow。使用候选 template 时，AlpacaLoop 会在 planning 前做 fit review；普通运行中 worker 请求缺失 template 时，会创建 blocking 的 `missing-workflow-template` setup issue。prompt-mode issue creation 会保存未解析的 auto / auto_select workflow selection，因此父 issue 创建后由 workflow setup 处理选择。如果所选 template 会缩小或冲突父请求，会创建 blocking 的 `workflow-template-fit` setup issue 来准备更合适的可复用 template。`__system/workflow-maintenance.md` 是显式指定用的 system workflow，用于根据 issue prompt 创建或更新可复用 workflow template。也支持 `--workflow`、`--default-worker`、`--thinking-worker`、`--base-branch`、`--recurring-max-active-children`、`--recurring-update-child-title-after-plan`、`--workflow-start-new-plan`、`--workflow-start-replan`、`--workflow-start-scope`、`--run-at`、`--run-after`、`--every`、`--cron`、`--first-run-*`、`--stop-*`、`--pr-workflow`、`--unplanned-workflow`、`--issue-completion-target`、`--pr-review`、`--pr-merge`、`--followup-proposal`、`--followup-proposal-approval`、`--followup-preferred-workflow-template`、`--followup-auto-maintain-templates`、`--followup-max-main-work-issues`、`--followup-max-maintenance-issues` 等 sticky override。

可选 system prompt file 会在 `alpaca eject system-prompts` 后位于 `.alpaca/system-prompts/`。它们用于添加 repo-specific guidance，例如 worker convention、workflow-wide convention、workflow planning/review preference、current-step execution preference、workflow closing 完成报告和 close audit、workflow template authoring preference、event hook create preference、issue create style、human handoff style、follow-up recommendation guidance、merge integration preference。如果 guidance 已经保存在 `.claude` 等现有位置，可在 `alpaca.config.json` 的 `paths.systemPrompts.<name>` 中指定 repo-relative `.md` path。

定时运行的父 issue 在等待时使用 `AI: Recurring`；到期后，只要 open recurring child 数量低于 `recurring.maxActiveChildren`，service 就会创建一个 blocking child issue；达到上限时不会创建 child，而是把父 issue 推进到下一次 schedule。recurring auto-stop 到期时，如果仍有 open recurring child，父 issue 会等 child 完成后再关闭。设置 `aiWorkflowOptionAutofill: on` 时，父 issue 上的新评论会在 child 创建前先被 autofill，因此类似“一周后关闭”的请求可以先更新父 issue 的 auto-stop 策略。

Follow-up workflow 会在源 issue / PR 完成后创建或复用独立 issue。使用 `followup.proposalPolicy`（`off`、`if_needed` 或 `always`）、`followup.proposalApproval`（`auto`、`confirm` 或 `confirm_if_needed`）、planned child issue 继承策略 `followup.childIssuePolicy`（`inherit` 或 `off`，默认 `inherit`）、按 category 设置的 `followup.maxIssuesPerSource`（默认 `{ mainWork: 2, maintenance: 2 }`）、`followup.preferredWorkflowTemplates` 和 `followup.autoMaintainTemplates` 配置仓库默认行为。自动 recommendation 会把源请求或主工作的后续归为 `mainWork`，把 workflow / prompt / skill / MCP / Codex / Claude / worker environment 改善归为 `maintenance`。自动 follow-up publication 需要 fresh `workflow_closing` audit；PR merge finalization 时，AlpacaLoop 会同步 source 或 base workspace，并在发布 recommendation 前验证 PR head 或 merge commit，否则会停止自动 follow-up 创建并要求人工确认。`/alpaca --followup-proposal if_needed` 启用完成时判断，`--followup-proposal always` 始终生成候选，`--followup-proposal off` 禁用生成。`--followup-proposal-approval <auto|confirm|confirm_if_needed|default>` 控制候选是立即创建 issue 还是先停在确认评论。批准 pending proposal 时，proposal 之后新增的人类评论会先由 review worker 应用，因此用户可以在添加 `AI: Follow-up` label 前通过评论要求新增、修改或删除候选。`alpaca issue followup --issue <id> --prompt <text>` 会立即创建独立 follow-up issue，并把请求写入该 issue body；请求中的时间或频率可由常规 setup/autofill 推断为 schedule。`--followup-preferred-workflow-template <path|no_template[,path...]|default>` 只会把模板作为 recommendation prompt 的优先候选，支持重复指定和逗号分隔，不是 allowlist，也不会强制创建 issue。`--followup-max-main-work-issues <0..5|default>` 和 `--followup-max-maintenance-issues <0..5|default>` 会覆盖单个 source item 的自动 follow-up category 上限。`autoMaintainTemplates: true` 会让 follow-up issue 的 workflow selection 使用可请求缺失或需改进模板的 `auto`；默认 `false` 使用 `auto_select`。添加默认值为 `AI: Follow-up` 的 `ticketTracker.workflowLabels.aiFollowUp` label 时，如果存在 pending proposal 则表示批准，否则视为显式 follow-up request。

## Publish Event Hooks

详细内容集中在 `alpaca docs show event-hooks`。`alpaca event-hook test` 可能执行真实外部副作用。

## Configuration

`alpaca.config.json` 通常由 `init` 生成。主要配置分组包括：

- 输出语言和显示 / 调度时区
- repository / tracker 目标
- default / thinking worker 顺序和 machine-local sign-in
- service 轮询节奏和并行度
- workflow label 和 approval 行为
- dependency / pull request automation
- repo scope publish event hook

可由 CLI 读取的配置说明请运行 `alpaca docs show config`。issue 级 workflow override 和 schedule 请运行 `alpaca docs show workflow-options`。

## Docs

运行 `alpaca docs list --with-description` 可列出 CLI 可读取的 reference topic；运行 `alpaca docs show <topic>` 可读取单个 topic；运行 `alpaca docs search <query>` 可搜索；阅读全文前可运行 `alpaca docs search <query> --view headings` 查看匹配文档的大纲。

建议先看这些 topic：

- `quick-start`: 从 install 到第一个 managed issue 的最短路径
- `install`: CLI installation 和 local checkout
- `setup`: repository initialization、worker sign-in、health check
- `issues`: issue creation、search、inspection、approval、follow-up、log、unlock
- `workflow-template-authoring`: 可复用 workflow template 的编写规则
- `workflow-state`: label、workflow update、resume behavior

## Development

contributor setup、checks 和 documentation boundaries 请见 [CONTRIBUTING.md](CONTRIBUTING.md)。

```bash
pnpm install
pnpm build
pnpm hooks:install
pnpm typecheck
pnpm test
pnpm verify
```

## License

MIT。见 [LICENSE](LICENSE)。
