@guanlin4924/devflow-pi 0.1.0

package/README.md

@@ -0,0 +1,164 @@
+# Devflow for Oh My Pi
+
+面向项目代码开发的 OMP 原生能力仓库。仓库同时提供 Agent Skills、运行时 extension、task agents、项目配置模板和 marketplace 插件目录。
+
+完整的第一性原理拆分、控制面不变量和对抗式审查见 [`docs/OMP-NATIVE-ARCHITECTURE.md`](docs/OMP-NATIVE-ARCHITECTURE.md)。
+
+## Devflow 专项 Pi（当前功能分支）
+
+`feat/devflow-pi-distribution` 新增了一个独立产品入口：它把固定版本 OMP SDK 当作通用 Runtime，把六个 Devflow 插件当作产品内置能力。目标项目不再需要复制本仓库到 `.skills`，也不需要另装或覆盖官方 `omp` 命令。
+
+当前为本地发行验证版，要求 Bun `>=1.3.14`：
+
+```bash
+git switch feat/devflow-pi-distribution
+npm install
+npm link
+
+cd /path/to/your-project
+devflow-pi init
+devflow-pi doctor
+devflow-pi
+```
+
+进入 TUI 后：
+
+```text
+/devflow doctor
+/devflow project-init
+/devflow explain-state
+/devflow start <feature>|<phase>
+/devflow continue
+/devflow advance
+/devflow checkpoint
+/devflow resume
+/devflow-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` 默认只能统计当前项目的隔离 Session。
+- 以 `devflow-pi` 启动时，确定性工作流和代码索引脚本只从产品包内六插件解析；项目遗留 `.skills` 不会覆盖专项版本。`install.sh --apply` 兼容模式仍可使用项目 `.skills`。
+
+`devflow-pi doctor` 是产品壳和资源检查；TUI 内的 `/devflow doctor` 还会验证活动 Extension、30 个必需 Skills、6 个 Agents，以及 `@smol/@task/@slow` 三个不同的已认证模型。专项 Pi 默认用 `@slow` 处理用户交互和规划，`@smol` 仅负责只读侦察，`@task` 仅负责受限执行与验证。完整产品设计见 [`features/20260805Devflow专项Pi发行版.md`](features/20260805Devflow专项Pi发行版.md)，双模型控制规范见 [`features/devflow-agent-orchestration/00-架构总览.md`](features/devflow-agent-orchestration/00-架构总览.md)。
+
+专项 Pi 会复用 `~/.omp/agent/` 里的登录凭据和可用模型列表，但模型角色选择写在 `~/.devflow-pi/agent/` 这个产品级目录里，不写入目标项目，也不读取官方 OMP 的 Session。首次进入专项 Pi 后，先在模型角色界面把 `smol`、`task`、`slow` 配成三个不同模型，再执行 `/devflow doctor`；未配好时 `/devflow start` 会被拒绝。
+
+现有 `install.sh --apply` 模式仍保留，作为未迁移项目的兼容入口；下文描述的是该兼容模式。
+
+## Skill 如何被加载
+
+Skill 仍采用标准目录结构：
+
+```text
+<skill-name>/
+  SKILL.md
+  scripts/
+  references/
+  assets/
+```
+
+`.skills` 不是 Pi/OMP 的默认自动发现目录，但 OMP 可以通过项目 `.omp/config.yml` 的 `skills.customDirectories` 直接扫描仓库内各插件的 skill 目录。因此无需再创建 `.claude/skills` 或 `.codex/skills` 软链接。
+
+```yaml
+skills:
+  customDirectories:
+    - .skills/plugins/devflow-core/skills
+    - .skills/plugins/devflow-intel/skills
+    # 其余四个插件目录同理
+```
+
+## 完整接入：项目固定版本
+
+```bash
+git submodule add https://gitee.com/guanlin4924/skill-kit.git .skills
+bash .skills/install.sh --apply
+```
+
+`install.sh --apply` 是完整 Devflow Runtime 的标准入口。它不仅安装能力目录，还部署 `/devflow` 所依赖的 Extension、task agents、项目策略和生命周期配置。安装器会执行 postflight；已有但不兼容的 `.omp/config.yml` 会使安装失败，不会再以警告方式假装安装完整。
+
+安装器只生成以下 OMP 原生资源：
+
+```text
+.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
+bash .skills/install.sh --apply --force-config
+```
+
+启动 OMP 后：
+
+```text
+/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` 只创建 Feature 状态，不会自动启动整条流程。`/devflow continue` 只运行当前一个工作流步骤并停止；产物审查后由用户显式执行 `/devflow advance`，checkpoint 也必须由用户通过 `/devflow checkpoint` 确认。恢复已有流程使用 `/devflow resume`，它同样只恢复状态而不自动执行。普通中文输入“初始化项目”“查看状态”“需求：……”会进入相应的受控只读分诊，不会偷偷启动实现或状态迁移。
+
+## Marketplace 能力包
+
+仓库也可作为 OMP marketplace 使用，但 Marketplace 安装只用于发现和安装 Skills、Agents、命令等能力内容，不代表完整 Devflow Runtime 已启用。OMP 不会从 Marketplace 安装加载 `package.json` 中的 `omp.extensions`，因此下面的命令不能替代 `bash .skills/install.sh --apply`：
+
+```bash
+omp plugin marketplace add https://gitee.com/guanlin4924/skill-kit.git
+omp plugin install --scope project devflow-core@devflow
+omp plugin install --scope project devflow-intel@devflow
+omp plugin install --scope project devflow-requirements@devflow
+omp plugin install --scope project devflow-design@devflow
+omp plugin install --scope project devflow-implementation@devflow
+omp plugin install --scope project devflow-quality@devflow
+```
+
+完整研发流程仍必须在项目固定版本模式下运行安装器。安装或升级 Extension 后重启会话；仅刷新 Skill/Command 时可使用 `/reload-plugins`。
+
+## 插件边界
+
+| 插件 | 职责 | 主要能力 |
+|---|---|---|
+| `devflow-core` | 控制面 | 流程状态、检查点、制品登记、单写者保护、`/devflow` |
+| `devflow-intel` | 项目事实 | 代码索引、查询、导航、上下文同步、`project-scout` |
+| `devflow-requirements` | 需求决策 | 分诊、探索、领域建模、可行性、需求基线、对抗审查 |
+| `devflow-design` | 契约设计 | API/UI/前后端方案、功能拆解、集成一致性 |
+| `devflow-implementation` | 代码变更 | 变更计划、隔离执行、Bug 修复 |
+| `devflow-quality` | 独立验证 | 代码审查、主流程用例、UAT、里程碑审计与归档 |
+
+每个 skill 恰好归属一个插件，插件目录中的实体文件是唯一真本；仓库根目录的同名入口只是兼容现有脚本和人工浏览的相对链接。marketplace 因而可以独立缓存单个插件，而不会留下指向缓存外部的断链。
+
+## 核心不变量
+
+- `.planning/STATE.md`、workflow 和 artifact registry 只允许 Devflow 工具写入。
+- 子 agent 不更新控制面，只返回证据、结构化审查结果或隔离 patch。
+- 索引是加速器，不是真相源；过期时回退到 LSP、搜索、源码和测试。
+- 人工 checkpoint 不得在 headless 模式静默通过。
+- semantic correctness 不能靠 prompt 保证，必须由契约、确定性校验、独立审查和可复现测试共同约束。
+
+## 更新
+
+```bash
+git -C .skills pull
+bash .skills/install.sh --refresh
+git add .skills .omp .agent-gates
+```
+
+刷新完成后重启 OMP 并再次运行 `/devflow doctor`。如果模板新增了强制配置而项目配置被保留，安装器会拒绝完成；审查后使用 `--force-config` 更新。

