> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbi.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

# 快速开始

这一页带你从全新 clone 走到第一个验证过的 tick。这里的所有命令在任何
clone 路径下都能工作——不依赖任何特定机器布局。

## 前提

这些前提由**你自己安装**——`muyan-pilot setup` 只**检查**它们（校验
`git`、`gh`、`python3`、`uv` 和 systemd user session）；它从不自动安装
系统包、从不安装 `gh`、也不执行 `gh auth login`（你先登录，setup 只
验证登录状态）。

| 要求                                             | 用途                                                                             | 检查                        |
| ---------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------- |
| Python 3.14                                    | Runner 和测试契约（CI 固定同一 minor 版本）                                                 | `python3 --version`       |
| [uv](https://docs.astral.sh/uv/)               | 把 `muyan-pilot` CLI 装进隔离的 tool 环境（setup 的 CLI editable 步骤会调 `uv tool install`） | `uv --version`            |
| [Pi](https://github.com/earendil-works/pi) CLI | 开发 agent；每个任务一个完整 session                                                      | `pi --version`            |
| Git                                            | worktree、分支、base 新鲜度                                                           | `git --version`           |
| GitHub CLI（`gh`）                               | Issue、标签、PR、merge                                                              | `gh auth status`          |
| systemd（user session）                          | 每 5 分钟触发一个 tick 的 timer                                                        | `systemctl --user status` |
| 可用的 OpenAI-compatible 模型 endpoint              | Pi 的模型 provider——本地 llama.cpp server 或任意 OpenAI-compatible API                 | 一次真实 `pi --print` 调用（见下）  |

用官方安装器安装 `uv`（已对照
[uv 官方文档](https://docs.astral.sh/uv/getting-started/installation/)）：

```bash theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Pi 必须配置一个能稳定服务 coding agent 的 provider（system prompt +
tool schemas + 长 session）。派活之前先用一次真实调用验证 endpoint——
不要假设 key 或模型服务可用：

```bash theme={null}
pi --print "reply with the single word: ok"
```

如果失败，先修模型 endpoint；否则 Runner 会在每个任务上 fail fast。

<Note>
  `local-llm-kv-cache` proxy 是**可选**增强（本地 llama.cpp 模型更快的
  prefix 复用），不是核心前提——见[可选组件](/zh/optional-kv-cache)。
</Note>

## 1. Clone 仓库

```bash theme={null}
git clone https://github.com/xqliu/muyan-pilot.git
cd muyan-pilot
```

## 2. 安装 CLI

正式使用方式是安装后的 `muyan-pilot` console script（`pyproject.toml`
的 PEP 621 打包把 `muyan-pilot = muyan_pilot:main` 映射为可执行文件），
以 **editable** `uv tool` 安装——这是官方本地部署方式（Issue #152）。
在 clone 目录里安装，`--python` 固定生产解释器（3.14）：

```bash theme={null}
uv tool install --force --reinstall --editable --python /usr/bin/python3 .
muyan-pilot --help
```

`uv tool` 把 CLI 装进隔离的 tool 环境，可执行文件落在 `~/.local/bin`
（systemd unit 的 PATH 已包含该目录）。

**为什么必须 `--editable`**：非 editable 安装会把源码复制进 tool
环境的 site-packages；service 的 `ExecStartPre` 每次启动前把 checkout
快进到最新 `main`——源码被复制后 CLI 仍在执行旧副本（启动死锁：
Issue #152）。editable 安装下 tool 环境直接从 clone 目录导入
`muyan_pilot`，下一个 CLI 进程（下一个 timer 启动的 Runner）自动取到
merge 后的代码：**普通 Python 源码与 systemd 模板/迁移代码变更不需要
任何重装或升级命令**。
当**打包输入**变化（`py-modules` 新增运行时模块、依赖、入口点、包名、
构建后端或 Python 版本）时，editable finder 的模块映射会过期，下一个
CLI 进程在 Runner 启动前就 `ModuleNotFoundError`（Issue #158）——现在
Runner 自动刷新：每次启动（在任何 slot/claim 之前）比较 checkout
`pyproject.toml` 的 sha256 与**上次成功安装**记录的指纹（共享状态目录
`.muyan-pilot/cli-install.json`）：未变 → 完全不跑 `uv`（不做每 tick
重装）；变更或首次安装 → 在 base-sync flock 保护下跑一次上面的 force
editable 重装（与服务 `ExecStartPre` 同一把锁，两个 instance 同 tick
启动时串行化，第二个复用第一个的结果）；安装失败 → fail fast（结构化
`cli_install_failed` 行：原因 + 精确修复命令）。`muyan-pilot doctor`
报告一致性（`cli_source: clean` 或 `cli_source: DRIFT` + 结构化
`cli_source_drift` 行），`muyan-pilot setup` 幂等地校验或重装。发布包
不携带第三方运行时依赖、token 或用户目录——配置文件和用户 systemd 目录
保持机器本地。`muyan_pilot.py` 的直接执行入口（用解释器直接运行该文件）
保留为开发/兼容路径。

## 3. 创建配置

仓库带一份提交的 example；真实配置是本地状态（gitignored）。复制并编辑：

```bash theme={null}
cp .muyan-pilot.example.toml muyan-pilot.toml
```

全部字段（TOML，相对路径相对配置文件所在目录解析）：

| 字段                 | 必填 | 默认                 | 含义                                                                                                                                                                                                                                                                                                                             |
| ------------------ | -- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `source_repos`     | 是  | —                  | 每个 tick 按顺序扫描的 `owner/repo` 任务池列表（例如先你的 pilot 仓库，再你的 backlog 仓库）                                                                                                                                                                                                                                                               |
| `repo_dir`         | 否  | `.`                | service 启动的 Runner checkout（`bootstrap_runner.py` 所在目录）                                                                                                                                                                                                                                                                        |
| `workspace_root`   | 否  | `..`               | 包含任务 worktree 和 agent 可修改仓库的目录                                                                                                                                                                                                                                                                                                 |
| `prompt`           | 否  | `prompt.md`        | 实现者 prompt 模板（`{{SOURCE_REPO}}` 等占位符由 Runner 渲染）                                                                                                                                                                                                                                                                               |
| `prompt_review`    | 否  | `prompt_review.md` | PR 后独立审查 session 的 review prompt 模板                                                                                                                                                                                                                                                                                            |
| `base_branch`      | 否  | `main`             | 交付 base 分支；每个任务 worktree 都从冻结的 `origin/<base_branch>` SHA 创建                                                                                                                                                                                                                                                                   |
| `active_milestone` | 否  | 未设置                | 新领取扫描的领取范围（Issue #139）：当前活跃的 GitHub Milestone 标题（如 `v0.2.0`）。设置后 p0/bug/普通三个 ready 扫描只领取该 Milestone 的 Issue（`milestone:"<title>"` 限定词直接进 gh 搜索查询——其他 Milestone 或无 Milestone 的 Issue 永远进不了队列）；`ai-ready` 仍是执行开关，领取顺序（p0 → bug → 普通）不变，P0 不跨 Milestone，恢复态（已开 PR、在途重启）不受 Milestone 限制。未设置 = 所有 `ai-ready` Issue 都可领取（#139 之前的行为） |
| `max_concurrency`  | 否  | `1`                | 本机并发 Pilot 任务数（正整数；本地模型/GPU 通常只稳定服务一个任务）                                                                                                                                                                                                                                                                                       |
| `skills`           | 否  | `[]`               | 可选 Pi skill 路径（绝对、`~`，或相对配置文件）                                                                                                                                                                                                                                                                                                 |
| `context_files`    | 否  | `[]`               | 可选 Markdown 上下文文件，以路径形式注入 prompt                                                                                                                                                                                                                                                                                               |

最小示例：

```toml theme={null}
source_repos = [
  "OWNER/PILOT-REPO",
  "OWNER/BACKLOG-REPO",
]

repo_dir = "."
workspace_root = ".."
prompt = "prompt.md"
prompt_review = "prompt_review.md"
base_branch = "main"
max_concurrency = 1
skills = []
context_files = []
```

## 4. 运行一次性 setup

setup 入口用一条命令完成全部初始化：校验你安装好的前提（git、gh、
python3、uv、systemd user session——缺失会 fail fast 并给出可执行的
安装指引）、校验或重装 editable CLI 安装（Issue #152——运行中的 CLI
必须从部署 checkout 导入）、验证 `gh auth status` 和仓库权限、从仓库
管理的 `labels.toml`（标签名/颜色/描述的唯一事实源——commit 从不创建
标签，缺标签会让扫描静默漏掉对应状态）声明式对齐平台标签、安装
systemd user units 并 enable timer、检查 checkout、报告可选模型 proxy：

```bash theme={null}
muyan-pilot setup --config muyan-pilot.toml
```

它幂等（重复运行从不创建重复的标签、units 或 timer）且 fail-fast（仓库
错误、权限不足、checkout 不干净或缺 systemd user bus 都会带具体原因
停下）。完整输出契约、成功和失败示例见[一次性 setup](/zh/setup)。

## 5. 手工运行一个 tick

手工命令只用于首次验证和排查——正常运行由 timer 调度（第 7 步）：

```bash theme={null}
python3 bootstrap_runner.py --config muyan-pilot.toml
```

一个 tick 最多做一件事：恢复一个已打开的 PR（review/fix/merge），或
领取一个 `ai-ready` Issue（带 `p0` 标签的 Issue 最先被领取，然后是
`bug` 标签的，最后是普通 feature；设置 `active_milestone` 后只领取该
Milestone 的 Issue——Issue #139），然后退出。ready 队列为空时干净
退出，不领取任何东西。

## 6. Smoke walkthrough（从零）

验证环境可用的最小端到端证明。在第 1 步的 clone 目录里运行；每条命令
都相对该目录。

```bash theme={null}
# a. 向第一个配置的 source repo 派一个极小任务。
#    `add` 一步完成创建 Issue 并加 ai-ready 标签。
muyan-pilot add "Docs: verify smoke walkthrough" \
  --body "Read README.md and confirm the smoke walkthrough commands exist." \
  --config muyan-pilot.toml

# b. 看队列：新 Issue 已 ready。
muyan-pilot status --config muyan-pilot.toml

# c. 跑一个 tick：Runner 领取 Issue，在全新 worktree 里启动 Pi，
#    朝 PR 推进。
python3 bootstrap_runner.py --config muyan-pilot.toml

# d. tick 运行期间跟实时活动（第二个终端）：
journalctl --user -u muyan-pilot@1.service -u muyan-pilot@2.service -f
# 或者对手工 tick 直接跟 session JSONL：
muyan-pilot session --follow --config muyan-pilot.toml

# e. PR 打开后，Issue 带 ai-pr-opened，交付在后续 tick 继续
#    （独立审查、会话内修复、merge）。在 GitHub 上看 Issue 和 PR。
gh issue list --repo OWNER/PILOT-REPO --label ai-pr-opened
```

完成标志：Issue 走完 `ai-ready → ai-in-progress → ai-pr-opened →
ai-merged`，存在一个 body 带 `Fixes #<issue>` 的 PR，journal 显示
`run_end ... result=pr_opened`。任何一步失败，Issue 会被标记
`ai-blocked` 并留下现场——恢复方法见[运维](/zh/operations)。

## 7. 验证 timers

setup 已经安装 unit 模板并 enable 了两个 timer 实例
（`muyan-pilot@1.timer` 和 `muyan-pilot@2.timer`，各自触发自己的
service 实例——见[运维](/zh/operations)）；验证一下：

```bash theme={null}
systemctl --user list-timers 'muyan-pilot@*.timer'
```

setup 输出每个实例一行（两个实例各一行），形如
`timer=muyan-pilot@1.timer enabled active=true next=...`，带下次触发时间。每个 timer 每 5 分钟触发一次，全天 24 小时（00:00–23:55）。一个
service 实例 active 时，systemd 忽略对**该实例**的后续启动请求；下一
次真正启动会取到最新代码（service 启动前先 fast-forward `main`——见
[运维](/zh/operations)）。两个实例可以同时运行；容量由 Runner 的
flock slot（`max_concurrency`）决定，而不是实例数。

<Note>
  提交的 unit 模板通过 `%h` 占位符引用作者的 clone 布局
  （`%h/Documents/muyan/muyan-pilot`）。如果你的 clone 在别处，从**你**
  的 clone 路径安装 CLI（第 2 步），并编辑你 user unit 目录
  （`~/.config/systemd/user/`）里**已安装**的 units，把
  `WorkingDirectory` 和 `MUYAN_PILOT_CONFIG` 指向**你的** clone 路径，
  然后 `systemctl --user daemon-reload`。`ExecStart` 是已安装的
  `muyan-pilot` CLI，保持相对名。仓库模板仍是其余一切的唯一事实源——
  漂移检测见[运维](/zh/operations)。
</Note>


## Related topics

- [Testing](/zh/testing.md)