openfeel 1.1.1 → 1.1.3

package/README.en.md

@@ -4,9 +4,11 @@
 
 OpenFeel is a TypeScript CLI tool for end-to-end process governance in AI Agent development. Core philosophy: **"Slim prompts, process in tools"** — agents understand workflows by reading `flow.json` state, not long text documents.
 
-> **Supported Platform**: Currently only [opencode](https://opencode.ai).  
+> **Current adapter harness**: opencode (default); the framework targets multi-harness support (other adapters reserved).  
 > **Default Model Config**: DeepSeek V4 (primary reasoning) + GLM-5.3-flash (cross-review) + DeepSeek-flash (multimodal vision).  
 > `openfeel init` auto-detects registered models and guides configuration.
+>
+> ⚠️ The `openfeel <cmd>` examples below are the **installed-package usage**; when developing/running **inside this source repository**, use `node bin/openfeel.js <cmd>` instead (the global `openfeel` may lag behind this repository — it is not synced with the source here).
 
 ## What Problem Does It Solve
 
@@ -46,20 +48,37 @@ openfeel plan scheme create stage-01 "Implement core features"
 openfeel flow status
 ```
 
+## What's New in v1.1.2
+
+- **Self-description**: `flow phases [--json]` lists all valid phases and the transition table (5 top-level JSON keys: `schemaVersion` / `phases` / `transitions` / `advanceAccepted` / `transitionsDiff`).
+- **Stage governance**: `flow stage remove` / `plan stage add --deps` / `stageId` validation and directory-conflict detection.
+- **Effective config**: `config effective` prints the resolved value plus its source (`status.md > config.yaml > profile.yaml > builtin`).
+- **Structured output**: `flow status/current/health/metrics/overview --json` (pure JSON + `schemaVersion`).
+- **Correction/cleanup CLI surface**: `plan scheme remove/rename/publish`, `flow ops list`, `flow health --fix`, `knowledge dedup`, `lint` non-zero exit on findings.
+- **Deployment & backup**: automatic backup before overwrite at `~/.openfeel/backup/{ts}/`; new skill `openfeel-cli-usage` (skills 16 → 17).
+- **Output encoding adaptation (stage-58 / stage-61 fix)**: `auto` passes through **UTF-8** on Windows non-TTY (pipe-friendly); TTY / POSIX pass through UTF-8; **GBK requires explicit** `--encoding gbk` / `OPENFEEL_ENCODING`; `--json` is **always UTF-8**; unencodable chars degrade to `?` without warning.
+- **Runtime log (stage-58)**: written by default to `~/.openfeel/cli/logs/openfeel-YYYY-MM-DD.log` (UTF-8, one file per day); `--log-file <path>` changes the path, `--no-log` / `OPENFEEL_LOG=0` disables it, `--debug` enables debug-level entries.
+
 ## Command Reference
 
 | Command | Purpose |
 |---------|---------|
-| `openfeel init [path]` | Initialize new project with `.openfeel/` workspace and platform adapter (opencode) |
+| `openfeel init [path]` | Initialize new project with `.openfeel/` workspace and platform adapter (current: opencode) |
 | `openfeel update` | Incrementally deploy platform adapter to existing projects |
-| `openfeel flow` | Pipeline state management (status / current / advance / overview) |
+| `openfeel flow` | Pipeline state management (status / phases / overview / current / advance / attempt / ops list / health [--fix] / checkpoint / migrate; status·current·health·metrics·overview support --json) |
 | `openfeel roadmap` | Version roadmap management (create / show) |
-| `openfeel plan` | Stage and scheme management (stage add/list, scheme create/list) |
-| `openfeel lint` | Quality gate checks (i18n key symmetry / kb stale references) |
-| `openfeel config` | Configuration management (get / set / list, supports --global) |
-| `openfeel knowledge` | Knowledge base management (list / search) |
+| `openfeel plan` | Stage and scheme management (stage add/list [--deps/--tasks], scheme create [--draft] / publish / rename / remove / list) |
+| `openfeel lint` | Quality gate checks (i18n key symmetry / kb stale references; **non-zero exit on findings**, no escape hatch) |
+| `openfeel config` | Configuration management (get / set[**all `defaults.*`**] / effective / get-lang / list-projects, supports --global) |
+| `openfeel knowledge` | Knowledge base management (list / add / search / index / dedup) |
 | `openfeel archive <stage>` | Stage archiving with knowledge extraction |
-| `openfeel update` | Update Agent definitions and Skill files |
+| `openfeel setup` | Global-only deployment (global AGENTS.md + agents + skills + adapter config); no project `.openfeel/` |
+| `openfeel migrate` | Migrate legacy-layout projects (detect / backup / rollback) |
+| `openfeel model` | Three-tier agent model config (set / get / list, `--scope`) |
+| `openfeel stage` | Work stage status (status / set / task / create [deprecated]) |
+| `openfeel project` | Project management (overview) |
+| `openfeel view` | Review item management (list / accept; add/update/remove via `flow review add|update|remove`) |
+| `openfeel instructions` | Generate structured instructions (artifact → XML/JSON) |
 
 Details: [docs/commands.md](docs/commands.md)
 
@@ -83,6 +102,12 @@ Feel is the command center, receiving user intent and dispatching downstream Age
 | Vision | Vision Agent | Multimodal visual analysis |
 | Archiver | Archiver | Operation archiving and knowledge extraction |
 
+### Global Deployment and Workspace Layering
+
+Framework assets (9 agents / 17 skills / global `AGENTS.md` / global `opencode.jsonc`) are deployed to `~/.config/opencode/` via `openfeel setup`; **the repository itself keeps no project-level `.opencode/agents|skills`** (since stage-55).
+
+Workspace state is layered into two files: `current.md` (team file, cross-user overall progress, ≤5 entries + auto-archiving) and `dev_last.md` (local index + topic directory, cross-session recovery). Framework assets are **automatically backed up** before deployment overwrite to `~/.openfeel/backup/{ts}/`.
+
 ### Three-Tier Planning
 
 ```
@@ -103,7 +128,7 @@ Roadmap
 | `openfeel plan` | Plan formulation |
 | `openfeel plan scheme` | Scheme formulation |
 | `openfeel-executor` | Code execution |
-| `openfeel view` | Code review |
+| `openfeel view` | Review item acceptance |
 | `openfeel-feel-tester` | Test acceptance |
 | `openfeel archive` | Stage archiving |
 | `openfeel knowledge` | Knowledge base operations |
@@ -112,7 +137,8 @@ Roadmap
 
 ```
 CLI Layer (Commander)
-  ├── init / update
+  ├── init / update / setup / migrate
+  ├── stage / project / model
   ├── flow         ← FlowManager (state machine core)
   ├── roadmap      ← Roadmap module
   ├── plan         ← Stage / Scheme module
@@ -130,15 +156,19 @@ Core Layer
   ├── artifact-graph/ — Dependency graph & instruction generation
   ├── view/ — Review item CRUD
   ├── archive/ — Archive consolidation
+  ├── backup.ts — pre-overwrite backup (~/.openfeel/backup/{ts}/)
+  ├── fs/ — atomic writes + advisory file locks
   └── workspace/ — Directory structure & knowledge base
 ```
 
+> **Global asset deployment**: 9 agents / 17 skills / global `AGENTS.md` / global `opencode.jsonc` are deployed to `~/.config/opencode/` via `openfeel setup`; the repository itself keeps no project-level `.opencode/agents|skills` (since stage-55).
+
 ## Development
 
 ```bash
 npm install        # Install dependencies
 npm run build      # Compile TypeScript
-npm test           # Run tests (395 cases)
+npm test           # Run tests (1018 cases / 61 test files; Linux CI skips 1 Windows-only case)
 ```
 
 ## Acknowledgments

package/README.md

@@ -1,11 +1,15 @@
 # OpenFeel — AI Agent 开发流程治理 CLI
 
-[English](README.en.md) | [更新日志](CHANGELOG.md) | [npm](https://www.npmjs.com/package/openfeel)
+[English](README.en.md) | [更新日志](CHANGELOG.md) | [npm](https://www.npmjs.com/package/openfeel) | [入门指南](docs/GETTING_STARTED.md)
 
-> ⚡ **支持平台**：opencode ｜ **默认模型**：DeepSeek（主力推理）+ GLM（交叉审查）+ Alibaba-CN（多模态）
+> ⚡ **当前适配 harness**：opencode（框架面向多 harness 适配，其余适配器预留） ｜ **默认模型**：DeepSeek V4（主力推理）+ GLM-5.3-flash（交叉审查）+ DeepSeek-flash（多模态视觉）
+
+> ⚠️ 下文示例命令 `openfeel <cmd>` 为**安装后的一般使用者用法**；若在**本仓库源码**中开发/执行，请改用 `node bin/openfeel.js <cmd>`（全局 `openfeel` 可能滞后于本仓——未随本仓库源码同步更新）。
 
 OpenFeel 是一个 TypeScript CLI 工具，为 AI Agent 开发提供端到端的流程治理。核心理念：**「提示词瘦身，流程入工具」** —— Agent 不靠读长文本理解流程，而是通过 `flow.json` 获取当前状态和下一步指令。
 
+> 📦 **最新版本 v1.1.2** — 自描述 `flow phases`、配置有效值 `config effective`、部署前自动备份；框架资产（agents/skills/AGENTS.md）全局部署。
+
 > 📌 本项目基于 [AI_Prompt](https://github.com/Liuary/AI_Prompt) 开发，参考了 [OpenSpec](https://github.com/Fission-AI/OpenSpec) 等工具的设计思路。
 
 ---
@@ -18,10 +22,11 @@ openfeel init ./my-project     # 初始化新项目
 openfeel update                # 已有项目？一键部署平台适配器
 openfeel migrate               # 存量旧布局项目？一键迁移（检测/备份/回滚）
 openfeel flow status           # 查看流水线
+openfeel flow phases           # 查看合法 phase 与转移表
 
 npm install -g openfeel@latest # 更新到最新版本
 ```
 
-> 💡 `init` 用于新项目首次部署，`update` 为已有项目增量更新（适用于 `init` 之后再引入 OpenFeel 的项目）。存量旧布局项目（项目内 `.opencode/agents|skills|instructions`）用 `openfeel migrate` 迁移到全局部署。
+> 💡 `init` 用于新项目首次部署，`update` 为已有项目增量更新（适用于 `init` 之后再引入 OpenFeel 的项目）。存量旧布局项目（opencode 适配器：项目内 `.opencode/agents|skills|instructions`）用 `openfeel migrate` 迁移到全局部署。框架资产（agents/skills/AGENTS.md）经 `openfeel setup` 全局部署，项目内不再生成 `.opencode/agents|skills`。
 
 完整中文文档：[README.zh-CN.md](README.zh-CN.md)

package/README.zh-CN.md

@@ -2,9 +2,11 @@
 
 [English](README.en.md) | [更新日志](CHANGELOG.md) | [npm](https://www.npmjs.com/package/openfeel) | [入门指南](docs/GETTING_STARTED.md)
 
+> ⚠️ 下文示例命令 `openfeel <cmd>` 为**安装后的一般使用者用法**；若在**本仓库源码**中开发/执行，请改用 `node bin/openfeel.js <cmd>`（全局 `openfeel` 可能滞后于本仓——未随本仓库源码同步更新）。
+
 OpenFeel 是一个 TypeScript CLI 工具，为 AI Agent 开发提供端到端的流程治理。
 
-> **支持平台**：目前仅支持 [opencode](https://opencode.ai)。  
+> **当前适配 harness**：opencode（默认）；框架面向多 harness 适配（其余适配器预留）。  
 > **默认模型配置**：DeepSeek V4（主力推理） + GLM-5.3-flash（交叉审查） + DeepSeek-flash（多模态视觉）。  
 > 首次 `openfeel init` 时会自动检测用户已注册的模型并引导配置。
 
@@ -46,20 +48,37 @@ openfeel plan scheme create stage-01 "实现核心功能"
 openfeel flow status
 ```
 
+## v1.1.2 新增能力
+
+- **自描述**：`flow phases [--json]` 输出全部合法 phase 与转移表（JSON 顶层 5 键：`schemaVersion` / `phases` / `transitions` / `advanceAccepted` / `transitionsDiff`）。
+- **阶段治理**：`flow stage remove` / `plan stage add --deps` / `stageId` 校验与目录冲突检测。
+- **配置有效值**：`config effective` 输出有效值 + 生效来源（`status.md > config.yaml > profile.yaml > builtin`）。
+- **结构化输出**：`flow status/current/health/metrics/overview --json`（纯 JSON + `schemaVersion`）。
+- **纠正/清理侧命令面**：`plan scheme remove/rename/publish`、`flow ops list`、`flow health --fix`、`knowledge dedup`、`lint` 发现问题非 0 退出。
+- **部署与备份**：部署覆盖前自动备份 `~/.openfeel/backup/{ts}/`；新增 skill `openfeel-cli-usage`（skill 16 → 17）。
+- **输出编码自适应（stage-58 / stage-61 修正）**：`auto` 在 Windows 非 TTY（管道/重定向）下**直通 UTF-8**（管道/CI 友好）；TTY / POSIX 直通 UTF-8；**GBK 需 `--encoding gbk` / `OPENFEEL_ENCODING` 显式**；`--json` **恒 UTF-8**；不可编码字符降 `?` 不告警。
+- **运行日志（stage-58）**：默认写入 `~/.openfeel/cli/logs/openfeel-YYYY-MM-DD.log`（UTF-8，按日一文件）；`--log-file <path>` 改路径，`--no-log` / `OPENFEEL_LOG=0` 关闭，`--debug` 记录 debug 级。
+
 ## 命令参考
 
 | 命令 | 用途 |
 |------|------|
-| `openfeel init [path]` | 初始化新项目，创建 `.openfeel/` 目录结构和平台适配器（opencode） |
+| `openfeel init [path]` | 初始化新项目，创建 `.openfeel/` 目录结构和平台适配器（当前：opencode） |
 | `openfeel update` | 为已有项目增量部署平台适配器（适用于 `init` 之后再引入 OpenFeel 的项目） |
-| `openfeel flow` | 流水线状态管理（status / current / advance / overview） |
+| `openfeel flow` | 流水线状态管理（status / phases / overview / current / advance / attempt / ops list / health [--fix] / checkpoint / migrate；status·current·health·metrics·overview 支持 --json） |
 | `openfeel roadmap` | 分期大纲管理（create / show） |
-| `openfeel plan` | 工作阶段与操作方案管理（stage add/list、scheme create/list） |
-| `openfeel lint` | 质量门禁检查（i18n 键对称性 / kb 过期引用） |
-| `openfeel config` | 配置管理（get / set / list，支持 --global） |
-| `openfeel knowledge` | 知识库管理（list / search） |
+| `openfeel plan` | 工作阶段与操作方案管理（stage add/list [--deps/--tasks]、scheme create [--draft] / publish / rename / remove / list） |
+| `openfeel lint` | 质量门禁检查（i18n 键对称性 / kb 过期引用；**发现问题非 0 退出**，无逃生阀） |
+| `openfeel config` | 配置管理（get / set[**全量 `defaults.*`**] / effective / get-lang / list-projects，支持 --global） |
+| `openfeel knowledge` | 知识库管理（list / add / search / index / dedup） |
 | `openfeel archive <stage>` | 阶段归档，汇总产出、生成摘要、提取知识 |
-| `openfeel update` | 更新 Agent 定义和 Skill 文件到目标平台 |
+| `openfeel setup` | 纯全局部署（全局 AGENTS.md + agent + skill + 平台适配器配置），不建项目 `.openfeel/` |
+| `openfeel migrate` | 存量旧布局项目迁移（检测 / 备份 / 回滚） |
+| `openfeel model` | 三层级 agent 模型配置（set / get / list，`--scope`） |
+| `openfeel stage` | 阶段状态（status / set / task / create［已弃用］） |
+| `openfeel project` | 项目管理（overview） |
+| `openfeel view` | 审查条目管理（list / accept；新增/修改/删除改用 `flow review add|update|remove`） |
+| `openfeel instructions` | 生成结构化指令（artifact → XML/JSON） |
 
 详细参数见：[docs/commands.md](docs/commands.md)
 
@@ -79,10 +98,16 @@ Feel 是整个流程的调度中心，负责接收用户意图并调度下游 Ag
 | Executor | 执行官 | 按方案编码实现 |
 | Reviewer | 审查官 | 交叉审查代码 |
 | Feel Tester | 测试官 | 正式测试验收 |
-| 事务官 | 事务官 | 文件机械操作 |
+| Utility | 事务官 | 文件机械操作 |
 | Vision | 视觉官 | 多模态视觉分析 |
 | Archiver | 归档官 | 归档操作记录与知识提取 |
 
+### 全局部署与工作区分层
+
+框架资产（9 agent / 17 skill / 全局 `AGENTS.md` / 全局 `opencode.jsonc`）经 `openfeel setup` 部署到 `~/.config/opencode/`；**仓库自身不保留项目级 `.opencode/agents|skills`**（stage-55 起）。
+
+工作区状态分两层：`current.md`（团队文件，跨用户整体进度，≤5 条 + 自动归档）与 `dev_last.md`（本地索引 + 主题目录，跨会话恢复）。框架资产部署覆盖前**自动备份**至 `~/.openfeel/backup/{ts}/`。
+
 ### 三层计划体系
 
 ```
@@ -103,7 +128,7 @@ Roadmap（分期大纲）
 | `openfeel plan` | 制定分期大纲和工作阶段 |
 | `openfeel plan scheme` | 制定细粒度操作方案 |
 | `openfeel-executor` | 按方案编码实现 |
-| `openfeel view` | 代码审查 |
+| `openfeel view` | 审查条目验收 |
 | `openfeel-feel-tester` | 测试验收 |
 | `openfeel archive` | 归档操作记录 |
 | `openfeel knowledge` | 知识库操作 |
@@ -112,7 +137,8 @@ Roadmap（分期大纲）
 
 ```
 CLI 层（Commander）
-  ├── init / update
+  ├── init / update / setup / migrate
+  ├── stage / project / model
   ├── flow         ← FlowManager（状态机核心）
   ├── roadmap      ← Roadmap 模块
   ├── plan         ← Stage / Scheme 模块
@@ -130,15 +156,19 @@ Core 层
   ├── artifact-graph/ — 依赖图与指令生成
   ├── view/ — 审查条目 CRUD
   ├── archive/ — 归档合并
+  ├── backup.ts — 覆盖写前备份（~/.openfeel/backup/{ts}/）
+  ├── fs/ — 原子写 + 建议性文件锁
   └── workspace/ — 目录结构和知识库
 ```
 
+> **框架资产全局部署**：9 agent / 17 skill / 全局 `AGENTS.md` / 全局 `opencode.jsonc` 经 `openfeel setup` 部署到 `~/.config/opencode/`；仓库自身不保留项目级 `.opencode/agents|skills`（stage-55 起）。
+
 ## 开发
 
 ```bash
 npm install        # 安装依赖
 npm run build      # 编译 TypeScript
-npm test           # 运行测试（395 用例）
+npm test           # 运行测试（1018 用例 / 61 个测试文件；Linux CI 跳过 1 个 Windows 专属用例）
 ```
 
 ## 致谢

package/bin/openfeel.js

@@ -2,8 +2,13 @@
 // OpenFeel CLI 入口 — 加载并启动 Commander 程序
 // 无参数时进入 REPL 交互模式，有参数时正常 CLI 模式
 import { program, applyHelpI18n, startRepl, runCli } from '../dist/cli/index.js';
+import { installOutputEncoding } from '../dist/cli/output-encoding.js';
+import { installRuntimeLog } from '../dist/core/runtime-log.js';
 
 const args = process.argv.slice(2);
+// 进程入口安装：输出编码 + 运行日志（单一咽喉；库/测试侧未调用即 no-op）
+installOutputEncoding();
+installRuntimeLog();
 // 在 parse 前注入翻译，此时命令树已就绪
 applyHelpI18n(program);
 if (args.length === 0) {

package/dist/cli/index.d.ts

@@ -5,12 +5,24 @@
  */
 import { Command } from 'commander';
 declare const program: Command;
+/**
+ * 是否启用彩色输出（B7-1，单一判定入口）。
+ * 优先级：`--no-color`（显式关闭，commander 解析为 color=false） > `NO_COLOR` 环境变量（存在且**非空**即关闭，
+ * 遵循 no-color.org，**不解析其值**） > 默认（允许彩色）。
+ *
+ * 注：当前实现**无着色逻辑**，故实际输出恒无 ANSI；本函数为**契约与未来保护**——
+ * 将来引入着色时必须经此判定（禁止绕过）。
+ * @param options commander 解析结果（`color === false` 表示显式 --no-color）
+ */
+export declare function shouldUseColor(options?: {
+    color?: boolean;
+}): boolean;
 export declare function applyHelpI18n(program: Command): void;
-/** 并发冲突退出码：与通用错误 1 区分，便于自动化识别「可重试」冲突 */
+/** 并发写冲突退出码：与通用错误 1 区分，便于自动化识别「可重试」冲突 */
 export declare const EXIT_CONCURRENT = 2;
-/** 统一 CLI 错误处理：识别 flow.json 并发冲突并输出可重试提示 */
+/** 统一 CLI 错误处理：识别 flow.json 并发写冲突并输出可重试提示（单点，T38） */
 export declare function handleCliError(err: unknown): never;
-/** CLI 启动入口：包裹 program.parse，统一处理并发冲突 */
+/** CLI 启动入口：包裹 program.parse，统一处理并发写冲突 */
 export declare function runCli(): void;
 export { program };
 export { startRepl } from './repl.js';

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AA8C9B,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAsEpD;AAED,wCAAwC;AACxC,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,4CAA4C;AAC5C,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CAQlD;AAED,yCAAyC;AACzC,wBAAgB,MAAM,IAAI,IAAI,CAM7B;AAED,OAAO,EAAE,OAAO,EAAE,CAAC;AACnB,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAe9B;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAYrE;AAyCD,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+EpD;AAED,yCAAyC;AACzC,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CAQlD;AAED,0CAA0C;AAC1C,wBAAgB,MAAM,IAAI,IAAI,CAU7B;AAED,OAAO,EAAE,OAAO,EAAE,CAAC;AACnB,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/cli/index.js

@@ -5,8 +5,10 @@
  */
 import { Command } from 'commander';
 import { createRequire } from 'node:module';
-import { t, getCliLang } from '../core/i18n.js';
+import { t, getCliLang, hasKey } from '../core/i18n.js';
 import { isFlowConcurrentError } from '../core/flow-manager.js';
+import { handleConcurrentConflict } from '../commands/shared/errors.js';
+import { runtimeLog } from '../core/runtime-log.js';
 // 读取 package.json 获取版本号
 const require = createRequire(import.meta.url);
 const pkg = require('../../package.json');
@@ -15,7 +17,37 @@ const program = new Command();
 program
     .name('openfeel')
     .description('AI Agent 开发流程治理 CLI 工具')
-    .version(pkg.version, '-v, --version', '输出版本号');
+    .version(pkg.version, '-v, --version', '输出版本号')
+    // B7-2：全局 --no-color（negate 选项；描述在注册时按当前语言求值，applyHelpI18n 会跳过 negate）
+    .option('--no-color', t('help.global.noColor', getCliLang(process.cwd())))
+    // stage-58 A-5：全局 --encoding（默认 auto；仅用于 --help 展示 + 防 commander 未知选项报错；实际解析从 argv/env 读取）
+    .option('--encoding <encoding>', t('help.global.encoding', getCliLang(process.cwd())), 'auto')
+    // stage-58 B-4：运行日志全局选项
+    .option('--log-file <path>', t('help.global.logFile', getCliLang(process.cwd())))
+    .option('--no-log', t('help.global.noLog', getCliLang(process.cwd())))
+    .option('--debug', t('help.global.debug', getCliLang(process.cwd())));
+/**
+ * 是否启用彩色输出（B7-1，单一判定入口）。
+ * 优先级：`--no-color`（显式关闭，commander 解析为 color=false） > `NO_COLOR` 环境变量（存在且**非空**即关闭，
+ * 遵循 no-color.org，**不解析其值**） > 默认（允许彩色）。
+ *
+ * 注：当前实现**无着色逻辑**，故实际输出恒无 ANSI；本函数为**契约与未来保护**——
+ * 将来引入着色时必须经此判定（禁止绕过）。
+ * @param options commander 解析结果（`color === false` 表示显式 --no-color）
+ */
+export function shouldUseColor(options) {
+    // 显式 --no-color → 关闭
+    if (options?.color === false) {
+        return false;
+    }
+    // NO_COLOR 存在且非空 → 关闭（空串按未设置处理）
+    const noColor = process.env.NO_COLOR;
+    if (typeof noColor === 'string' && noColor.length > 0) {
+        return false;
+    }
+    // 默认允许彩色（当前无着色实现 → 零可见变化）
+    return true;
+}
 // ── 静态导入命令模块（新增命令在此追加） ──
 import { registerInitCommand } from '../commands/init.js';
 import { registerFlowCommand } from '../commands/flow.js';
@@ -76,6 +108,14 @@ export function applyHelpI18n(program) {
                 cmd.description(descTranslated);
             }
         }
+        // 替换当前命令的 arguments 描述（键约定 help.<commandPath>.arg<name>，T38）
+        // 仅命中既有键时替换，避免对未补键的 argument 触发缺失告警
+        for (const arg of cmd.registeredArguments ?? []) {
+            const argKey = `${keyPrefix}.arg${arg.name()}`;
+            if (hasKey(argKey, lang)) {
+                arg.description = t(argKey, lang);
+            }
+        }
         // 替换当前命令的 option 描述
         for (const opt of cmd.options) {
             // 跳过 Commander 自动生成的 --no- 选项（negate 标记为 true）
@@ -87,9 +127,9 @@ export function applyHelpI18n(program) {
                 continue;
             const optName = toCamelCase(flag);
             const optKey = `${keyPrefix}.${optName}`;
-            const optTranslated = t(optKey, lang);
-            if (optTranslated !== optKey) {
-                opt.description = optTranslated;
+            // 仅命中既有键时替换，避免对未补键的选项触发缺失告警（与 argument 同策略）
+            if (hasKey(optKey, lang)) {
+                opt.description = t(optKey, lang);
             }
         }
         // 递归处理子命令
@@ -111,9 +151,9 @@ export function applyHelpI18n(program) {
             continue;
         const optName = toCamelCase(flag);
         const optKey = `help.${program.name()}.${optName}`;
-        const optTranslated = t(optKey, lang);
-        if (optTranslated !== optKey) {
-            opt.description = optTranslated;
+        // 仅命中既有键时替换，避免对未补键的选项（如 help.openfeel.encoding）触发每命令缺失告警
+        if (hasKey(optKey, lang)) {
+            opt.description = t(optKey, lang);
         }
     }
     // 子命令路径从命令名开始（不含 root），与 help 域 key 命名对齐
@@ -121,26 +161,30 @@ export function applyHelpI18n(program) {
         walkCmd(sub, [sub.name()]);
     }
 }
-/** 并发冲突退出码：与通用错误 1 区分，便于自动化识别「可重试」冲突 */
+/** 并发写冲突退出码：与通用错误 1 区分，便于自动化识别「可重试」冲突 */
 export const EXIT_CONCURRENT = 2;
-/** 统一 CLI 错误处理：识别 flow.json 并发冲突并输出可重试提示 */
+/** 统一 CLI 错误处理：识别 flow.json 并发写冲突并输出可重试提示（单点，T38） */
 export function handleCliError(err) {
+    // stage-58 B-6：记录「命令处理中抛出的异常」。error 级语义边界（REV-002）：
+    // commander 解析期错误（未知命令/未知选项/缺参）经 program.error() 直接 process.exit(1)，不抛异常、不达此处 → 不入日志。
+    runtimeLog('error', 'cli error: ' + (err instanceof Error ? err.message : String(err)));
     if (isFlowConcurrentError(err)) {
-        console.error(`[并发冲突] flow.json 已被其它进程修改（期望 revision=${err.expectedRevision}，磁盘=${err.actualRevision}）。`);
-        console.error('本次修改未写入。请重新执行该命令（将基于最新 flow.json 重试）。');
-        console.error('若多 Agent 并发推进，请串行化 flow.json 写入后重试。');
-        process.exit(EXIT_CONCURRENT);
+        handleConcurrentConflict(err, getCliLang(process.cwd()));
     }
     throw err;
 }
-/** CLI 启动入口：包裹 program.parse，统一处理并发冲突 */
+/** CLI 启动入口：包裹 program.parse，统一处理并发写冲突 */
 export function runCli() {
+    // stage-58 B-6：命令（argv）+ 结果入运行日志；不记录 stdout 内容。
+    // 注：--help/--version 由 commander 输出后直接 exit → 不记「cli done」；错误路径经 handleCliError 抛出 → 亦不记「cli done」。
+    runtimeLog('info', 'cli start: ' + process.argv.slice(2).join(' '));
     try {
         program.parse();
     }
     catch (err) {
         handleCliError(err);
     }
+    runtimeLog('info', 'cli done exit=' + (process.exitCode ?? 0));
 }
 export { program };
 export { startRepl } from './repl.js';

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/cli/output-encoding.d.ts

@@ -0,0 +1,32 @@
+/** 目标编码（iconv-lite 支持的编码名） */
+export type OutputEncoding = 'utf8' | 'gbk' | 'gb18030' | 'big5' | 'cp932' | 'cp949';
+/** resolveTargetEncoding 的输入上下文（注入以便纯函数单测） */
+export interface ResolveTargetEncodingContext {
+    /** 命令行参数（不含 node 与脚本名），如 process.argv.slice(2) */
+    argv: string[];
+    /** 环境变量，如 process.env */
+    env: NodeJS.ProcessEnv;
+    /** 平台，如 process.platform */
+    platform: NodeJS.Platform;
+    /** 该输出流是否为 TTY */
+    isTTY: boolean;
+}
+/** 安装选项（仅注入输出流，便于单测；不含 force——无 env 守卫可绕） */
+export interface InstallOutputEncodingOptions {
+    stdout?: NodeJS.WriteStream;
+    stderr?: NodeJS.WriteStream;
+}
+/** 归一化编码值：命中别名返回目标编码；'auto'/空/未知返回 null */
+export declare function normalizeEncoding(value: string | undefined): OutputEncoding | null;
+/**
+ * 解析目标输出编码（纯函数）。
+ * 优先级：① --json→utf8（最高） ② 显式 --encoding ③ OPENFEEL_ENCODING ④ 非 win32/TTY→utf8
+ * ⑤ win32 非 TTY→utf8。
+ */
+export declare function resolveTargetEncoding(ctx: ResolveTargetEncodingContext): OutputEncoding;
+/**
+ * 安装输出编码包装（幂等）。仅由 bin/openfeel.js 调用。
+ * 未调用时库/测试侧零副作用（不包装任何流）。
+ */
+export declare function installOutputEncoding(opts?: InstallOutputEncodingOptions): void;
+//# sourceMappingURL=output-encoding.d.ts.map

package/dist/cli/output-encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-encoding.d.ts","sourceRoot":"","sources":["../../src/cli/output-encoding.ts"],"names":[],"mappings":"AAkBA,8BAA8B;AAC9B,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAErF,8CAA8C;AAC9C,MAAM,WAAW,4BAA4B;IAC3C,kDAAkD;IAClD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,kBAAkB;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,6CAA6C;AAC7C,MAAM,WAAW,4BAA4B;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;CAC7B;AAoBD,2CAA2C;AAC3C,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,IAAI,CAMlF;AAgBD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,4BAA4B,GAAG,cAAc,CAsBvF;AA6BD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,4BAAiC,GAAG,IAAI,CAOnF"}

package/dist/cli/output-encoding.js

@@ -0,0 +1,120 @@
+/**
+ * CLI 输出编码自适应模块（stage-58 op-001）
+ *
+ * 职责：在 CLI 进程入口（bin/openfeel.js）安装 stdout/stderr 写包装，把人类可读文本按目标编码转码。
+ * win32 非 TTY 默认直通 UTF-8（对齐 Node 默认与管道/CI 消费者）；GBK 仅经显式
+ * `--encoding gbk` / `OPENFEEL_ENCODING=gbk` 生效。
+ *
+ * 设计边界：
+ * - **库侧默认 no-op**：未调用 installOutputEncoding 时不包装任何流（测试 import 零副作用）。
+ * - **不设 VITEST/env 守卫**（REV-001 裁定方案 b）：安装仅由 bin 调用；in-process 测试从不安装；
+ *   若设守卫会被 spawn 子进程继承（vitest 主进程会设置 VITEST 环境变量为真）→ E2E 恒绿。
+ * - **--json 恒 UTF-8**：机器合同，resolve 第 1 步旁路，覆盖显式 --encoding / OPENFEEL_ENCODING / auto。
+ * - **仅支持 UTF-8 字符串语义**（REV-003）：string 分支丢弃调用方 encoding；非默认 encoding 的
+ *   直接 write（如 write(str, 'latin1', cb)）不受支持。当前全仓 process.stdout/stderr.write 直调为 0。
+ * - 不可编码字符由 iconv-lite 降级为 '?'，**不额外告警**。
+ */
+import iconv from 'iconv-lite';
+/** 已安装标志（幂等） */
+let installed = false;
+/** 编码别名 → iconv 编码名（'auto'/空/未知返回 null → 调用方继续回退） */
+const ENCODING_ALIASES = {
+    utf8: 'utf8',
+    'utf-8': 'utf8',
+    gbk: 'gbk',
+    gb2312: 'gbk',
+    gb18030: 'gb18030',
+    big5: 'big5',
+    shift_jis: 'cp932',
+    sjis: 'cp932',
+    cp932: 'cp932',
+    'euc-kr': 'cp949',
+    cp949: 'cp949',
+};
+/** 归一化编码值：命中别名返回目标编码；'auto'/空/未知返回 null */
+export function normalizeEncoding(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const v = value.trim().toLowerCase();
+    return ENCODING_ALIASES[v] ?? null;
+}
+/** 从 argv 读取显式 --encoding（支持 `--encoding gbk` 与 `--encoding=gbk`） */
+function readEncodingArg(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--encoding') {
+            return argv[i + 1];
+        }
+        if (arg.startsWith('--encoding=')) {
+            return arg.slice('--encoding='.length);
+        }
+    }
+    return undefined;
+}
+/**
+ * 解析目标输出编码（纯函数）。
+ * 优先级：① --json→utf8（最高） ② 显式 --encoding ③ OPENFEEL_ENCODING ④ 非 win32/TTY→utf8
+ * ⑤ win32 非 TTY→utf8。
+ */
+export function resolveTargetEncoding(ctx) {
+    const { argv, env, platform, isTTY } = ctx;
+    // ① --json 恒 UTF-8（机器合同，覆盖一切显式/env/auto）
+    if (argv.includes('--json')) {
+        return 'utf8';
+    }
+    // ② 显式 --encoding
+    const fromArg = normalizeEncoding(readEncodingArg(argv));
+    if (fromArg) {
+        return fromArg;
+    }
+    // ③ 环境变量
+    const fromEnv = normalizeEncoding(env.OPENFEEL_ENCODING);
+    if (fromEnv) {
+        return fromEnv;
+    }
+    // ④ 非 win32 或 TTY：现代终端由 Node 控制台 API 直通，无需转码
+    if (platform !== 'win32' || isTTY) {
+        return 'utf8';
+    }
+    // ⑤ win32 非 TTY：直接 UTF-8（对齐 Node 默认与管道/CI 消费者；GBK 仅显式 ②/③）
+    return 'utf8';
+}
+/** 包装单个输出流：仅字符串 chunk 转码，Buffer 直通，保留 callback/返回值 */
+function wrapStream(stream) {
+    const target = resolveTargetEncoding({
+        argv: process.argv.slice(2),
+        env: process.env,
+        platform: process.platform,
+        isTTY: Boolean(stream.isTTY),
+    });
+    // target=utf8 不包装（零行为变更）
+    if (target === 'utf8') {
+        return;
+    }
+    const orig = stream.write.bind(stream);
+    const wrapped = (chunk, encoding, cb) => {
+        if (typeof chunk === 'string') {
+            // 仅支持 UTF-8 字符串语义：丢弃调用方 encoding（REV-003）；不可编码字符降 '?'，不告警
+            const callback = typeof encoding === 'function' ? encoding : cb;
+            const buf = iconv.encode(chunk, target);
+            return orig(buf, callback);
+        }
+        // Buffer/二进制直通，保留原始签名
+        return orig(chunk, encoding, cb);
+    };
+    stream.write = wrapped;
+}
+/**
+ * 安装输出编码包装（幂等）。仅由 bin/openfeel.js 调用。
+ * 未调用时库/测试侧零副作用（不包装任何流）。
+ */
+export function installOutputEncoding(opts = {}) {
+    if (installed) {
+        return;
+    }
+    wrapStream(opts.stdout ?? process.stdout);
+    wrapStream(opts.stderr ?? process.stderr);
+    installed = true;
+}
+//# sourceMappingURL=output-encoding.js.map

package/dist/cli/output-encoding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-encoding.js","sourceRoot":"","sources":["../../src/cli/output-encoding.ts"],"names":[],"mappings":"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"}