package/docs/OMP-NATIVE-ARCHITECTURE.md

@@ -0,0 +1,104 @@
+# Devflow OMP 原生架构
+
+## 结论
+
+Pi/OMP 不把任意 `.skill` 文件或名为 `.skills` 的目录自动视为 skill。稳定的能力单元是：
+
+```text
+<skill-name>/SKILL.md
+```
+
+Pi 默认扫描项目 `.pi/skills/` 和兼容的 `.agents/skills/`；OMP 默认扫描 `.omp/skills/`，也允许用 `skills.customDirectories` 指向任意 skill 集合目录。本项目选择直接扫描 `.skills/plugins/*/skills`，不生成 `.claude/`、`.codex/` 或 `.omp/skills` 镜像。
+
+依据：
+
+- [Pi Skills](https://pi.dev/docs/latest/skills)
+- [OMP Skills](https://github.com/can1357/oh-my-pi/blob/main/docs/skills.md)
+- [OMP Settings](https://github.com/can1357/oh-my-pi/blob/main/docs/settings.md)
+- [OMP Marketplace](https://github.com/can1357/oh-my-pi/blob/main/docs/marketplace.md)
+- [OMP Extensions](https://github.com/can1357/oh-my-pi/blob/main/docs/extensions.md)
+
+## 第一性原理
+
+项目开发 agent 的目标不是“调用更多 prompt”，而是以最小不可逆风险交付可验证的正确变更。因此能力按其本质分层：
+
+| 能力本质 | OMP 承载面 | 原因 |
+|---|---|---|
+| 领域知识、步骤、模板 | Skill | 按需加载，避免常驻上下文膨胀 |
+| 必须强制的不变量 | Extension/tool | prompt 不能作为并发控制或权限边界 |
+| 独立探索、实现、审查 | Task agent | 隔离上下文与写权限，避免角色自证 |
+| 项目级默认策略 | `.omp/config.yml` | 固定发现源、审批、并发、递归与隔离 |
+| 可安装能力边界 | Marketplace capability pack | 独立启停 Skills/Agents 等内容；不承担强制运行时加载 |
+| 项目事实与进度 | `.planning/` | 跨会话持久化；不能依赖聊天记忆 |
+
+事实优先级固定为：可执行测试与运行结果 → 当前源码/LSP → 已批准契约 → 新鲜索引 → 模型推断。索引只能加速定位，不能覆盖源码事实。
+
+## 插件拆分
+
+| 插件 | 唯一责任 | Skills | Extension/tools | Task agents |
+|---|---|---|---|---|
+| `devflow-core` | 控制面 | pipeline、orchestrator、project-context | 状态、初始化、CAS 转移、制品、生命周期、`/devflow` | — |
+| `devflow-intel` | 项目事实发现 | code-index、query、context-sync、navigation | code index、context cursor | `project-scout` |
+| `devflow-requirements` | 需求决策 | triage、wayfinder、domain、feasibility、baseline | — | `requirements-auditor` |
+| `devflow-design` | 跨层契约 | API/UI/前后端/拆解/集成/设计规则 | design rule pack | `contract-auditor` |
+| `devflow-implementation` | 有界代码变更 | change-plan、execute、bug-fix | — | `implementation-worker` |
+| `devflow-quality` | 独立质量结论 | review、mainflow、UAT、audit、archive | mainflow cases | reviewer、verification runner |
+
+每个插件的 `skills/` 存放实体真本，仓库根部的同名目录是兼容链接。原因是 marketplace 会把单个插件目录缓存为独立包：插件内部不能依赖指向包外部的 skill 链接。
+
+## 控制面不变量
+
+1. `.planning/STATE.md`、workflow 定义、artifact registry 和 `.next-intent` 只能由 Devflow 工具写。
+2. 所有控制面 writer 共用 `.planning/.devflow.lock`，文件用临时文件 + `fsync` + 原子 rename 写入。
+3. 每次状态推进必须携带刚读取的 `expectedRevision`；过期写返回 `stale_revision`，不产生部分副作用。显式 force 初始化是独立的用户批准操作。
+4. artifact registry 携带 `state_revision`，它是从状态派生的缓存，不是第二真相源。
+5. task agent 不推进状态、不批准 checkpoint；只有父会话能提交状态转移。
+6. 人工 checkpoint 不在 headless 场景自动通过。
+7. extension 只暴露白名单脚本工具，不提供任意脚本路径执行器。
+
+## 对抗式审查
+
+| 攻击/失败方式 | 后果 | 当前防线 | 剩余边界 |
+|---|---|---|---|
+| 两个 agent 同时推进同一步 | 丢更新、重复 checkpoint | project lock + revision/CAS | NFS 等非标准锁语义需另行验证 |
+| 模型直接编辑 STATE/workflow | 状态与制品漂移 | `tool_call` 拦截 + 专用 writer tools | extension 是进程内代码，安装源必须可信 |
+| 索引过期仍被当作真相 | 修改错文件或漏影响面 | advisory index + LSP/源码回退 | 大仓库降级扫描会更慢 |
+| 子 agent 自己验证自己 | 漏报和确认偏差 | 实现、审查、验证角色拆开 | 是否接受风险仍由父会话/用户决定 |
+| skill 在根目录和插件目录复制 | 两份规则逐渐分叉 | 插件实体唯一真本 + 根兼容链接 + 布局测试 | Windows checkout 的 symlink 策略需在发布环境验证 |
+| marketplace 只缓存插件子目录 | 跨包链接断裂或 Extension 未加载 | 每个插件自包含 capability 内容；完整 Runtime 由安装器部署 | 跨插件工作流要求全套能力包和项目 Runtime |
+| 任意脚本包装器扩大执行面 | prompt 注入获得任意执行 | 按插件拆分的枚举/固定脚本工具 | 脚本本身仍需代码审查 |
+| OMP 导入外部 harness 配置 | 规则冲突、工具面失控 | project config 禁用外部配置发现源 | 用户全局模型凭据仍由用户管理 |
+
+## 安装模型
+
+项目固定版本模式是完整研发流水线的标准安装方式：`.skills` 作为 submodule，运行 `install.sh --apply` 生成 `.omp` 配置、extensions、agents 和 gate policy，并执行完整性 postflight。
+
+Marketplace 模式只适合按能力启停 Skills、Agents、Commands 等内容。OMP Marketplace 安装不会加载 `package.json` 的 `omp.extensions`，所以即使六个插件全部安装，也不等价于完整 Runtime。完整流水线仍需项目安装器；更新 Extension 后必须重启会话，仅 Skill 变化可 reload plugins。
+
+## 启动与模型门禁
+
+`/devflow start <feature>|<phase>` 不是提示词别名。Core Extension 按以下顺序执行：
+
+1. 运行 `/devflow doctor` 等价预检；
+2. 验证 Extension tools、Skills、Agents、脚本和项目配置；
+3. 用 OMP 模型解析器解析 `@smol`、`@task`、`@slow`；
+4. 拒绝未解析角色或三个角色落到同一具体模型；
+5. 初始化 workflow/state/artifact registry；
+6. 调用 inspector 生成最小当前步骤信封；
+7. 通过 `sendUserMessage` 自动启动 `workflow-pipeline`。
+
+进入 runtime loop 后，每次成功迁移都重新 inspect 并继续下一合法步骤，直到人工 checkpoint、`blocked`、工具硬失败或 `workflow_complete`。因此“自动跑完整流程”表示自动跑到下一个必须由人或外部事实决定的边界，不表示自动批准 checkpoint。
+
+`task.agentModelOverrides` 以 agent name 为键，优先于 agent frontmatter 和父模型继承。模型角色的具体 provider/model 仍由项目所有者在 OMP 项目 role store 中选择，仓库不硬编码供应商凭据或可能过期的模型 ID。
+
+## 验证门槛
+
+发布前至少通过：
+
+- 每个根 skill 唯一映射到一个插件实体目录；
+- 单插件复制到独立缓存后不存在断链 skill；
+- 所有 SKILL frontmatter 只有稳定的 `name`、`description`；
+- 安装器不创建 `.claude/`、`.codex/` 或 `.omp/skills`；
+- 同 revision 并发写只有一个成功；
+- Ruby/Python/JSON/Bash 语法检查和 Bun extension build；
+- 在实际安装的 OMP 版本中做一次 extension 加载与 `/devflow status` 冒烟测试。

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@guanlin4924/devflow-pi",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
+  "license": "UNLICENSED",
+  "bin": {
+    "devflow-pi": "./src/cli.ts"
+  },
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "doctor": "bun run src/cli.ts doctor",
+    "test:devflow-pi": "bun test tests/devflow-pi",
+    "test": "bun test tests/devflow-pi && python -m pytest",
+    "check": "bun test tests/devflow-pi && python -m pytest"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "dependencies": {
+    "@oh-my-pi/pi-coding-agent": "17.2.7"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "src",
+    "plugins",
+    "!plugins/**/__pycache__",
+    "!plugins/**/*.pyc",
+    "!plugins/**/tests",
+    "templates",
+    "docs",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}