Devflow for Oh My Pi

面向项目代码开发的 OMP 原生 Devflow 能力仓库。仓库同时提供 Agent Skills、运行时 extension、task agents、项目配置模板和 marketplace 插件目录。Devflow 的流程真相由需求图谱、冻结测试集、机器证据和控制面状态组成，Markdown 只负责展示。

本项目不依赖外部会话式验收或里程碑工作流；验收和版本收口均由 Devflow 自有节点完成。架构设计材料仅保留在内部源码仓库，不随 npm 包发布。

Devflow Pi

Devflow Pi 是一个面向项目研发交付的独立 OMP 产品入口，内置固定版本的 OMP Runtime 和六个 Devflow 插件。安装后可以直接在目标项目中进行初始化、需求梳理、方案设计、代码执行和验收，不需要把本仓库复制到业务项目中。

安装与启动：

npm install -g @guanlin4924/[email protected]
cd /path/to/your-project
devflow-pi init
devflow-pi doctor
devflow-pi

进入 TUI 后：

/devflow doctor
/devflow project-init
/devflow explain-state
/devflow recover
/devflow start <feature>|<phase>
/devflow resume
/devflow-usage
/usage-stats

/devflow project-init 会先读取当前项目已有的 .planning/PROJECT.md 与 .planning/navigation/INDEX.md：仅回填仍存在于项目根目录内的已登记前后端路径，删除或越界的历史路径会被忽略。随后可选择复用已有边界、复用边界并重建索引，或手动覆盖。初始化模式使用选择器提供“只读规划（默认）”和“写入初始化”；选择后者并确认，只会创建 Devflow 的 .planning/ 与 .context/ 初始化产物，不会修改业务源码、依赖或项目配置。

用量统计默认只读取当前项目的隔离会话：/usage-stats。需要明确查看历史 OMP 会话时，使用 /usage-stats omp，或加筛选条件：/usage-stats omp --from 2026-08-01 --to 2026-08-10。历史统计保留真实会话路径，不再把不同项目的长会话文件合并成 main；统计只使用 assistant message 的原始 usage，不虚构工具调用成本分摊。

会话继续使用 devflow-pi --resume；也可用 devflow-pi --resume <session-id> 打开当前项目的指定 Session。OMP 17.2.7 退出时仍会显示上游硬编码的 omp --resume 提示，在专项发行版中应替换为这里的 devflow-pi --resume，不会去读取官方 OMP 的 Session 目录。

专项 Pi 的隔离边界：

• 项目身份位于 <project>/.devflow/project.json；
• 流程状态和代码索引仍位于 <project>/.planning/；
• Session 位于 ~/.devflow-pi/sessions/<projectId>/；
• 模型认证默认复用 ~/.omp/agent/，但不复用官方 OMP Session；
• 只显式加载产品内六个插件根，不自动混入用户或项目的环境 Extension；
• MCP 默认关闭，避免自动连接用户全局服务器；确需复用时显式加 devflow-pi --mcp；
• task 只允许六个 Devflow 角色 Agent，且必须显式写明 agent；同名项目/用户 Agent 与产品定义不一致时拒绝执行；
• devflow-pi usage、devflow_usage_stats 与 usage_stats 默认只统计当前项目的隔离 Session；usage_stats 显式传 source=omp 时才读取 ~/.omp 历史会话。
• 以 devflow-pi 启动时，确定性工作流和代码索引脚本只从产品包内六个插件解析；项目遗留 .skills 不会覆盖产品版本。

devflow-pi doctor 是产品壳和资源检查；TUI 内的 /devflow doctor 还会验证活动 Extension、30 个必需 Skills、6 个 Agents，以及 @smol/@task/@slow 三个不同的已认证模型。专项 Pi 默认用 @slow 处理用户交互和规划，@smol 仅负责只读侦察，@task 仅负责受限执行与验证。

专项 Pi 会复用 ~/.omp/agent/ 里的登录凭据和可用模型列表，但模型角色选择写在 ~/.devflow-pi/agent/ 这个产品级目录里，不写入目标项目，也不读取官方 OMP 的 Session。首次进入专项 Pi 后，先在模型角色界面把 smol、task、slow 配成三个不同模型，再执行 /devflow doctor；未配好时 /devflow start 会被拒绝。

Skill 如何被加载

Skill 仍采用标准目录结构：

<skill-name>/
  SKILL.md
  scripts/
  references/
  assets/

.skills 不是 Pi/OMP 的默认自动发现目录，但 OMP 可以通过项目 .omp/config.yml 的 skills.customDirectories 直接扫描仓库内各插件的 skill 目录。因此无需再创建 .claude/skills 或 .codex/skills 软链接。

skills:
  customDirectories:
    - .skills/plugins/devflow-core/skills
    - .skills/plugins/devflow-intel/skills
    # 其余四个插件目录同理

私有源码兼容模式

install.sh --apply 只用于已经获得内部源码访问权限的开发环境。本文档不提供私有仓库地址；在内部工作副本中执行：

bash .skills/install.sh --apply

它会执行 postflight；已有但不兼容的 .omp/config.yml 会使安装失败，不会以警告方式假装安装完整。

安装器只生成以下 OMP 原生资源：

