OpenFeel

OpenFeel CLI JSON 输出契约(v1.5.10)

§1 单文档规则

  1. --json 模式下 stdout 恰好输出一个 JSON 文档;不得混入标题、进度、警告等人类文本(唯一例外:flow advance --json 成功输出保持人类文本,见 §7/§8)。
  2. schemaVersion 恒为运行时首键且值为 1(构造序必须写成 { schemaVersion: 1, ...doc },禁止 { ...doc, schemaVersion: 1 })。
  3. 可选字段缺省时使用 null;集合字段使用 [];映射字段使用 {};不使用 undefined(JSON.stringify 会丢键)。
  4. 既有字段只增不删、不重排、不改类型;键的语义与取值规则以本文件冻结表为准。
  5. JSON 输出与人类可读输出共享同一业务判定,禁止为 JSON 分支复制第二套来源判定。
  6. 双轨判定(stage-97 §13.6):成功 JSON 分支判定(options.json,Commander 已注册选项;直接 parse 与 runCli 两条入口均可达)与失败 envelope 判定(isJsonMode() 单点,由 runCli 预扫描置位、命令层不得自行 set)为两条授权入口;测试直接 parse 失败路径须显式 setJsonMode(true) 并在 finally 复位。

§2 退出码语义表(权威口径 R-cp-1)

退出码 语义 kind 说明
0 成功 — 命令完成(含 ok:false 等「成功文档 + 非 0」情形见 §5)
1 预期拒绝 refusal 门禁拒绝、相位非法、非法参数 / 用法错误
2 并发写冲突 refusal 保留 EXIT_CONCURRENT;可重试
3 内部错误 internal 本版新增;既有 0/1/2 语义零改动

§3 code → kind → exitCode 映射表(单一权威)

code kind exitCode
NO_INIT refusal 1
INVALID_ARGUMENT refusal 1
STAGE_NOT_FOUND refusal 1
PHASE_TRANSITION_ILLEGAL refusal 1
PHASE_PATH_NOT_FOUND refusal 1
BLOCKING_REVIEWS refusal 1
ARCHIVE_GATE_REJECTED refusal 1
ARCHIVE_WRITE_FAILED internal 3
PROJECT_NOT_FOUND refusal 1
FLOW_CONCURRENT_CONFLICT refusal 2
INTERNAL_ERROR internal 3
ARCHIVE_FAILED refusal 1(stage-97 实现:archive <stage> --json 失败(refusal/1))
ARCHIVE_EXISTS refusal 1(v1.2.4 A1:目标归档文件已存在且未显式 --force;零写盘)

§4 错误形态(envelope 与 legacy 双形态)

4.1 新 envelope

{
  "schemaVersion": 1,
  "error": {
    "code": "INVALID_ARGUMENT",
    "kind": "refusal",
    "message": "……",
    "detail": null
  }
}

4.2 legacy 形态(零破坏保留)

{
  "schemaVersion": 1,
  "error": "gate-rejected",
  "notDone": ["..."],
  "blockingOpen": ["..."],
  "errorKind": "refusal"
}

4.3 唯一判别规则

typeof doc.error === 'string'  → legacy
否则(object)                 → envelope

§5 43 出口冻结表

