OctoWorkFlow快速开始
GitHub
QUICK START · V4 分步指南

先预览，再安装。
十分钟走完。

本页所有命令只用于复制，页面不会执行任何东西。安装器默认先预览差异；初始化只写本机能力快照与角色覆盖，不装软件、不读密钥。安装成功 ≠ 宿主已发现 ≠ 行为已测——按第 4 步核验。

macOS / Linux / Windows · WSLPython 3.9+4 个宿主~10 分钟
01 / 准备PREREQUISITES

开工前，四样东西。

macOS / Linux 原生安装；Windows 原生安装 Skills，完整工作流经显式配置的 WSL 后端运行。仓库当前为私有，clone 需要访问权限。

REQ / 01

macOS、Linux 或 Windows

CI 覆盖 macOS、Ubuntu 与 Windows；其他 Linux 发行版未逐一验证。Windows 原生安装 Skills，完整工作流走显式 WSL 后端。

REQ / 02

Python 3.9+

渲染与安装脚本都需要 python3；低于 3.9 时部分测试会跳过。

REQ / 03

Git 与仓库访问

git clone 需要 GitHub 上对该私有仓库的读权限。

REQ / 04

一个受支持宿主

Codex、Claude Code、Cursor 或 Grok（走 Claude compatibility）任选其一，可重复安装到多个。

02 / 安装INSTALL

复制五段命令。预览在前，安装在后。

选择你的宿主，命令随之切换。--preview 只打印将要写入的路径、diff 与冲突，不改任何文件；确认后再跑无参安装。Windows 下等价命令为 python -B scripts/install.py 或 scripts\install.ps1。

01

克隆并校验渲染

LOCAL / TERMINAL
$git clone https://github.com/Octo-o-o-o/OctoWorkFlow.git
$cd OctoWorkFlow
$python3 scripts/render.py --check

--check 校验宿主入口是否与共同正文同步；过期会列出，不写入。

02

预览安装差异

DRY RUN / PREVIEW
$./scripts/install.sh codex --preview

核对目标路径、写入内容与和你已有文件的冲突。默认仅复制按需 Skills 及依赖，保留已有 MD。

03

实际安装

INSTALL
$./scripts/install.sh codex

首次修改已有文件前会完整备份并读回校验。常用选项：--skill <name> 只装某个能力，--project <dir> 装到项目范围，--rules block 附带常驻规则区块。复制受管文件，不做 symlink。

多宿主：对每个宿主重复第 2、3 步（或 ./scripts/install.sh all）。升级时 git pull 后重跑 render.py --check 与安装即可；--rules 模式沿用收据。

03 / 初始化SETUP

一次性的能力快照。不是第二条安装命令。

install.sh 复制文件；setup.py 做的是另一件事——探测本机 CLI、询问订阅与常用宿主，写角色覆盖与能力快照。编排入口靠它解析角色；只用普通 skill 可以跳过，建议先 --dry-run 看一遍。

01

先干跑一遍

DRY RUN
$python3 scripts/setup.py --dry-run

只探测与打印：各 CLI 路径与版本、node、API key 是否在场（只看存在性，不读值）、已有覆盖与 policy。不写任何文件。

02

二选一，同一份逻辑

终端向导与网页向导写入同一份配置，任选其一。

方式 A · 终端向导
$python3 scripts/setup.py
# 非交互：--answers answers.json 或 --non-interactive

12 个短问题：各平台订阅、常用宿主（supervisor）、Oracle 研究传输、本人亲验门禁、任务目录。准入条件不满足就写显式 gaps，不回填默认角色。

方式 B · 网页向导
$python3 ~/.octoworkflow/dashboard.py board serve --control
→ http://127.0.0.1:8765/#k=… · 仅本机，链接含一次性令牌
①探测本机②声明订阅③预览角色链④确认写入

打开终端打印的链接 → 侧栏「模型」→「开始配置」。API key 只报有/无，不读值；仅 --control 模式可写入 roles.override.json，只读模式会显示等价终端命令。

写入（仅在 OCTOWORKFLOW_HOME 或 ~/.octoworkflow）
  • roles.override.json — 角色覆盖与显式 gaps，供编排任务解析角色
  • local/capabilities.json — 能力快照；之后 setup.py --check 对照报告 CLI 消失或版本变化

不做的事：不安装软件、不改 policy.json、不改第三方配置、不读任何密钥值。

04 / 验证VERIFY

三层核验，不是看输出像成功。

安装成功 ≠ 宿主已发现 ≠ 真实任务行为已测。三层分别核对：

层级命令 / 位置看什么
收据./scripts/install.sh codex --doctor对照收据报告文件归属与状态；不一致会列出
能力python3 scripts/setup.py --checkCLI 消失或版本变化时报告 capability_stale
宿主发现宿主的 Skills / 命令菜单Claude：/command 与 @import；Codex：$skill 或 Skills 菜单（别假定 @import 会展开）；Cursor：规则 + skills；Grok：Claude compatibility

真实行为只能靠一次真实任务确认。宿主加载实测边界见仓库接入指南。

05 / 首次使用FIRST USE

四个入口。按目标选。

普通任务直接做。delivery 提供 plan_only / run；review 提供 accept / audit。pro-research 与 pro-design 只能点名，并保留原外部 ChatGPT Pro 多轮方式。看板只读显示 V4；恢复走任务冻结工具。

/delivery点名或明确要求

plan_only 只写交接；run 按授权执行，保存当前候选、原评审与 required gates

/review点名或明确要求

accept 独立只读验收；audit 发现问题并独立证伪高影响结论

/pro-research只能点名

向网页 Pro 征询，并在授权研究产物内有界修订

/pro-design只能点名

双 Pro 账号出原型：demo HTML + assets.zip，再交宿主实施

dashboard.py board serve看板

本机任务看板：V4 只读显示统一派发、回执与 usage；旧任务与配置的受控操作需显式 --control。

06 / 维护MAINTAIN

可逆，按归属卸载。

操作命令说明
卸载./scripts/install.sh codex --uninstall按收据归属卸载，保留你的修改；--rules-only 只停用常驻规则
回滚./scripts/install.sh --rollback撤销上次事务；备份在 ~/.octoworkflow/.bak/<事务>/
升级git pull && ./scripts/install.sh codex先预览；默认升级刷新已归属旧入口为薄别名，用户修改报冲突，沿用收据规则模式。V3 在途任务不迁移。
07 / 帮助HELP

卡住时，先看这些。

README.md安装、恢复与入口的权威说明docs/v4-spec.md新任务现行规则一页docs/…-adoption.md接入与已有个人文件冲突的处理AGENTS.mdcanonical、渲染与规则准入约定
SELF CHECK
$python3 -B scripts/render.py --check
$env PYTHONDONTWRITEBYTECODE=1 bash scripts/check.sh