{"id":"ec6a66da-8c85-42c0-90d2-f87bca363f7d","slug":"autopi","kind":"skill","name":"AutoPi","summary":"Pi-native interactive autopilot package with a shared headless driver","owner":"archpeng","repoUrl":"https://github.com/archpeng/AutoPi","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-04-16T06:29:29.000Z","addedAt":"2026-10-22T00:55:11.198Z","logoUrl":"https://avatars.githubusercontent.com/u/166825283?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["browser-web","developer-tools"],"tags":[],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T22:14:41.494Z","sample":false,"url":"https://conduits.dev/tools/autopi","language":"TypeScript","transports":["stdio"],"install":{"npm":"autopi"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# AutoPi\n\n`AutoPi` 现在定位为一个 **Pi-native interactive autopilot package with a shared headless driver**。\n\n> 当前产品名为 `AutoPi`；npm package 名为 `autopi`。repo 路径、部分文档文件名、以及历史 control-plane 归档仍暂时保留 legacy `pi-sdk` 命名。\n\n固定产品表达：\n\n- **primary UX** = 当前 Pi session 内的 interactive autopilot\n- **secondary UX** = CLI / headless / batch driver\n- **truth / eval / learning** = 继续由 `BB` substrate 负责\n- **Pi core** = 不做 patch\n\n这意味着 `AutoPi` 不再把“CLI orchestrator + optional extension”当作长期目标，而是把：\n\n> **shared autopilot core + Pi interactive driver + CLI/headless driver**\n\n作为当前正确形态。\n\n## 当前能力\n\n### 1. Pi-native interactive autopilot\n\n安装为 Pi package 后，当前 session 内可直接使用：\n\n- `/autopilot-run <goal>`\n- `/autopilot-resume [goal]`\n- `/autopilot-pause`\n- `/autopilot-stop`\n- `/autopilot-status`\n- `/autopilot-status overlay`（bounded operator inspector overlay）\n- `autopilot_report` tool\n\nInteractive driver 当前已具备：\n\n- 同一 Pi session 内 same-session phase dispatch\n- deterministic `phase -> skill/prompt surface` binding：`master_plan / wave_plan / replan -> plan-creator`、`execute -> execute-plan`、`review -> execution-reality-audit`、`closeout -> repo-local closeout prompt surface`\n- routed dispatch 会在发给模型前预加载对应 `SKILL.md`，而不是只在 prose 里暗示“可以用某个 skill”\n- repo-local active control plane 读取，且 machine truth 固定单根在 `docs/plan/*`（不再宣称 dual-root `docs/active/* + docs/plan/*`）\n- `autopilot_report` 驱动的自动续跑\n- active-slice-aware report validation，包括 `phase` / `stepId`、`doneWhenMet` / `stopBoundaryHit`、以及未知 stop-law item 的 fail-fast\n- Pi 0.68 tool allowlist fail-fast（尤其是 `autopilot_report` 缺失时的 command-side + before-agent-start guard；skill-bound phases 还要求 `read`）\n- deterministic `README / STATUS / WORKSET` writeback，以及 accepted slice completion 后的 next-slice advancement\n- pause / resume / stop 语义\n- session-branch aware runtime-state reconstruction\n- reason-aware session replacement / fork handoff cleanup (`session_shutdown.reason` / `targetSessionFile`)\n- local mode 下的 control-plane-aware dirty-repo initial-run guard\n- phase-aware working indicator + footer/widget 状态展示\n- operator-facing degraded-mode / warning summary\n- BB-backed benchmark / promotion-readiness projection（当 server-owned status 可达时）\n- BB-backed decision-authority / dry-run reconcile projection（当 server-owned authority surfaces 可达时）\n- bounded status overlay inspector\n- `bb` substrate 模式下的 risky tool governance preflight\n\n### 2. Shared autopilot core\n\n`src/autopilot/**` 现已承载共享协议面：\n\n- protocol vocabulary / report schema\n- phase prompt builder\n- headless workflow engine\n- interactive runtime state model + reconstruction\n- closeout summary helper\n\n### 3. CLI / headless driver\n\n`src/sdk/orchestrator.ts` 仍保留，但现在定位为 **secondary driver**：\n\n- CLI argv parsing\n- session bootstrap\n- bounded headless loop\n- stdout / stderr closeout summary\n\n### 4. Substrate seam\n\n`src/substrate/**` 继续提供：\n\n- `local` / `bb` substrate mode\n- memory / governance / workspace ports\n- repo-local control-plane read / write seams\n- BB HTTP MCP adapter\n- hydration / raw evidence writeback helpers\n\n当前 local substrate 已不再是纯 no-op。\n一句话：local substrate includes repo-local control-plane read/write and local git workspace scanning。\n\n## 项目结构\n\n```text\nsrc/\n  autopilot/\n    protocol.ts          # shared protocol / commands / report schema\n    phase-prompt.ts      # shared phase prompt builder\n    engine.ts            # shared headless workflow engine\n    state.ts             # interactive runtime state + reconstruction\n    closeout.ts          # shared closeout summary formatting\n  extension/\n    index.ts             # Pi interactive driver assembly\n    command-handlers.ts  # slash-command entrypoints\n    runtime-dispatch.ts  # phase prompt + accepted-slice writeback glue\n    runtime-guardrails.ts # dirty-repo / continuation guardrails\n    tool-guard.ts        # tool-allowlist preflight + missing-tool diagnostics\n    runtime-ui.ts        # status/widget/working-indicator rendering\n    session-transition.ts # session replacement / handoff messaging\n  sdk/\n    orchestrator.ts      # CLI/headless driver\n  shared/\n    *.ts                 # compatibility re-exports into shared core\n  substrate/\n    index.ts             # substrate config + factory\n    bb.ts                # BB HTTP MCP adapter\n    local.ts             # local substrate: repo-local control plane + git workspace scan\n    control-plane.ts     # repo-local active-pack parser / next-slice resolver / writeback\n    hydration.ts         # pre-phase hydration + raw evidence helpers\n    governance.ts        # risky tool classification helpers\n    http-mcp-client.ts   # streamable HTTP MCP client\ntest/\n  *.test.ts              # targeted TDD coverage\n```\n\n## 安装与验证\n\n```bash\ncd /home/peng/dt-git/github/pi-sdk\nnpm install\nnpm test\nnpm run typecheck\nnpm run build\n```\n\n注意：\n\n- `build` 现在会先执行 `clean`\n- `src/**` 是唯一开发真相\n- `dist/**` 只是 clean build output，不再允许靠 stale dist 文件“假装”存在旧能力面\n- v1 release/readiness acceptance gate 现在固定为 `npm run release:check`\n- post-v1 maintenance 现已增加 clean-room packaged install smoke：`npm run smoke:packaged-install`\n- final completion proof route 现已增加 `pi` startup autoload smoke：`npm run smoke:pi-autoload`\n- auto-loaded command-surface smoke 现已增加：`npm run smoke:pi-commands`\n- deterministic BB-backed residual smoke 现已增加：`npm run smoke:pi-bb-backed`\n- operator install / upgrade / diagnostics / recovery runbook 见：`docs/runbooks/pi-sdk-autopilot-v1-operator-runbook.md`\n\n## 作为 Pi package 使用\n\n`package.json` 已声明：\n\n```json\n{\n  \"pi\": {\n    \"extensions\": [\"./src/extension/index.ts\"]\n  }\n}\n```\n\n所以可以直接：\n\n```bash\npi install /home/peng/dt-git/github/pi-sdk\n```\n\n安装后在当前 Pi session 内使用：\n\n```text\n/autopilot-run <goal>\n/autopilot-resume [goal]\n/autopilot-pause\n/autopilot-stop\n/autopilot-status\n```\n\n### Interactive 行为要点\n\n- 当前 session 就是执行现场\n- extension 使用 `sendUserMessage()` 在同一 session 内推进 phase；interactive path 不再建立在隐藏第二个 `AgentSession` 上\n- interactive dispatch 发出的不是裸 phase prompt，而是 `[AUTOPILOT ROUTED DISPATCH]` user message：其中会声明当前 phase 的 deterministic route，并在 skill-bound phase 中预加载对应 `SKILL.md`\n- `closeout` 明确绑定到 repo-local closeout prompt surface，而不是额外发明一个 global closeout skill\n- `autopilot_report` 仍是 machine-consumable phase contract\n- execute / review 的 progression 不再只看请求的 `status`，而会根据 active slice `done_when / stop_boundary` 推导 `doneWhenMet / stopBoundaryHit`\n- runtime state 会通过 `pi.appendEntry(\"autopilot-runtime-state\", ...)` 持久化，供 reload / tree navigation / resume 重建\n- status/widget 会显式暴露 substrate mode、degraded yes/no、warning summary\n- 当 `bb` substrate 的 `memory_autopilot_status` 可达时，status/widget/overlay 会投影 objective key 与 promotion-readiness summary\n- 当 `bb` substrate 的 decision-authority current/detail resources 与 reconcile-plan tool 可达时，status/overlay/closeout/hydration 会进一步投影 bounded decision-authority summary 与 `dry_run manual_reconcile` visibility\n- 当 `bb` substrate 的 recent canary / strategy report resources 可达时，status/overlay/closeout/hydration 会进一步投影 bounded history-summary\n- `/autopilot-status overlay` 会在当前 Pi UI 内打开 bounded inspector overlay，而不是新建第二个 UI/runtime\n\n## Deterministic routed phase contract\n\ninteractive runtime 现在固定使用以下 route matrix：\n\n- `master_plan` -> skill `plan-creator`\n- `wave_plan` -> skill `plan-creator`\n- `execute` -> skill `execute-plan`\n- `review` -> skill `execution-reality-audit`\n- `replan` -> skill `plan-creator`\n- `closeout` -> built-in repo-local closeout prompt surface\n\n这条 contract 不是“模型最好这样做”，而是 extension runtime 的 hard binding：\n\n- package-owned routed skills 位于 `<packageRoot>/skills/*`，是默认 primary shipped surface；`${PI_CODING_AGENT_DIR:-~/.pi/agent}/skills/*` 只作为 compatibility fallback\n- skill-bound phase 必须能解析到 routed `SKILL.md`，且文件不能为空\n- `selectedTools` 必须包含 `autopilot_report`；skill-bound phase 还必须包含 `read`\n- route 缺失、route/phase 不匹配、skill 文件缺失/为空、wrong `autopilot_report.phase`、wrong `stepId`、未知 `doneWhenMet / stopBoundaryHit` item 都会 fail-fast\n- repo-local machine control plane 固定单根在 `docs/plan/*`\n\n## Routed skill precedence / proof boundary / recovery\n\n- primary routed runtime surface 是 `<packageRoot>/skills/{plan-creator,execute-plan,execution-reality-audit}/SKILL.md`\n- `${PI_CODING_AGENT_DIR:-~/.pi/agent}/skills/*` 仍然存在，但只作为 explicit compatibility fallback；当前 contract **不**宣称更宽泛的 project-local `.pi/skills` auto-discovery\n- `npm run smoke:pi-bb-backed` 证明 repo-local clean-room routed phase：isolated/empty `PI_CODING_AGENT_DIR` 下成功输出应包含 `clean-room agent-dir routed skills: <none>` 与 `routed-skill-sources: package`\n- `npm run smoke:packaged-install` 证明 installed tarball 既包含 routed skill bundle，也能通过 installed-package alias 运行 clean-room routed phase；这不是对额外 skill discovery path 的泛化承诺\n- 若 routed dispatch 在 repo work 开始前就 fail-fast，先检查 package-owned skill path，再检查 explicit agent-dir fallback，然后重跑 `node dist/sdk/orchestrator.js --doctor`、`npm run smoke:pi-bb-backed`、`npm run smoke:packaged-install`\n\n## 作为 CLI / headless driver 使用\n\n确保本机 Pi 已可用，并且已有模型认证（例如 `~/.pi/agent/auth.json`）。\n\n### Local substrate（默认）\n\n```bash\nnode dist/sdk/orchestrator.js \\\n  --goal \"Build the first usable version of feature X in this repo\" \\\n  --cwd /path/to/target/repo \\\n  --max-waves 4 \\\n  --max-cycles 3 \\\n  --thinking high\n```\n\n### BB substrate\n\n```bash\nnode dist/sdk/orchestrator.js \\\n  --goal \"Implement the BB-backed slice\" \\\n  --cwd /path/to/target/repo \\\n  --substrate bb\n```\n\n也可以直接开发模式运行：\n\n```bash\nnpm run dev -- \\\n  --goal \"Implement the MVP\" \\\n  --cwd /path/to/target/repo \\\n  --substrate bb\n```\n\n### CLI 参数\n\nRun mode：\n\n- `--goal <text>`：必填，总目标\n- `--cwd <path>`：目标仓库路径，默认当前目录\n- `--model <provider/id>`：可选模型\n- `--thinking <level>`：`off|minimal|low|medium|high|xhigh`\n- `--max-waves <n>`：最大 wave 数\n- `--max-cycles <n>`：每个 wave 最大 execute/review 循环数\n- `--substrate <mode>`：`local|bb`，默认 `local`\n- `--plan-docs <path>`：覆盖 `docs/plan` 路径\n- `--bb-memory-url <url>`：覆盖 BB memory MCP 地址\n- `--bb-govern-url <url>`：覆盖 BB govern MCP 地址\n- `--bb-tools-url <url>`：覆盖 BB tools MCP 地址\n- `--agent-dir <path>`：可选 Pi agent 目录覆盖\n- `--ephemeral`：使用内存 session\n- `--quiet`：不把 assistant 文本实时流到 stdout\n\nReadiness / packaging mode：\n\n- `--version`：输出当前 package version\n- `--print-manifest`：输出 v1 release/readiness manifest JSON\n- `--doctor`：执行 bounded packaging/readiness diagnostics（repo checkout 与 installed package 都保持诚实边界）\n- `--help`：输出 CLI 帮助\n\n## 协议核心\n\n所有 driver 仍共用同一 phase protocol：\n\n- `master_plan`\n- `wave_plan`\n- `execute`\n- `review`\n- `replan`\n- `closeout`\n\n但是 interactive runtime 现在不只要求“有一个 report”，而是要求完整的 routed + stop-law contract：\n\n1. 每个 phase 结束前必须 **恰好调用一次** `autopilot_report`\n2. `autopilot_report.phase` 必须匹配当前 runtime phase\n3. 当存在 active slice 时，`autopilot_report.stepId` 必须匹配当前 slice\n4. execute / review 会把 active slice 的 `done_when / stop_boundary` surface 进 prompt，并用 `doneWhenMet / stopBoundaryHit` 派生 honest progression\n5. local writeback 只把 `docs/plan/*` 当成 repo-local machine truth\n\n`autopilot_report` 当前核心字段包括：\n\n- `phase`\n- `status`\n- `summary`\n- `waveId`\n- `stepId`\n- `nextAction`\n- `decisionMode`\n- `decisionBasis[]`\n- `candidateRoutes[]`\n- `doneWhenMet[]`\n- `stopBoundaryHit[]`\n- `evidence[]`\n- `artifacts[]`\n- `risks[]`\n\n这仍然是 `AutoPi` 的核心 machine-consumable contract；`status` 只是其中一部分，真正的 execute/review progression 还依赖 stop-law fields。\n\n## Substrate 行为边界\n\n### `local`\n\n- 不做外部 `BB` memory / govern / autopilot truth 调用\n- 会读取 repo-local `docs/plan/*` control plane，并把它当成唯一 machine truth\n- 会在 local mode 下执行 deterministic `README / STATUS / WORKSET` writeback；accepted slice completion 会推进 next active slice 或 `PACK_COMPLETE`\n- 不再宣称 dual-root `docs/active/* + docs/plan/*` mirroring\n- 会做本地 git workspace scan，用于 control-plane-aware dirty-repo guard（允许 control-plane-only dirty，阻断 foreign dirty）\n- interactive 与 CLI/headless 都可继续最小可运行\n\n### `bb`\n\n通过 BB HTTP MCP servers 接入：\n\n- memory: `memory_recall` / `memory_store` / `memory_autopilot_status`\n- decision authority: `memory_autopilot_decision_authority` / `memory_autopilot_decision_intent` / `memory_autopilot_decision_reconcile_plan`\n- resources: `memory://autopilot/decision-authority/current/{objective_key}` / `memory://autopilot/decision-authority/recent` / `memory://autopilot/decision-authority/{authority_id}`\n- history resources: `memory://autopilot/canary/reports/recent` / `memory://autopilot/strategy-feedback/reports/recent`（用于 bounded operator history inspection）\n- govern: `govern_policy` / `govern_evaluate`\n- workspace: `workspace_scan` / `plan_sync`\n\n当前固定约束：\n\n- `AutoPi` 继续做 workflow shell\n- benchmark / promotion / canonical truth / eval / learning 继续在 `BB`\n- repo-local objective key 只用于查询 server-owned status / authority truth，不代表本地拥有 benchmark or decision truth\n- 若 live BB endpoint 落后于源码，必须显式降级，而不是在 `AutoPi` 本地偷偷发明第二套 truth path\n\n## 关键设计约束\n\n1. **official Pi docs / examples first**\n2. **no hidden second session as the primary interactive path**\n3. **no Pi core patch**\n4. **BB remains the truth / eval / learning substrate**\n5. **CLI stays supported, but is secondary**\n\n## Release / Readiness Quick Commands\n\n```bash\nnode dist/sdk/orchestrator.js --version\nnode dist/sdk/orchestrator.js --print-manifest\nnode dist/sdk/orchestrator.js --doctor\nnpm run smoke:pi-autoload\nnpm run smoke:pi-commands\nnpm run smoke:pi-bb-backed\nnpm run smoke:packaged-install\nnpm run release:check\nnpm pack --dry-run\n```\n\n## 相关文档\n\n- `docs/architecture.md`\n- `docs/pi-sdk-bb-integration-architecture.md`\n- `docs/pi-native-interactive-autopilot-design-2026-04-16.md`\n- `docs/runbooks/pi-sdk-autopilot-v1-operator-runbook.md`\n- `docs/plan/README.md`\n"}