.omp/config.yml
.omp/AGENTS.md
.omp/extensions/devflow-*.ts
.omp/agents/*.md
.omp/hook-config.json
.agent-gates/index-first.json

已有且兼容的 .omp/config.yml 会保留。源码兼容模式下，已有配置缺少 Devflow skill 来源、model overrides 或工具策略时，先审查差异，再显式运行：

bash .skills/install.sh --apply --force-config

启动 OMP 后：

/devflow doctor
/devflow start <feature>|<phase>

/devflow doctor 检查 4 个运行时 Extension、30 个 Skills、6 个 Agents、确定性脚本、项目配置以及 @smol、@task、@slow 三个模型角色。三个角色必须解析到不同且已认证的具体模型，否则自动流程拒绝启动。

首次使用时，在 OMP 的模型角色界面中分别为 smol、task、slow 选择具体模型；modelRoleStorage: project 会把选择保存在项目作用域。建议分别使用快速探索模型、代码实现模型和独立推理/审查模型。配置完成后以 /devflow doctor 的 models: 行为准。

/devflow start 会先进入安全的需求梳理：可澄清并只读检查，不写入项目。用户随后直接补充需求，原文会被带入入口分诊并启动当前步骤。每个步骤结束后，系统展示产物和证据；用户明确回复“批准执行”才会推进并运行下一步，回复修改意见或“拒绝执行”则保持原步骤。普通需求描述绝不会自动确认 checkpoint。/devflow explain-state 发现控制面和制品 registry 漂移时会给出只读恢复计划；用户审查后可用 /devflow recover 确认仅修复可由文件系统证明的 registry 字段，它绝不推进步骤或自动通过 checkpoint。恢复已有流程使用 /devflow resume，它同样只恢复状态而不自动执行。

需求验收测试与 TDD 证据链

新建功能在 integration-verify 后会先生成独立的 TC-* 验收测试设计，再生成变更清单：

已确认需求/契约/架构事实 → TC-* 候选 → 变更清单（任务 ↔ 候选 TC 绑定）
                                                        ↓
                    CP-3：校验候选绑定 → 冻结 TC → 写入 Core attestation
                                                        ↓
                    RED / GREEN / REGRESSION 证据 → 按冻结 TC 执行 API / 页面 / 专项测试 → CP-4 → 版本收口

• TC-* 的步骤和 oracle 在代码出现前冻结；CP-3 在同一次确认中先校验候选绑定，再冻结 TC 并固定绑定哈希。需求或契约变化会使它 stale，不能继续以旧测试集宣称通过。
• tdd_required 任务必须先由 Core 记录准备快照，再记录 RED（命中预期失败）、同一目标的 GREEN 和回归；缺失或环境失败不算完成。
• API、跨数据域、边界、迁移、工作负载与架构风险会派生相应的 api、permission、boundary、migration、performance、resilience TC 义务。
• 每个 TC 还要声明证明策略：replay 用组件/页面/API/集成的稳定回放；causal 用已定位的首个偏差加 HAR、控制台、DOM 快照、截图或日志等受控文件证明，Core 会记录文件哈希；observation 用于尚不可复现、也未能证明根因的问题，只能保持阻塞并带观测计划。后两者都不能被“AI 已复现”或 Markdown 自述放行。
• 代码完成后，workflow-run-acceptance-tests 只能运行绑定到冻结 TC、且已在初始化 .planning/toolchain.md 发现的测试运行器命令。任何失败、未执行、人工待执行或环境阻塞用例都会阻止 CP-4。
• 验收不是代码完成后的临时手工检查。它是需求基线在编码前派生并冻结的完整测试集，覆盖主流程、异常、边界、权限、迁移、兼容、韧性和工作负载义务；代码只能补充执行适配信息，不能改变测试意图。
• 验收失败不会创建另一套人工台账，而是进入 acceptance-remediation：诊断 → 修复 → code-index 刷新 → 原冻结 TC-* 重跑。
• CP-4 通过后只进入一个 workflow-release-closeout 步骤，统一写入 .planning/milestones/current-CLOSEOUT.md 并更新项目状态、导航和版本记录。

正常使用不需要记忆底层命令：在 Devflow 工作流中按步骤继续即可。需要排查时，可用 devflow_acceptance_tests 查看冻结套件，或由工作流调用 devflow_tdd_evidence 与 devflow_run_acceptance_tests 生成 Core-owned 证据；不要手写“已测试”来替代结果文件。

更新

升级 npm 发行版：

npm install -g @guanlin4924/devflow-pi@latest

安装或升级 Extension 后重启会话；仅刷新 Skill/Command 时可使用 /reload-plugins。

插件边界

| 插件 | 职责 | 主要能力 | |---|---|---| | devflow-core | 控制面 | 流程状态、检查点、制品登记、单写者保护、/devflow | | devflow-intel | 项目事实 | 代码索引、查询、导航、上下文同步、project-scout | | devflow-requirements | 需求决策 | 分诊、探索、领域建模、可行性、需求基线、对抗审查 | | devflow-design | 契约设计 | API/UI/前后端方案、功能拆解、集成一致性 | | devflow-implementation | 代码变更 | 变更计划、隔离执行、Bug 修复 | | devflow-quality | 质量与收口 | 代码审查、主流程适配、冻结 TC 执行、失败修复编排与版本收口 |

每个 skill 恰好归属一个插件，插件目录中的实体文件是唯一真本；仓库根目录的同名入口只是兼容现有脚本和人工浏览的相对链接。marketplace 因而可以独立缓存单个插件，而不会留下指向缓存外部的断链。

核心不变量

• .planning/STATE.md、workflow 和 artifact registry 只允许 Devflow 工具写入。
• 子 agent 不更新控制面，只返回证据、结构化审查结果或隔离 patch。
• 索引是加速器，不是真相源；过期时回退到 LSP、搜索、源码和测试。
• 人工 checkpoint 不得在 headless 模式静默通过。
• semantic correctness 不能靠 prompt 保证，必须由契约、确定性校验、独立审查和可复现测试共同约束。

源码兼容模式刷新：

bash .skills/install.sh --refresh

刷新完成后重启 OMP 并再次运行 /devflow doctor。如果模板新增了强制配置而项目配置被保留，安装器会拒绝完成；审查后使用 --force-config 更新。