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_bootstrap 时使用 flow="regression-acceptance"，随后按“回归测试设计 → 主流程 DSL → 批准 → 验收执行”推进， 不需要补建功能开发链路。用例冻结时必须明确 oracle_source：requirement 来自需求， contract 来自外部接口/权限约定，invariant 表示内部一致性，characterization 只表示经人确认的现有行为基线。 后三者都必须附 oracle_evidence；characterization 不能被表述为正确性证明。

测试环境 profile 的 secret_env 只声明变量名。打开 /devflow control 的“测试凭据”输入值后， 凭据仅保存在当前扩展进程的内存中，不写入 process.env、文件、日志或审计，也不会被 Agent 子进程继承； 只有 Core 启动验收执行子进程时才会注入。面板输入没有遮罩能力，输入时值会显示在屏幕上，退出 devflow-pi 后失效。

/devflow project-init 会先读取当前项目已有的 .devflow/planning/PROJECT.md 与 .devflow/planning/navigation/INDEX.md：仅回填仍存在于项目根目录内的已登记前后端路径，删除或越界的历史路径会被忽略。随后可选择复用已有边界、复用边界并重建索引，或手动覆盖。初始化模式使用选择器提供“只读规划（默认）”和“写入初始化”；选择后者并确认，只会创建 Devflow 的 .devflow/planning/ 与 .devflow/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>/.devflow/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 是产品壳和资源检查，并验证 Node ≥20、Playwright Runtime manifest、可启动 Chromium、测试环境目录及安全运行目录；TUI 内的 /devflow doctor 还会验证活动 Extension、32 个必需 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
    # 其余四个插件目录同理

启动已发布的 Devflow Pi 后：

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

/devflow doctor 检查 4 个运行时 Extension、32 个 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，它同样只恢复状态而不自动执行。

窗口操作指引与干净会话

Devflow 会在输入框上方显示“当前 Feature 交付链路”：它基于只读状态快照展示已知步骤、当前节点、完成数、工作流/执行状态、当前允许的操作，以及安全恢复方案。使用 /devflow control 打开交互式控制台：它只会在状态检查器允许时提供启动当前步骤、审查并批准推进、安全恢复或取消当前 Feature；每个有写入影响的操作都会重新读取状态并沿用已有确认流程。面板不提供重试或重置当前节点，避免破坏 revision、checkpoint 和证据链。

正式节点经用户批准后，Devflow 会把已校验的状态和产物引用固化为内容校验的 handoff，再自动创建干净 Session 执行下一节点。交接期间工作流冻结；只有新 Session 成功认领并消费同一份 handoff 后才解除冻结。Devflow 不使用 OMP 的模型摘要 handoff，因此 .devflow/planning/STATE.md 仍是唯一流程事实源。

需求验收测试与 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、且已在初始化 .devflow/planning/toolchain.md 发现的测试运行器命令。任何失败、未执行、人工待执行或环境阻塞用例都会阻止 CP-4。
• 验收不是代码完成后的临时手工检查。它是需求基线在编码前派生并冻结的完整测试集，覆盖主流程、异常、边界、权限、迁移、兼容、韧性和工作负载义务；代码只能补充执行适配信息，不能改变测试意图。
• 验收失败不会创建另一套人工台账，而是进入 acceptance-remediation：诊断 → 修复 → code-index 刷新 → 原冻结 TC-* 重跑。
• CP-4 通过后只进入一个 workflow-release-closeout 步骤，统一写入 .devflow/planning/milestones/current-CLOSEOUT.md 并更新项目状态、导航和版本记录。

正常使用不需要记忆底层命令：在 Devflow 工作流中按步骤继续即可。需要排查时，可用 devflow_acceptance_tests 查看冻结套件，或由工作流调用 devflow_tdd_evidence 与 devflow_run_acceptance_tests 生成 Core 指定写入的证据；不要手写“已测试”来替代结果文件。本地 hook 拒绝 Agent 文件工具与 shell 访问 control.db 及 Devflow 数据目录 projects/、拒绝写入 canonical 验收结果文件，并默认拒绝访问 .devflow/runs/ 运行工件，仅白名单放行 result.json（Read 类读取工具仍可读取 acceptance-results.json；trace、截图、网络工件和 runtime.log 由用户本地查看）。它是防误用，不构成对同系统用户恶意进程的安全隔离。

Core 软门禁模式

默认情况下，Core 生成的测试绑定、追溯、merge gate、产物有效性和图谱新鲜度问题会记录为 advisory，交给 AI 审查决定继续、修改或阻塞；只有控制面损坏、越权路径、并发冲突等安全问题仍会硬阻断。需要临时恢复旧的严格门禁时，启动前设置 DEVFLOW_SOFT_GATES=0。

更新

升级 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 因而可以独立缓存单个插件，而不会留下指向缓存外部的断链。

核心不变量

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

Devflow MCP（阶段 B）

devflow-pi mcp --client <name> 通过 stdio 提供四个 feature 级工具：validate_feature、run_feature、get_feature_report 和 dsl_draft_validate。Server 只做输入校验、授权、审计和调用包内 Core；不读取或导出 trace、截图等运行工件，也不能确认批准。缺批准的用例仍需在 /devflow 面板完成批准。

授权文件位于 $DEVFLOW_HOME/mcp.json（默认 ~/.devflow-pi/mcp.json），例如：

{
  "schema_version": 1,
  "clients": { "claude-code": { "projects": {
    "/abs/path/to/project": {
      "features": ["order"],
      "permissions": ["validate", "run", "report", "dsl_draft"],
      "environment_profiles": ["local"]
    }
  } } }
}

这里的 --client 是声明式身份，用于匹配授权和写入审计，不是密码学认证；stdio 调用方与 Server 是同一台机器上的同一用户。Claude Code 注册：claude mcp add devflow-acceptance -- devflow-pi mcp --client claude-code。Codex 在 config.toml 中注册：

[mcp_servers.devflow-acceptance]
command = "devflow-pi"
args = ["mcp", "--client", "codex"]

run_feature 是同步调用，默认最多运行 2 小时，可用 --run-timeout-seconds 下调；客户端也应把 MCP 请求超时设得足够长，并启用 progress。审计写入 $DEVFLOW_HOME/mcp-audit/。批准仍只能在 /devflow 面板完成。

Core 在 MCP Server 的进程环境中执行，因此注册 Server 时要把被测环境需要的变量一并传入：HTTP adapter 的基础地址变量（如 DEVFLOW_TEST_BASE_URL）和环境 profile 中 secret_env 声明的密钥变量；缺失时对应用例会是 failed 或 blocked。mcp.json 的 environment_profiles 只约束 devflow_playwright 绑定引用的 profile；HTTP adapter 的目标地址来自这些环境变量，不受 mcp.json 授权约束，应由启动 Server 的人控制。run_feature 在有用例未通过时仍返回报告，是否通过以其中的 gate 为准。