OpenFeel — AI Agent 开发流程治理 CLI
📚 版本能力概览:docs/VERSIONS.md | 逐版本明细:CHANGELOG.md
⚡ 当前适配 harness:opencode(默认) | Claude Code(
--tools claude,v1.1.6 起) | DSH(--tools dsh,v1.3.0 起) | 默认模型:DeepSeek V4(主力推理)+ GLM-5.3-flash(交叉审查)+ DeepSeek-flash(多模态视觉)
⚠️ 下文示例命令
openfeel <cmd>为安装后的一般使用者用法;若在本仓库源码中开发/执行,请改用node bin/openfeel.js <cmd>(全局openfeel可能滞后于本仓——未随本仓库源码同步更新)。
OpenFeel 是一个 TypeScript CLI 工具,为 AI Agent 开发提供端到端的流程治理。核心理念:「提示词瘦身,流程入工具」 —— Agent 不靠读长文本理解流程,而是通过 flow.json 获取当前状态和下一步指令。
两种模式:Feel Mode(流程模式)与 Free Mode(自由模式)
feel_mode 决定 OpenFeel 是否强制流程。两个模式共享同一套状态机、数据与硬门禁,区别只在「流程是否被强制」:
| 模式 | 配置值 | 行为 | 适合 |
|---|---|---|---|
| Feel Mode(流程模式) | enabled |
按门禁走流程:要求/催促创建需求与阶段、preflight 严格(先读后写)、系统提示是完整 Feel 纪律 |
团队协作、需要可审计的交付 |
| Free Mode(自由模式) | disabled |
不强制流程:是否建需求/阶段由 AI 判断、preflight 只提示、提示词切「Free Mode」;但状态机 / done 门 / 阶段验证门 / 归档判据 / blocking REV / 写入门禁仍然有效 |
探索、一次性任务、个人快速迭代 |
- 默认:v1.5.18 起为 Free Mode(全新安装开箱宽松);更早版本默认 Feel Mode。
- 切换(即时生效;项目级覆盖全局):
openfeel config set feel_mode enabled # 本项目 → Feel Mode
openfeel config set feel_mode disabled # 本项目 → Free Mode
openfeel config set preferences.feel_mode enabled --global # 全局默认(未显式声明的项目继承它)
openfeel config effective feel_mode # 查看生效值与来源
- 不要和
workflow_mode混淆:feel_mode决定「是否强制流程」;workflow_mode(full/fast/general)决定「走流程时走多少道关」——两者正交,见下文「快速迭代模式」。
📦 最新版本 v1.5.20(适配器独立发 npm,社区市场可安装) — 适配器
dsh/以独立 npm 包openfeel-dsh随openfeel同步发布(版本 lockstep;requiresCli声明所需 CLI 下限),因此社区插件市场(awesome-dsh-plugin / dshmarket / 1024Store / dshbase / dsh.market 等)可凭 npm 身份收录并一键安装;DSH 官方「发现」页仍可用 format 1 索引docs/market/index.json添加。CLI 与门禁仍是必需组件:安装适配器后仍需npm i -g openfeel(供门禁使用)+ 重启宿主。版本能力概览见 docs/VERSIONS.md。
快速开始
npm install -g openfeel # 安装(Node ≥ 20)
openfeel init ./my-project # 初始化新项目
openfeel update # 已有项目?一键部署平台适配器
openfeel migrate # 存量旧布局项目?一键迁移(检测/备份/回滚)
openfeel flow status # 查看流水线
openfeel flow phases # 查看合法 phase 与转移表
openfeel setup --tools claude # 显式启用 Claude Code 适配器(可选)
npm install -g openfeel@latest # 更新到最新版本
💡
init用于新项目首次部署,update为已有项目增量更新(适用于init之后再引入 OpenFeel 的项目)。存量旧布局项目(opencode 适配器:项目内.opencode/agents|skills|instructions)用openfeel migrate迁移到全局部署。框架资产(agents/skills/AGENTS.md)经openfeel setup全局部署,项目内不再生成.opencode/agents|skills。
推荐用法:需求驱动 + 快速迭代(fast)
日常开发默认推荐 fast:计划审查 + 代码审查各单轮,跳过方案/测试相位;大改动或架构变更再用 full。
openfeel req add "接入 DSH 适配器" --workflow-mode fast # 1. 发布需求
openfeel req claim REQ-NNN # 2. 认领
openfeel plan stage add vX.Y.Z-stage-NN --workflow-mode fast # 3. 建 fast 阶段
openfeel req link --stage vX.Y.Z-stage-NN --requirement REQ-NNN # 4. 关联
openfeel flow next # 5. 按调度迭代
- fast(默认推荐):日常迭代;保留计划审查与代码审查,跳过 scheme/test;
- full:大改动 / 架构变更,完整六关;
- general:无流水线的零散任务,仅需求级合法;
- 需求关联阶段后,全部关联阶段 done 时自动收口需求。
- 完成必审验(v1.5.8 / REQ-027):需求
done前必须openfeel req review <id> …+openfeel req verify <id> …(两者均--result pass);阶段archiving → done前必须openfeel stage verify <id> …且该阶段关联需求全部done——缺证据即被拒,--force不绕过。
Claude Code 适配器(v1.1.6 起)
与 opencode 适配器并存,默认不启用(须显式
--tools claude)。
- 启用:
openfeel setup --tools claude(或--tools opencode,claude双 harness)。 - 部署资产到
~/.claude/:CLAUDE.md(全局约束,受管区三态,用户已有内容 append 不覆盖)、agents/(10 个,含feel)、skills/(22 个共享源)、settings.json(注入"agent":"feel"+"permissions":{"defaultMode":"auto"},用户既有键逐字保留;无则创建、有则不覆盖——用户主权键model不被改写)。 - 升级:
npm i -g openfeel@latest→openfeel setup --tools claude;首次创建~/.claude/{agents,skills}后须重启会话或/reload-skills使新 skill/agent 生效;CLAUDE.md于下次会话生效。仅npm i -g不刷新全局资产。 - 默认零触:不带
--tools时~/.claude/零变化。
DSH 适配器(v1.3.0 起)
与 opencode / Claude Code 适配器并存,默认不部署;适配器同时以独立 npm 包
openfeel-dsh发布(v1.5.20 起,供 DSH 插件市场安装),openfeel单包内仍自带dsh/。
npm i -g openfeel@latest # 1. 安装/升级(单包,已含 dsh/)
openfeel setup --tools dsh # 2. 部署到 DSH profile(默认全部;可 --dsh-profile web)
# 3. 重启 DSH 宿主
社区市场安装(v1.5.20 起):适配器已是独立 npm 包,可直接 dsh plugin add openfeel-dsh;仍须全局安装 CLI(npm i -g openfeel,门禁在 CLI 里),但不要再执行 openfeel setup --tools dsh——setup 会把 profile 依赖改写成本地 link:,覆盖市场安装版本。二选一,最后重启宿主。
- 写入
<DSH_HOME>/profiles/<name>/package.json:dependencies["openfeel-dsh"] = "link:<openfeelRoot>/dsh"+dsh.profile.bundles += "openfeel-dsh",并在需要时执行pnpm install(依赖未变化且链接有效时跳过)。 - 前提:DSH
0.2.0-rc.2、Node ≥ 20.17、存在 DSH profile、全局openfeel可用(openfeel-dsh的requiresCli声明所需 CLI 下限;适配器不做硬校验,CLI 过旧时以门禁报错为准)。 - 升级:
npm i -g openfeel@latest→ 重启 DSH;link:指向同一路径,随包更新(社区市场安装则同时升级openfeel-dsh)。 - 开发态可直接
link:仓库dsh/;详见 dsh/README.md 与 dsh/ADAPTER.md。 - 写入门禁第 4 类(无法静态判定写入目标)默认 告警放行、不阻断,只落审计 + 一行 stderr(不消耗模型轮次);已知安全命令可用
OPENFEEL_SHELL_ALLOW白名单(||分隔,折叠空白后整条命令全等,strict档同样生效),例如OPENFEEL_SHELL_ALLOW="Build.bat all || node Tools/gen-typings.js"。 openfeel update --tools dsh不适用(DSH 是全局部署)。
快速迭代模式(v1.1.7 起)
本节讲
workflow_mode(走流程时的关卡密度),与上文feel_mode(是否强制流程)正交;新部署默认 fast(config.yaml defaults.workflow_mode),可逐阶段覆盖与切回。
- 快线链:
plan_pending → plan_review → plan_passed → exec_running → review_pending → review_passed → archiving → done(跳过 6 项scheme_*/test_*;计划审查与代码审查保留单轮,review_failed可回环重试)。 - 选择与切换:
openfeel plan stage add <name> --workflow-mode full|fast|general(新建阶段);openfeel stage set <stage> --workflow-mode full|fast|general(单阶段切回);openfeel config set defaults.workflow_mode full|fast|general(项目默认记忆)。general仅需求级合法(v1.2.1 起,见 docs/VERSIONS.md)。 - 查看(只读):
openfeel flow mode [--stage <id>] [--json](当前模式 + 来源);openfeel flow phases [--mode full|fast|general] [--stage <id>](按模式查看转移表)。 - 默认自动推进开启:新部署默认
auto_advance: enabled(v1.1.7 起);如需关闭:openfeel config set auto_advance disabled。 - v1.3.3 修复(fast 结构性缺口):fast 快线新增返工边
review_passed → exec_running(flow advance --reason落审计);无 op 的 fast 阶段可用flow review add --stage <id>挂阶段级 REV;写入门禁对空仓新增文件与docs/**/ doc-note 放行(源码仍要求exec_running);plan stage add后原子聚焦。阶段 ID 归一化与plan/目录映射见 docs/commands.md。
完整中文文档:README.zh-CN.md(含 Claude Code / DSH 适配器、命令参考与核心概念)
No comments yet. Be the first to write one.