计数口径:43 个成功 JSON 出口(#1~#43)。flow advance --json 为错误封装开关,不计入(见 §7)。v1.5.10 / stage-125 新增 #43 dashboard(v1.5.8 / REQ-030 新增 #42 req release-check)。

# 出口 顶层键序 元素/嵌套键(实测) 条件键/形态
1 flow status schemaVersion,pipeline,stages,counts pipeline{phase,current{stage,op}};stages[]{id,phase,status,deps,ops,workflowMode,requirementId,reviewTier,effectiveReviewTier,opsSummary{total,byState}};counts{total,done,active} 恒在;stages[] 末位新增 5 字段(既有 5 字段键序/类型不变,见 §12.2);requirementId 恒在、可空(null);byState 仅含观测态
2 flow overview 已初始化:schemaVersion,phase,current,summary,stages,reviews,health,logs current{stage,op};summary{phase,currentOp,retryCount,stagesCount,opsCount,reviewItemsOpen,recentLogs};stages[]{id,phase,status,opsTotal,opsDone};reviews{open,blockingOpen,nonBlockingOpen,resolved,closed};health{ok,pass,warn,fail} 形态变体:未初始化恰 schemaVersion,initialized(false)
3 flow current schemaVersion,stage,op,phase 均为 string(空态 '') 恒在
4 flow metrics schemaVersion,agents agents[]{agentName,totalRuns,successfulRuns,failedRuns,totalRetries,totalDurationMs,avgDurationMs,successRate} 恒在
5 flow phases schemaVersion,phases,transitions,advanceAccepted,transitionsDiff,workflowMode,reviewTier,displayReviewTier,effectiveReviewTier transitionsDiff{missing,extra,changed} 恒在;末位新增 2 键(既有 7 键不变,见 §12.3)
6 flow mode schemaVersion,stage,mode,source,modes modes{full,fast,general}(各为 transitions 映射) 恒在
7 flow ops list schemaVersion,ops ops[]{stage,opId,title,state,fill,warning} warning 恒在,warning != null 仅当 fill==='empty' && state!=='done'(v1.5.16:done op 不再告警),其余 null
8 flow archive 成功:schemaVersion,version,stages,reviews,log,dryRun,eligible,unfinishedStages,blockingReviews,requirements stages/reviews/log/requirements 为 number;dryRun 为 boolean;eligible 成功恒 true;unfinishedStages / blockingReviews 成功恒 [];requirements = 随版本归档的终态需求数(v1.5.8 追加,末键) 失败为 legacy(见 §4;gate-rejected 9 键见 #8b;发布软门拒绝见 §4.2)
9 flow archive list schemaVersion,versions versions[]{version,counts};counts{stages,reviews,log,requirements} 或 null(老归档无 requirements 键 → 读侧不注入,视同 0) counts 恒在、可空
10 flow archive show schemaVersion,version,stages,reviews,log,requirements,counts,archived_at(本版首键重定位;v1.5.8 在 log 后追加 requirements,其余相对序不变) 嵌套透传归档文件原文(requirements? 为归档需求数组,老文件缺省) 失败为 legacy(见 §4)
11 flow health schemaVersion,ok,items,reconciled items[]{name,status,detail} reconciled 恒在,非 --fix 时 null;ok:false 仍为成功文档 + exit 1
12 req list schemaVersion,requirements requirements[] = RequirementData + 末位追加 linkedStages,progress;linkedStages[]{id,phase};progress{done,total};RequirementData 可选字段(target_version,priority,owner,claimed_at,body_path,parent_id,workflow_mode,carried_from,review,verification)条件出现(读侧宽容不注入);--include-archived 时归档需求再末位追加 archived:true 条件出现键(依据:src/core/req/types.ts 可选标记 + 读侧宽容不注入);两新键恒在且恒为末位;archived 仅归档需求出现
13 req show schemaVersion,requirement,stages,parent,children(活跃)/ schemaVersion,requirement,stages,parent,children,archived(已归档回退) stages:string[];parent:string|null;children:string[] parent 恒在、可空;archived:true 为末尾可选键(仅归档回退路径)
14 req split schemaVersion,parent,children children = RequirementData[] 恒在
15 req board schemaVersion,groups groups 键序 = REQ_STATUSES(7 值);值为数组 恒在
16 req next schemaVersion,requirement requirement 对象或 null candidates 条件出现键(仅 limit>1)
17 instructions schemaVersion,artifact,task,project_context,rules,dependencies,output,instruction,template,unlocks(C1) artifact{id,change,schema};project_context{tech_stack,workspace,project,config{execution_mode,auto_advance,merge_mode}};template 可空 template 恒在、可空
18 setup --check schemaVersion,status,cliVersion,deployedVersion deployedVersion 可空 status!=='ok' 仍为成功文档 + exit 1
19 flow next schemaVersion,stage,phase,phaseLabel,responsibleAgent,workflowMode,reviewTier,effectiveReviewTier,legalNextPhases,suggestedCommand,guards,blockingReviews blockingReviews[]{id,title,priority,op};guards:string[](本地化;顺序见 §12.1) 恒在(无活跃阶段亦为完整 12 键文档;可空字段 null、数组 [])
20 stage status 单阶段:schemaVersion,stageId,statusPath,fields,tasks,blockedBy;无参:schemaVersion,stages,count 单阶段 fields = 7 规范键 + raw(execMode,autoAdvance,status,reviewAgent,previousReviewAgent,updatedAt,workflowMode,raw);tasks[]{number,done,description};无参 stages[]{stageId,status,statusPath} blockedBy 可空(null);statusPath 绝对路径;无参空态 stages:[] + count:0
21 flow recover schemaVersion,initialized,phase,currentOp,stageStatus,blockedBy,pendingTasks,stageStats stageStats 为映射({} 空态);pendingTasks:string[] 未初始化:initialized:false + null / [] / {}(exit 0,镜像人类)
22 flow checkpoint list schemaVersion,stage,checkpoints,count checkpoints:string[] stage 可空(null = 全部);未初始化与空集合同形 checkpoints:[]
23 knowledge search schemaVersion,query,limit,offset,results results[]{title,category,date,enabled,content,summary};summary 为内容前 100 字(超出加 …) 空态 results:[] + exit 0
24 knowledge list schemaVersion,entries,count entries[]{title,category,date,enabled}(不含 content) 空态 entries:[] + exit 0
25 knowledge index schemaVersion,categories,recentUpdates categories[]{name,description};recentUpdates[]{date,category,title} index.md 缺失时 categories 为 4 分类缺省、recentUpdates:[]
26 knowledge dedup schemaVersion,threshold,categories,found,readOnly,matches matches[]{category,title,date,enabled,similarity,flagged};categories:string[] 恒 readOnly:true;无匹配 found:false + matches:[];非法阈值/分类走 envelope(refusal/1)
27 config get 项目:schemaVersion,scope,key,value;项目 --all:schemaVersion,scope,defaults;全局无 key:schemaVersion,scope,values;全局有 key:同项目形态 values = 7 全局键固定序(user.name,user.lang,preferences.auto_advance,preferences.review_mode,preferences.communication,preferences.confirm_threshold,preferences.feel_mode);defaults = 5 项目键固定序(execution_mode,auto_advance,merge_mode,workflow_mode,feel_mode,取自 resolveConfigDefaults) 全局缺省值 undefined → JSON null(人类显示空串;DEFAULT_PROFILE 回填后前 6 键通常有值,feel_mode 不在 DEFAULT_PROFILE 中故未设置时为 null);项目无 key 且无 --all → envelope INVALID_ARGUMENT(key-required);--all+--global → all-global-conflict;--all+key → all-with-key
28 config effective 无 key:schemaVersion,effective;有 key:schemaVersion,key,value,source effective 为受管键映射(键序 = EFFECTIVE_CONFIG_KEYS) 未知 key → envelope INVALID_ARGUMENT(refusal/1)
29 view list schemaVersion,count,reviews reviews[] 10 键:id,op,status,priority,title,filed_by,filed_at,blocking,canAutoFix,autoFixDetail blocking 缺省 true(!== false);canAutoFix 缺省 false(=== true);autoFixDetail 可空;空态 reviews:[];内部异常 JSON INTERNAL_ERROR/3(人类 1)
30 plan scheme list schemaVersion,stage,count,schemes schemes[]{stage,opId,title,filePath,draft,fill};filePath 为项目根相对路径 stage 可空(null = 全部);draft = flow.json 同 opId 存在 state:'draft'(跨阶段全局匹配,见 §13.5);fill 经 detectFillState;空态 schemes:[]
31 flow log schemaVersion,count,entries entries[]{time,agent,action,detail};time 原始 ISO(不截断);agent 经 normalizeAgentName 空日志与未初始化同形 entries:[] + exit 0
32 project overview schemaVersion,project,dirs,stats,entries,techStack project{name,version,description};dirs{src{exists,cli,commands,core,utils},opencode{exists,agents,skills},openfeel{exists,kb,plan,codeReview,bugs}};stats{tsSourceFiles,agentDefs,cliModules,kbEntries,planVersions};entries{available,cli,pkg,build};techStack{runtime,language,cliFramework,validation,config,fileMatch,test} dirs.* 子项目录不存在时 null(bugs 为 boolean);stats 恒 number;entries.available 反映 src 存在性
33 archive <stage> schemaVersion,stage,archivePath,opsCount,reviewsCount,knowledgeExtracts,generated archivePath 绝对路径;opsCount/reviewsCount 为 number;knowledgeExtracts:string[];generated{releaseNotes,skills,requirements} 三键(v1.5.8 追加,路径相对项目根) 阶段不存在 / 未初始化 → envelope ARCHIVE_FAILED/refusal/1;目标归档已存在且未 --force → ARCHIVE_EXISTS/refusal/1(零写盘);非法 --skill slug → INVALID_ARGUMENT/refusal/1(零写盘);异常 → INTERNAL_ERROR/internal/3(人类保持 1);generated 为追加键,既有 6 键键序/语义零改动
34 plan stage list schemaVersion,stages,count stages[]{id,phase,status,deps,workflowMode,opsTotal,opsDone};phase/status 可空,deps 恒数组 flow.json 注册阶段(声明序);workflowMode 经 resolveStageWorkflowMode;空态/未初始化 stages:[] + count:0 + exit 0;人类输出保持计划目录清单(不同视图)
35 model list schemaVersion,scope,agents agents[]{agent,provider,model,source};scope 回显 --scope(未指定 null) provider/model 按生效值首个 / 切分(无 / → provider:null);source = 生效层(default > project > global),无值 null
36 model get schemaVersion,scope,agent,provider,model,source 单 agent 六键;派生规则同 #35 非法 scope → INVALID_ARGUMENT/refusal/1;人类输出不变
37 flow retry schemaVersion,op,attempts,maxAttempts,exhausted,state attempts = getRetryCount(op);maxAttempts = op.max_attempts;exhausted = attempts >= maxAttempts 只读;未初始化 → NO_INIT;阶段不存在 → STAGE_NOT_FOUND;非法 opId / op 不存在 → INVALID_ARGUMENT(detail.reason)
38 lint i18n schemaVersion,target,ok,issues target:"i18n";issues[]{path,message};path ∈ {src/core/i18n-data/zh-CN.ts, src/core/i18n-data/en.ts} ok = issues.length === 0;ok:false 仍为成功文档 + exit 1;人类输出逐字不变
39 lint kb schemaVersion,target,ok,issues target:"kb";issues[]{path,message};path = .openfeel/kb/<file>(项目根相对) 无 kb 目录 → ok:true,issues:[] + exit 0;过期引用 → ok:false + exit 1
40 roadmap show schemaVersion,version,milestones milestones[]{title,theme,stage,deliverable}(表头驱动;兼容 3/4 列,缺列 null) 不传版本 → version:null,milestones:[] + exit 0;版本不存在 → INVALID_ARGUMENT/refusal/1;人类输出逐字不变
41 lint req schemaVersion,target,ok,issues,suspects,unknownCount,suspectCount target:"req";issues[]{path,message}(A 类 unknown-command);suspects[]{path,message}(B 类 suspect-command-group);两个计数为 number;path = .openfeel/requirements/<file> ok = (issues.length === 0)(与 #38/#39 一致);suspects 不参与 ok / 退出码;无需求目录 → ok:true,issues:[],suspects:[] + exit 0;A 类 → ok:false + exit 1;抑制行数 / 未闭合警告不进 JSON(见 §16)
42 req release-check schemaVersion,version,done,unfinished,counts done:string[] / unfinished:string[](需求 ID);counts{done,unfinished,other,total}(number) 只读软门:恒 exit 0(未完成需求只报告,不阻断);版本比较去单前导 v(v1.5.8 ≡ 1.5.8);「其它」= cancelled/rejected 只进 counts.other
43 dashboard schemaVersion,generatedAt,generator,project,requirements,stages,releases,blockingReviews,health,metrics schemaVersion 恒首键;generatedAt 为唯一非确定时间字段(测试不得断言其值);generator = openfeel/<version>;project{root,name,version};requirements{groups{7 状态},counts{7 状态},total}(groups/counts 键序恒 = REQ_STATUSES;元素 = RequirementData + linkedStages,progress,逐字沿用 #12);stages{pipeline{phase,current{stage,op}},items[]{id,phase,status,opsTotal,opsDone,workflowMode,requirementId},counts{total,done,active}};releases{gates[]{version,counts{done,unfinished,other,total},unfinished[]},archived[]{version,counts{stages,reviews,log,requirements?}\|null}}(counts 逐字透传归档文件 ArchiveCounts:v1.5.8 起含可选 requirements;归档文件缺失 / 损坏 / 不可读 → counts:null);blockingReviews[]{stage,op,id,title,priority};health{ok,items[]{section,status,message}};metrics{agents} 快照命令:health.ok=false 仍 exit 0(非门禁,与 #11 flow health 的 exit 1 语义无关);releases.gates 只含未归档版本(已归档版本只出现在 archived[]);health.items = flow health --json 同源合并项、仅键名不同(section/message ↔ name/detail);metrics 不含 processHealth;空数据合法(7 空组 / items:[] / gates:[] / archived:[] / blockingReviews:[]);--json 与 --out / --open 互斥(INVALID_ARGUMENT/refusal/1,零写盘);未初始化 NO_INIT/refusal/1;写盘失败仅 HTML 路径 INTERNAL_ERROR/internal/3

登记类别:恒在键 / 条件出现键 / 文档形态变体三类,测试断言须与类别一致。

§6 本版新增 / 有意变更登记(全枚举)

  1. instructions --json 补 schemaVersion 首键(C1;既有 9 键相对顺序不变)。
  2. flow archive show --json 首键重定位为 schemaVersion(G-1;既有键相对顺序不变)。
  3. flow health.reconciled 恒在:--fix 时为对账清单,否则 null。
  4. flow ops list[].warning 恒在:fill==='empty' 且 state!=='done'(v1.5.16 / REQ-024:done op 已无可执行动作,不再提示)时为提示文案,否则 null。
  5. legacy 失败载荷末尾追加顶层 errorKind(refusal | internal;error 恒 string、键序不变)。
  6. --version --json 新出口(op-003;三键文档,见 op-003 契约段)。
  7. 全局 --project 根选项(op-003;单点注入 chdir)。
  8. 退出码 3(internal;纯新增)。
  9. flow advance --json 错误模式开关(op-002;成功输出保持人类文本,非成功出口)。
  10. flow next --json 新出口(出口 #19;12 键固定序,见 §12.1;REQ P0-1 / P2-2 一致性)。
  11. flow status --json.stages[] 追加 5 字段(P1-1;既有 5 字段键序/类型不变;见 §12.2)。
  12. flow phases --json 末位追加 displayReviewTier / effectiveReviewTier(P2-2;既有 7 键不变;见 §12.3)。
  13. stage-97:14 个读命令 --json 新出口(#20~#33)——stage status(单阶段/无参)、flow recover、flow checkpoint list、flow log、project overview、knowledge search|list|index|dedup、config get|effective、view list、plan scheme list,以及 archive <stage>(13 命令面 + archive <stage>;详见 §13.1)。
  14. stage-97:req list --json.requirements[] 末位追加 linkedStages / progress——既有 RequirementData 键序不变,仅末位追加;linkedStages[]{id,phase}、progress{done,total}(见 §13.3)。
  15. stage-97:flow archive --json(gate-rejected 与成功)追加 eligible / unfinishedStages / blockingReviews——legacy 键序与 error 类型不变;成功形态 9 键、gate-rejected 形态 9 键(见 §4.2 / §13.3)。
  16. v1.2.4-stage-100:A1~A5 有意增量(#34~#40 + 2 项既有出口扩展)——A1 archive <stage> 增 ARCHIVE_EXISTS 拒绝(错误码第 13 行)与 --force(出口 #33 键集不变);A2~A4 新增 #34~#40 七个出口;A5 config get --all 扩展 #27(项目模式新增 defaults 形态)。既有出口字段键集/键序/类型零改动;详见 §15。
  17. v1.5.6-stage-115:新增出口 #41 lint req——target:'req' 比其他 lint 出口多出 suspects 与两个计数键(共 3 个新键:suspects / unknownCount / suspectCount),理由:A 类阻塞 / B 类 advisory 必须可分,塞进单一 issues 会破坏 ok 不变量。ok = issues.length === 0 与 #38/#39 完全一致;既有 40 个出口字段键集/键序/类型零改动;详见 §16。
  18. v1.5.8 / REQ-030:新增出口 #42 req release-check + 归档追加需求段——req release-check --json 只读软门(恒 exit 0);flow archive 成功/预演末位追加 requirements(既有 9 键键序零改动);flow archive list 的 counts 在 log 后追加可选 requirements;flow archive show 在 log 后追加可选 requirements;归档文件 schema 增可选 requirements[](老文件无此键可读,不注入);req list --include-archived 的归档需求元素末位追加可选 archived:true;req show 回退路径末位追加 archived:true;flow archive 新增 legacy 拒绝形态 unfinished-requirements(见 §4.2)。
  19. v1.5.10-stage-125:新增出口 #43 dashboard——dashboard --json 为快照出口(非门禁),10 键固定序 schemaVersion,generatedAt,generator,project,requirements,stages,releases,blockingReviews,health,metrics;generatedAt 是成功出口中首个非确定字段(测试不断言值);health.items[] 复用 HealthCheckItem 原生 {section,status,message}(与 flow health --json 的 {name,status,detail} 仅键名不同,该别名映射不可导出);releases.gates 只含未归档版本;releases.archived[].counts 逐字透传 ArchiveCounts(stages,reviews,log + v1.5.8 起可选 requirements),归档文件缺失 / 损坏 / 不可读时降级为 null(不注入零值、不报错);既有 42 个出口字段键集/键序/类型零改动;详见 §5 #43。

§7 计数口径

§8 迁移边界

§9 扩展优先原则 C1~C6 同步清单

项 决议 代码/测试状态 其余载体
C1 instructions --json 补首键 schemaVersion 已同步:op-001 命令层 withSchemaVersion;核心 loader 零改动(git status 空);test/commands/instructions.test.ts(首键+9 键相对序)与 test/cli/json-contract.test.ts #17 通过 已同步(stage-98):README×3 / GETTING_STARTED / docs/commands.md / manual / cli-usage skill;DSH 消费记录与 CHANGELOG 于阶段最终 op(op-003)落地
C1b flow archive show --json 首键重定位(G-1) 已同步:op-001 命令层 withSchemaVersion(file)(flow.ts:1993);既有 6 键相对序不变;json-contract.test.ts #10 通过 已同步(stage-98):docs/commands.md / manual / cli-usage skill;CHANGELOG 于阶段最终 op(op-003)落地
C2 knowledge dedup --project:保留本地声明 + 单点解析(本地 --project 声明零修改;根全局 --project 并行提供;动作经 optsWithGlobals() 读取,路径解析单点) 已同步:op-003 实现(knowledge.ts:182 本地声明保留;:176-189 optsWithGlobals + resolveProjectPathForCommand 单点);project-option.test.ts #13 与 knowledge.test.ts 回归通过;实测无 help 重复/解析歧义 已同步(stage-98):docs/commands.md / README×3 / manual / cli-usage skill
C3 条件键 null 占位(flow health.reconciled / flow ops list[].warning) 已同步:op-001 实现为恒在键;json-contract.test.ts #7(warning 恒在;v1.5.16 起仅 empty && state∉{done,failed} 为 string,其余 null;夹具含 done+empty 正控)/ #11(reconciled 恒在 null)通过;req next.candidates 为条件出现键(#16);flow overview 未初始化形态变体 #2b 已同步(stage-98):GETTING_STARTED / docs/commands.md / cli-usage skill;CHANGELOG 于阶段最终 op(op-003)落地
C4 非 JSON 模式内部错误仅新增退出码 3;0/1/2 零改动 已同步:op-002 实现;error-envelope.test.ts ①/⑥/⑦、实跑矩阵(10 行 × zh/en,archive-write-failed→3、锁超时→INTERNAL_ERROR/3);非 JSON 退出码对照通过 已同步(stage-98):README×3 / GETTING_STARTED / docs/commands.md / manual / cli-usage skill;DSH 分类断言与 CHANGELOG 于阶段最终 op(op-003)落地
C5 legacy errorKind 仅末尾追加,error 类型与键序零改动 已同步:op-002 实现(flow archive* / req *);error-envelope.test.ts ① 与契约测试 legacy 段通过;实跑 08-archive-gate / 09-archive-write / 10-req-missing(zh/en)error 恒 string、errorKind 为末键 已同步(stage-98):README×3 / GETTING_STARTED / docs/commands.md / manual / cli-usage skill;DSH 与 CHANGELOG 于阶段最终 op(op-003)落地
C6 全局 --project 纯新增根选项;不传时行为逐字不变 已同步:op-003 实现(根选项 + 预扫描 + help 双表);project-option.test.ts 13 项通过;实跑前置/后置/等号/无效路径/缺失值/多值冲突、目标项目语言、--log-file 原始 cwd、误判对均通过 已同步(stage-98):README×3 / docs/commands.md / manual / cli-usage skill

本阶段直接落盘本契约与代码/测试面;其余文档载体由 stage-98 在同一版本内收口,既有消费者不得静默失效。

REV-95-005 检索备注:.openfeel/plan/** 中「收敛为全局选项」旧口径已清零;.openfeel/roadmap/v1.2.2.md:31 仍存一处旧口径(本 op 只读范围外),已登记由 stage-98 文档载体收口同步。

§10 REQ-001 L80 勘误留痕

§11 项目锚定边界(--project,预登记)

  1. 单点注入:--project 经预扫描后单点 process.chdir 注入;不传时回退 process.cwd()(行为逐字不变)。
  2. 语言解析:chdir 后命令输出语言按目标项目解析;根选项描述 / --help 语言在 bin 阶段先于 chdir 求值,按原始 cwd(详见 op-003 实测登记)。
  3. --log-file 相对路径:在 bin 的 installRuntimeLog 先于 chdir 解析,按原始 cwd。
  4. 预扫描误判面:已知取值选项跳过其下一 token(防 --title --json / --encoding --project);裸 --xxx 取值不保证(如 --title --json 中 --json 为取值 token 时不被识别为开关)。
  5. 前提:CLI 为一次性进程、单进程单命令;不存在单进程内多项目并发切换的场景承诺。

§12 调度属性与 flow next 冻结语义(v1.2.2-stage-96)

§12.1 flow next --json(出口 #19,stage-96)

§12.2 flow status --json.stages[](阶段调度属性)

§12.3 flow phases --json(档位消歧)

§12.4 三处档位一致性

flow next(§12.1)、flow status --json.stages[](§12.2)、flow phases --json(§12.3)的同名档位语义一致:reviewTier = 展示档位(由 workflowMode 派生),effectiveReviewTier = 生效档位(恒 'full');flow phases 另以 displayReviewTier 给出展示档位的显式名。

§13 读命令 JSON 冻结细则(v1.2.2-stage-97)

§13.1 出口清单与计数

本阶段新增 14 个成功出口(#20~#33),均为只读命令面(archive <stage> 除外,它写归档摘要与 flow 日志)。冻结键序见 §5;可执行断言见 test/cli/json-contract.test.ts #20~#33。

# 出口 命令面
20 stage status stage status [<stageId>] --json(单阶段/无参两形态)
21 flow recover flow recover --json(已初始化/未初始化两形态)
22 flow checkpoint list flow checkpoint list [stage] --json
23 knowledge search knowledge search <query> [--limit] [--offset] --json
24 knowledge list knowledge list [--type] --json
25 knowledge index knowledge index --json
26 knowledge dedup knowledge dedup [content] [--threshold] [--category] --json
27 config get config get [key] [--global] --json
28 config effective config effective [key] --json
29 view list view list [--op] --json
30 plan scheme list plan scheme list [stage] --json
31 flow log flow log [--last <n>] --json
32 project overview project overview --json
33 archive <stage> archive <stage> --json

§13.2 空态与 no-init 语义(Q6 定稿)

命令 空态 / no-init 形态 退出码 人类模式镜像关系
stage status(无参) stages:[] + count:0 0 人类打印「无阶段」(exit 0)
stage status <id> 未找到 → envelope STAGE_NOT_FOUND/refusal 1 人类 stderr 两行 + exit 1
flow recover initialized:false + phase/currentOp/stageStatus/blockedBy:null + pendingTasks:[] + stageStats:{} 0 人类打印未初始化提示(exit 0)
flow checkpoint list 未初始化与空集合同形 stage:null,checkpoints:[],count:0 0 人类「无快照」(exit 0)
flow log 未初始化与空日志同形 count:0,entries:[] 0 人类「无日志 / 未初始化」(exit 0)
knowledge search results:[](不区分 offset 越界) 0 人类「未找到」+ 偏移提示(exit 0)
knowledge list entries:[] + count:0 0 人类「空」(exit 0)
knowledge index index.md 缺失 → 4 分类缺省 + recentUpdates:[] 0 人类分类概览 + 无更新(exit 0)
knowledge dedup 无匹配 → found:false + matches:[];无内容 → envelope INVALID_ARGUMENT 0 / 1 人类「无相似条目」/ 错误(exit 0 / 1)
config get(项目) 无 key → envelope INVALID_ARGUMENT 1 人类错误(exit 1)
config get --global(无 key) values 7 键齐全;undefined → JSON null(DEFAULT_PROFILE 回填后前 6 键通常有值,feel_mode 未显式设置时为 null;人类模式同值/空串) 0 人类逐行(undefined 显示空串)
config effective effective 恒为受管键映射(含缺省解析值) 0 人类逐行(exit 0)
view list count:0,reviews:[] 0 人类「空」(exit 0)
plan scheme list schemes:[] + count:0(非法 stage 名同为空) 0 人类「空」(exit 0)
project overview 恒输出 5 段结构;目录不存在时子项 null(无 initialized 键) 0 人类逐段(exit 0)
archive <stage> 阶段不存在 / 未初始化 → envelope ARCHIVE_FAILED 1 人类 stderr 单行 + exit 1

§13.3 字段形态约定

§13.4 JSON 内部异常口径

§13.5 plan scheme list.draft 的 opId 全局匹配(既有口径与风险登记)

§13.6 双轨判定例外条款

§14 承接 REV 边界登记(v1.2.2-stage-97)

§14.1 REV-95-008:文件锁等待超时归类

§14.2 REV-95-009:并发冲突退出机制已统一(v1.2.3-stage-99)

§14.3 REV-96-008:本阶段零动作

§15 v1.2.4-stage-100 细则(DSH ACTION-GUIDE A1~A5)

§15.1 A1:archive <stage> [--json] [--force] 覆盖保护

§15.2 A2:plan stage list --json

§15.3 A3:model list|get --json

§15.4 A4:三命令面

§15.5 A5:config get --all --json

§16 v1.5.6-stage-115 细则(lint req,出口 #41)

首段(契约差异声明):target:'req' 比其他 lint 出口多出 suspects 与两个计数键(共 3 个新键:suspects / unknownCount / suspectCount),理由:A/B 分级——A 类阻塞驱动 ok 与退出码,B 类 advisory 仅提示;两级语义无法塞进单一 issues 数组而不破坏 ok 不变量。本出口无历史消费者,新增键不受「只增不改」约束,但必须在此显式登记。

§16.1 顶层键序(恒 7 键)

schemaVersion,target,ok,issues,suspects,unknownCount,suspectCount(schemaVersion 恒首;target 恒 "req")。 issues[] / suspects[] 元素键序恒 path,message(复用 LintIssue 形状);空集恒 [](非 null);两个计数恒 number。

§16.2 A / B 判定与 ok

§16.3 候选识别与前缀 token 串

§16.4 抑制两档 + 使用约束

§16.5 不新增 JSON 键的部分(REV-011)

§16.6 排序 / 退出码 / path / 文案