快速开始

这一页带你从全新 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	把 `muyan-pilot` CLI 装进隔离的 tool 环境（setup 的 CLI editable 步骤会调 `uv tool install`）	`uv --version`
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 官方文档）：

curl -LsSf https://astral.sh/uv/install.sh | sh

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

pi --print "reply with the single word: ok"

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

local-llm-kv-cache proxy 是可选增强（本地 llama.cpp 模型更快的 prefix 复用），不是核心前提——见可选组件。

1. Clone 仓库

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）：

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）。复制并编辑：

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

最小示例：

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：

muyan-pilot setup --config muyan-pilot.toml

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

5. 手工运行一个 tick

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

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 目录里运行；每条命令都相对该目录。

# 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 [email protected] -u [email protected] -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 并留下现场——恢复方法见运维。

7. 验证 timers

setup 已经安装 unit 模板并 enable 了两个 timer 实例（[email protected] 和 [email protected]，各自触发自己的 service 实例——见运维）；验证一下：

systemctl --user list-timers 'muyan-pilot@*.timer'

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

提交的 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，保持相对名。仓库模板仍是其余一切的唯一事实源—— 漂移检测见运维。

快速开始

核心概念

指南

可选组件

发布

Getting started

快速开始

前提

1. Clone 仓库

2. 安装 CLI

3. 创建配置

4. 运行一次性 setup

5. 手工运行一个 tick

6. Smoke walkthrough（从零）

7. 验证 timers

​快速开始

​前提

​1. Clone 仓库

​2. 安装 CLI

​3. 创建配置

​4. 运行一次性 setup

​5. 手工运行一个 tick

​6. Smoke walkthrough（从零）

​7. 验证 timers

快速开始

前提

1. Clone 仓库

2. 安装 CLI

3. 创建配置

4. 运行一次性 setup

5. 手工运行一个 tick

6. Smoke walkthrough（从零）

7. 验证 timers