openfeel 1.1.0 → 1.1.2

package/dist/core/update.js

@@ -1,34 +1,26 @@
 /**
  * OpenCode 适配器更新编排
- * 在目标项目中生成 Agent 定义、Skill 定义、instructions/core.md，并更新 opencode.jsonc 配置。
+ * 增量部署全局资产（全局 AGENTS.md、agent、skill）并更新全局/项目 opencode.jsonc 配置。
  *
- * 变更摘要 (v3-stage-04 第二轮):
- * - 新增 instructions/core.md 创建（从 init.ts 迁移至此，职责归位适配器层）
+ * 变更摘要:
+ * - v3-stage-04: 新增 instructions/core.md 创建（从 init.ts 迁移）
+ * - v1.1.1: 拆除项目 AGENTS.md 部署；全局约束由 core.md 改为全局 AGENTS.md（收归 openfeel setup）
  */
-import { existsSync, readFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync } from 'node:fs';
 import { resolve, dirname, join, basename, isAbsolute, relative } from 'node:path';
 import { loadAgentTemplate, listAgentIds, loadTemplate } from './template-loader.js';
-import { recordProjectLang, getGlobalConfig, getLang } from './workspace/identity.js';
-import { getCliLang } from './i18n.js';
-import { getOpencodeGlobalDir, getGlobalAgentsDir, getGlobalSkillsDir, getGlobalCoreMdPath, getGlobalOpencodeJsoncPath, getGlobalUpdateStatePath } from './global-paths.js';
+import { recordProjectLang } from './workspace/identity.js';
+import { t, getCliLang } from './i18n.js';
+import { getOpencodeGlobalDir, getGlobalAgentsDir, getGlobalSkillsDir, getGlobalCoreMdPath, getGlobalAgentsMdPath, getGlobalOpencodeJsoncPath, getGlobalUpdateStatePath } from './global-paths.js';
 import { mergeGlobalOpencodeJsonc, buildProjectOpencodeJsoncObj } from './opencode-config.js';
 import { atomicWriteFileSync } from './fs/atomic-write.js';
 import { withFileLock, globalLockPath } from './fs/file-lock.js';
 import { detectFileType, normalize, splitFrontmatter, parseRegion, wrapRegion, replaceRegion, mergeFrontmatter, serializeFrontmatter } from './managed-region.js';
 import { appendUpdateInfo } from './update-infos.js';
+import { backupFileBeforeWrite, BackupError, notifyBackupIfTTY } from './backup.js';
+import { readJsoncFile } from './fs/safe-read.js';
 // 新增：update_state.json hash 比对与冲突检测（项目 state + 全局 state）
 import { hashContent, loadUpdateState, saveUpdateState, createUpdateState, loadGlobalUpdateState, saveGlobalUpdateState, createGlobalUpdateState, updateFileHash, markFileConflict, getOpenfeelVersion, } from './update-state.js';
-/** AGENTS.md 语言冲突错误（由命令层捕获处理） */
-export class AgentsMdLangConflictError extends Error {
-    projectLang;
-    requestedLang;
-    constructor(projectLang, requestedLang) {
-        super(`AGENTS.md language conflict: project=${projectLang}, requested=${requestedLang}`);
-        this.projectLang = projectLang;
-        this.requestedLang = requestedLang;
-        this.name = 'AgentsMdLangConflictError';
-    }
-}
 /** 当前支持部署的 AI 工具列表 */
 export const supportedTools = [
     {
@@ -73,7 +65,7 @@ export async function selectTools() {
 export const SKILL_DEFINITIONS = {
     'openfeel-agent-model-check': `---
 name: openfeel-agent-model-check
-description: Agent 模型检查与修复。当 Agent 报 "Model not found" 或需要排查模型配置时使用。涵盖 auth.json 校验、provider key 匹配、模型能力确认、openfeel-vision 多模态专项指南。
+description: Agent 模型检查与修复。当 Agent 报 "Model not found" 或需要排查模型配置时使用。涵盖 auth.json 校验（opencode 适配器）、provider key 匹配、模型能力确认、openfeel-vision 多模态专项指南。
 ---
 
 # Skill: openfeel-agent-model-check
@@ -341,6 +333,130 @@ Skill 加载后，根据步骤 3 的匹配结果决定是否追加提示：
   此提示确保 Agent 不会跳过知识库查询直接编码。
 
 - **若步骤 3 无相关条目**：不追加强制提示，静默返回（已在步骤 4 输出"知识库中暂无相关记录，可继续执行"）。
+`,
+    'openfeel-cli-usage': `---
+name: openfeel-cli-usage
+description: OpenFeel CLI 命令用法参考：命令清单与关键参数、15 个 phase 枚举与转移表、stageId 命名与目录映射约定、v1.1.2 新增能力（自描述/可纠错、--json 结构化输出、health --fix、scheme draft、knowledge dedup、纠正清理侧命令面）。当需要查询 CLI 命令、参数、phase、stageId、阶段命名时加载。
+---
+
+# OpenFeel CLI 用法参考
+
+## 说明
+
+- 定位：**查询型参考手册**（只读，不自执行）。回答「命令是什么、参数怎么给、phase/stageId 规则如何」。
+- 边界：**执行型交互向导**请用 \`openfeel-wizard\` skill（跑 \`openfeel flow wizard\` 推进流水线）；本 skill 只承载静态知识查阅。
+- 与 \`openfeel-tool-usage\` 协同：工具选择规范见该 skill；本 skill 补充 CLI 命令细节。
+
+> 本文档为 v1.1.2 快照；命令/参数细节以 \`openfeel <cmd> --help\`（本仓执行）实时输出为准（CLI 演进后本文档可能滞后）。
+>
+> ⚠️ **本仓自举**：本仓（openfeel 源码仓库）开发/执行时请用 \`node bin/openfeel.js <cmd>\`；安装后使用 \`openfeel <cmd>\`。
+
+## 命令速查
+
+| 命令 | 用途 | 关键参数 |
+|------|------|----------|
+| \`openfeel init [path]\` | 初始化项目工作区 | \`--lang <zh-CN\\|en>\`、\`--demo\`、\`--workspace-only\`、\`--non-interactive\` |
+| \`openfeel setup\` | 部署全局框架配置（不建项目 \`.openfeel/\`） | \`--lang <zh-CN\\|en>\` |
+| \`openfeel update [path]\` | 部署适配文件到目标项目 | \`--lang\`、\`--force\` |
+| \`openfeel migrate [path]\` | Legacy 布局迁移（检测/备份/迁移/回滚） | \`--dry-run\`、\`--remap-assignee\`、\`--clean-global-core-md\`；\`migrate rollback\` |
+| \`openfeel flow ...\` | 流水线状态管理 | 见下「flow 子命令」 |
+| \`openfeel plan stage add\\|list\` | 工作阶段管理 | \`add <name> --deps <ids...> --tasks <items...>\` |
+| \`openfeel plan scheme create\\|publish\\|rename\\|list\\|remove\` | 操作方案管理 | \`create <stage> <title> [--draft]\`、\`publish <stage> <opId>\`、\`rename <stage> <opId> --title <text>\`、\`remove <stage> <opId> [--force] [--dry-run]\` |
+| \`openfeel stage status\\|set\\|task\` | \`status.md\` 原子操作 | \`set <id> --status/--exec-mode/--auto-advance/--review-agent\`、\`task <id> [no] --add/--done/--undone\`（\`stage create\` 已弃用） |
+| \`openfeel config ...\` | 配置管理 | \`get\\|set <key> <value> [--global]\`（支持全量 \`defaults.*\`）、\`get-lang\\|set-lang\`、\`list-projects\`、\`effective [key]\` |
+| \`openfeel model set\\|get\\|list\` | 模型三层级配置 | \`set <agent> <model>\` |
+| \`openfeel lint i18n\\|kb\` | 健康检查（i18n 键一致性 / kb 过期引用） | 发现问题**非 0 退出** |
+| \`openfeel knowledge ...\` | 知识库管理 | \`list\` / \`add\` / \`search\` / \`index\` / \`dedup\` |
+| \`openfeel archive <stage>\` | 归档指定阶段（汇总产出、生成摘要、提取知识） | \`<stage>\` |
+| \`openfeel view list\\|accept\` | 审查条目验收（\`add\` 已移除，改用 \`flow review add\`） | — |
+| \`openfeel project overview\` | 项目结构概览 | \`overview\`（无 \`list\`/\`info\` 子命令） |
+| \`openfeel roadmap create\\|show\` | 分期大纲管理 | \`create <version>\`、\`show [version]\` |
+| \`openfeel instructions <artifactId>\` | 为指定 artifact 生成结构化指令 | \`--change <name>\`、\`--schema <name>\`、\`--json\` |
+
+**flow 子命令**：\`status\` / \`current\` / \`overview\` / \`phases\` / \`stage\` / \`metrics\` / \`advance\`（\`--stage <id> --to <phase>\`、\`--op\`、\`--force\`、\`--dry-run\`、\`--quiet\`）/ \`attempt\` / \`log\` / \`review\` / \`retry\` / \`repair\` / \`ops\` / \`migrate\` / \`checkpoint\` / \`health\` / \`recover\` / \`wizard\`。
+
+**纠错/清理侧补充**：\`flow review add|resolve|update|remove\`；\`flow ops list [--stage <id>] [--json]\`（操作方案视图，draft 分组展示）；\`flow repair [--prune-orphans]\`（默认只报告，\`--prune-orphans\` 仅清键孤儿，单向不删文件）。
+
+> 命令职责分层：\`plan stage add\`（完整，推荐）> \`flow stage add\`（仅注册 \`flow.json\`，不建目录）> \`stage create\`（已弃用）。
+
+## v1.1.2 新增能力（stage-41~55）
+
+> 以下为 v1.1.2 相对上版的增量能力（分组摘要，细节以 \`<cmd> --help\` 为准）。
+
+- **A. 自描述与可纠错（stage-41）**：\`flow phases [--json]\`（**5 键**：\`schemaVersion\`/\`phases\`/\`transitions\`/\`advanceAccepted\`/\`transitionsDiff\`）、\`flow stage remove [--force] [--dry-run] [--purge]\`、stageId 校验/冲突检测（\`validateStageId\` / \`suggestStageId\` / \`findStageDirConflict\`）、\`plan stage add --deps\`。
+- **B. 状态与口径（stage-42）**：\`config effective [key]\`（有效值 + 生效来源 \`status.md > config.yaml > profile.yaml > builtin\`）、\`pipeline.phase\` 全量 done 判定、审计日志 \`register_stage\` / \`register_op\`。
+- **C. 部署与备份（stage-46）**：覆盖写前自动备份 \`~/.openfeel/backup/{ts}/\` + \`update_infos.md\`「备份」类条目（Agent 按 \`feel.md\` 检查规则核对）。
+- **D. 纠正/清理侧命令面（stage-51/52）**：\`plan scheme remove\`（仅删 \`flow.json\` 注册键，不删 op 文件；done/checkpoint 保护）、\`plan scheme rename --title\`（必填，空标题报错）、\`plan scheme publish\` + \`create --draft\`（draft→pending，空模板拒绝）、\`flow stage set --deps\`（覆盖写入；**不带 \`--deps\` 视为清空**）、\`flow review update|remove\`、\`stage set\`（**幂等**：同值 no-op + 同值不生成 \`.bak\`；\`--exec-mode <manual\\|auto>\` / \`--auto-advance <enabled\\|disabled>\` / \`--review-agent <agent>\`）、\`stage task --add|--done|--undone\`、\`plan stage add --tasks\`、\`flow repair --prune-orphans\`、\`flow health --fix [--dry-run]\`（默认只报告；\`--fix\` **仅回写 status.md「状态」字段**；\`--dry-run\` 预览零写盘）、\`flow ops list\`、\`flow advance --quiet\` + \`--to <远距 phase>\`（存在唯一路径时自动逐步；\`--dry-run\` 展示完整路径）、\`knowledge dedup\`（检索相似条目，**只读建议，不修改 kb**）。\`flow attempt\` 对 **draft op 拒绝**。
+- **E. 输出/门禁/约定（stage-50/52）**：\`flow status/current/health/metrics/overview --json\`（纯 JSON 单文档，含 \`schemaVersion\`）、\`lint i18n\`/\`lint kb\` **非 0 退出**（门禁语义，无逃生阀）、\`config set/get\` 支持**全量 \`defaults.*\`**（Schema 驱动键白名单 + 值类型归一 + 枚举校验，非法报错不写盘）、\`view add\` **已移除**（改用 \`flow review add\`）、\`NO_COLOR\` 环境变量 / \`--no-color\`。
+
+## phase 枚举与转移表
+
+15 个 phase（\`plan_pending\` … \`done\`）：
+
+\`\`\`
+plan_pending → plan_review → plan_passed → scheme_pending → scheme_review
+→ scheme_passed → exec_running → review_pending → review_passed → test_pending
+→ test_passed → archiving → done
+\`\`\`
+
+| phase | 合法目标 |
+|-------|----------|
+| \`plan_pending\` | \`plan_review\`, \`plan_passed\` |
+| \`plan_review\` | \`plan_passed\`, \`plan_pending\` |
+| \`plan_passed\` | \`scheme_pending\` |
+| \`scheme_pending\` | \`scheme_review\`, \`scheme_passed\` |
+| \`scheme_review\` | \`scheme_passed\`, \`scheme_pending\` |
+| \`scheme_passed\` | \`exec_running\` |
+| \`exec_running\` | \`review_pending\`, \`scheme_pending\` |
+| \`review_pending\` | \`review_failed\`, \`review_passed\` |
+| \`review_failed\` | \`review_pending\`, \`scheme_pending\` |
+| \`review_passed\` | \`test_pending\` |
+| \`test_pending\` | \`test_failed\`, \`test_passed\` |
+| \`test_failed\` | \`test_pending\`, \`scheme_pending\` |
+| \`test_passed\` | \`archiving\` |
+| \`archiving\` | \`done\` |
+| \`done\` | （终态） |
+
+- 转移表以**运行时** \`.openfeel/pipeline.yaml\` 为准；\`openfeel flow phases\` 查看当前生效值。
+- 推进：\`openfeel flow advance --stage <id> --to <phase>\`。**\`advanceAccepted\` = 内置 15 个 phase 的「推进白名单」**（\`flow advance\` 只接受这 15 个值），**不是**组合式条件键的替代品（旧文案曾误述，此处已更正）。**组合式条件差异**（如内置默认含 \`review_passed|test_passed\`，本仓 \`pipeline.yaml\` 未列）经 \`--json.transitionsDiff.missing\` **显式可见**（stage-50 裁定：**不补组合键**，改以 \`transitionsDiff\` 显式化）。
+- 参考：\`.openfeel/manual/**\`（CLI/flow 模块文档）。
+
+## stageId 命名与目录映射
+
+| 格式 | 示例 | series / stageDir |
+|------|------|-------------------|
+| 完整四级 | \`v1.1.2-stage-43\` | \`v1\` / \`stage-43\` |
+| 历史短版 | \`v4-stage-04\` | \`v4\` / \`stage-04\` |
+| 短名 | \`stage-01\` | \`v1\`（默认）/ \`stage-01\` |
+
+- \`series = v{MAJOR}\`；目录映射 \`.openfeel/plan/{series}/stage-{NN}/\`。
+- 唯一性：\`(series, stageDir)\` 冲突（如 \`v4-stage-04\` 与 \`v4.0.0-stage-04\` 映射同目录）会被 \`findStageDirConflict\` 检出并阻止；非法输入由 \`validateStageId\` 报原因 + \`suggestStageId\` 给建议名（\`NN\` 限定在同 series 内 max+1）。
+- 权威实现与三级回退：见 \`.openfeel/manual/core/plan-path.md\`。
+
+## 典型场景
+
+1. **落地新阶段**：\`openfeel plan stage add v1.1.2-stage-43\`（建目录 + 注册）→ \`openfeel flow advance --stage v1.1.2-stage-43 --to plan_pending\` 起步。
+2. **声明依赖**：\`openfeel plan stage add v1.1.2-stage-43 --deps v1.1.2-stage-41 v1.1.2-stage-47\`（写入 \`overview.md\`「## 依赖」+ \`flow.json.stages[].deps\`）。
+3. **纠错移除误建阶段**：\`openfeel flow stage remove v1.1.2-stage-43 --dry-run\` 预览 → 确认后 \`--force\`（必要时 \`--purge\` 删目录）。
+4. **查询有效配置**：\`openfeel config effective auto_advance\`（来源优先级 \`status.md\` > \`config.yaml\` > \`profile.yaml\` > \`builtin\`）。
+5. **部署前备份**：\`setup\`/\`update\`/\`init\`/\`migrate\` 覆盖写入前自动备份至 \`~/.openfeel/backup/{ts}/\`；\`update_infos.md\` 会新增「备份」类条目，Agent 须按 \`feel.md\` 检查规则核对（存在性 + 失败重跑）。
+
+## 权限模型要点
+
+- 9 个 agent 内联 \`permission:\` 白名单，均含 \`external_directory: "allow"\`（单一键，无读写粒度）。
+- **合并语义**：agent \`.md\` frontmatter 与 \`opencode.jsonc\` 按权限键**深合并**，同名键以 agent \`.md\` 为准（配置文件无法覆盖已声明键）。
+- **收紧入口**：项目根 \`.opencode/agent/<name>.md\` 覆盖全局同名 agent 并重写完整 \`permission\` 块；勿手改全局 agent frontmatter（会被 \`update\` 覆盖）。
+- 详 \`.openfeel/manual/core/permission.md\`。
+
+## 与 openfeel-wizard 的区别
+
+| 维度 | \`openfeel-cli-usage\`（本 skill） | \`openfeel-wizard\` |
+|------|--------------------------------|-------------------|
+| 定位 | 查询型**参考手册**（只读静态知识） | 执行型**交互向导**（跑 \`openfeel flow wizard\`） |
+| 动作 | 回答「命令/参数/phase/stageId 是什么」 | 逐步选择并推进阶段 phase |
+| 前置 | 无 | 需交互式 TTY（非 TTY 用 \`flow advance --stage <id> --to <phase>\`） |
+
+> wizard skill 正文已交叉引用本 skill；二者正文互引，边界为「查手册 vs 跑向导」。
 `,
     'openfeel-get-bugs': `---
 name: openfeel-get-bugs
@@ -514,6 +630,8 @@ description: 加载流水线健康检查结果，供 Agent 判断 flow.json 与
 
 # 流水线健康检查
 
+> ⚠️ **本仓自举**：本仓（openfeel 源码仓库）开发/执行时请用 \`node bin/openfeel.js <cmd>\`；安装后使用 \`openfeel <cmd>\`。
+
 ## 输入
 
 无
@@ -535,6 +653,8 @@ description: Feel 自检时检查所有 Agent 的模型配置状态，识别期
 
 # 模型配置检查
 
+> ⚠️ **本仓自举**：本仓（openfeel 源码仓库）开发/执行时请用 \`node bin/openfeel.js <cmd>\`；安装后使用 \`openfeel <cmd>\`。
+
 ## 触发时机
 
 Feel Agent 在以下时机加载本 Skill：
@@ -550,7 +670,7 @@ Feel Agent 在以下时机加载本 Skill：
 
 | 配置文件 | 平台 |
 |----------|------|
-| \`opencode.jsonc\` | OpenCode |
+| \`opencode.jsonc\` | OpenCode（当前适配器） |
 | \`kilo/kilo.json\` | Kilo |
 | \`claude/claude.json\` | Claude |
 
@@ -647,7 +767,7 @@ models:
 \`\`\`markdown
 ## 🔍 模型配置检查报告
 
-**平台**：OpenCode
+**平台**：OpenCode（当前适配器）
 **配置文件**：.openfeel/config.yaml
 **检查时间**：yyyy-mm-dd HH:MM
 
@@ -700,7 +820,7 @@ models:
 # 或直接复制此文件到 .openfeel/ 并重命名为 config.yaml（需合并其他节）
 #
 # 最近配置时间：yyyy-mm-dd HH:MM
-# 平台：OpenCode
+# 平台：OpenCode（当前适配器）
 
 models:
   default:
@@ -727,7 +847,7 @@ models:
 `,
     'openfeel-model-config': `---
 name: openfeel-model-config
-description: 查找和配置 Agent 模型。当 Agent 报 "Model not found" 或需要调整/新增 Agent 模型时使用。覆盖 opencode.jsonc 配置、模型名查找方法、多模态模型（openfeel-vision）特殊注意事项。
+description: 查找和配置 Agent 模型。当 Agent 报 "Model not found" 或需要调整/新增 Agent 模型时使用。覆盖 opencode.jsonc 配置（opencode 适配器）、模型名查找方法、多模态模型（openfeel-vision）特殊注意事项。
 ---
 
 # Skill: openfeel-model-config
@@ -809,6 +929,8 @@ description: 跨会话上下文恢复，供 Agent 在会话启动时重建流水
 
 # 跨会话上下文恢复
 
+> ⚠️ **本仓自举**：本仓（openfeel 源码仓库）开发/执行时请用 \`node bin/openfeel.js <cmd>\`；安装后使用 \`openfeel <cmd>\`。
+
 ## 输入
 
 无
@@ -816,9 +938,11 @@ description: 跨会话上下文恢复，供 Agent 在会话启动时重建流水
 ## 执行步骤
 
 1. 运行 \`openfeel flow recover\` 获取全局状态、流水线阶段、当前操作、阻塞原因与待处理任务
-2. 读取 \`.openfeel/users/{username}/dev_last.md\` 恢复上次操作状态与待续事项
+2. 读取**索引** \`.openfeel/users/{username}/dev_last.md\`（「用户偏好」「主题索引」「公共交接区」）→ **按需**再读主题文件（**文件名英文，如 \`decisions.md\`/\`pending.md\`**）恢复详情；**旧格式**（无 \`## 主题索引\` 节）→ 触发惰性迁移（按英文命名映射拆分生成 \`dev_last/\` + 索引，原文保留）
 3. 将两者合并为当前会话起点
 
+> **加锁提示（A9）**：恢复流程为**只读**，无需加锁；仅**会话末尾写入**走 \`withFileLock\` 临界区（见 agents-md「并发写加锁协议」）。
+
 ## 输出
 
 恢复摘要：流水线状态 + 阻塞项 + 待处理任务列表
@@ -970,7 +1094,7 @@ description: 语义检索 .openfeel/kb/ 项目知识库。当精确匹配无结
 `,
     'openfeel-sync-status': `---
 name: openfeel-sync-status
-description: 聚合所有成员的任务进度视图，供任意 Agent 快速了解项目整体协作状态。
+description: 聚合所有成员的任务进度视图（各用户 dev_last 索引主题 + flow.json 阶段状态），供任意 Agent 快速了解项目整体协作状态。
 ---
 
 # Skill: openfeel-sync-status
@@ -979,63 +1103,91 @@ description: 聚合所有成员的任务进度视图，供任意 Agent 快速了
 
 ## 输入
 
-无（自动从 \`.openfeel/dev/current.md\` 提取）
+无（**自动**：各用户 \`.openfeel/users/*/dev_last.md\` 索引「主题索引」+ \`flow.json\` 阶段状态 \`stages[].phase/status\`）
 
 ## 执行步骤
 
-### 1. 读取进度文件
+### 1. 读取进度来源
 
-读取 \`.openfeel/dev/current.md\`，提取所有 \`@{username}\` 行。
+读取 \`.openfeel/users/*/dev_last.md\` 的「主题索引」摘要 + \`flow.json\` 的 active stages；**按用户聚合**展示。
 
-### 2. 解析任务条目
+### 2. 解析条目
 
-对每行提取：
-- **成员**：\`@{username}\` 后的用户名
-- **模块**：\`[模块名]\` 或 \`[-]\`
-- **状态**：\`进行中\` / \`阻塞\` / \`已完成\`
-- **描述**：状态后的任务描述文本
-- **锁定**：若有 \`🔒\` 标记，列出锁定的文件
+对每个用户提取：
+- **成员**：用户目录名（\`.openfeel/users/{username}/\`）
+- **主题**：\`dev_last.md\`「主题索引」中的显示主题名（附英文文件名 \`dev_last/{english-name}.md\`）
+- **摘要**：各主题下 ≤5 条核心摘要（≤100 字）
+- **阶段**：\`flow.json\` 中与该用户相关的阶段 \`phase\` / \`status\`
 
 ### 3. 查漏补缺
 
-- 对比 \`.openfeel/users/\` 下的所有用户目录，检查是否有成员在 \`current.md\` 中无记录
+- 对比 **\`flow.json\` active stages** 与各用户 \`dev_last\` 索引覆盖的 stage，检查是否存在**无任何用户索引覆盖的活跃阶段**
 - 若有，标记为「未同步」
 
 ### 4. 格式化输出
 
-按状态分组输出（进行中 → 阻塞 → 已完成 → 未同步），格式：
+按阶段/用户分组输出，格式：
 
 \`\`\`
 📊 项目协作进度
 
-🟢 进行中（N 人）
-  @alice  [auth] 登录模块重构
-    🔒 src/auth/login.py
-  @bob    [db]   数据库迁移脚本编写
-    🔒 migrations/v2.sql
-
-🟡 阻塞（M 人）
-  @charlie [api] 等待第三方 OAuth 审批
+🟢 {stage-id} [{phase}]
+  {username}
+    - {主题显示名}（\`dev_last/{english-name}.md\`）：{摘要（≤100 字）}
 
-🔵 已完成（K 人）
-  @dave [config] 环境变量模板补充
+🟡 阻塞
+  {username} — {阻塞原因（若 dev_last 索引标注）}
 
-⚪ 未同步（L 人）
-  @eve — 尚未在 current.md 中声明任务
+⚪ 未同步
+  {username} — 尚无主题索引条目
+  {stage-id} — 无用户索引覆盖
 \`\`\`
 
 ### 5. 偏离告警
 
-若发现同一模块有 2 人同时标记为「进行中」且无 🔒 区分，输出告警：
+若同一 stage 在 \`flow.json\` 标记为活跃，但**所有用户索引均未覆盖**，输出告警：
 
 \`\`\`
-⚠️ 模块 [module_name] 多人同时活跃，请确认无冲突
+⚠️ 阶段 {stage_id} 处于活跃状态但无用户索引覆盖，请确认存在负责成员
 \`\`\`
 
 ## 输出
 
 格式化后的 Markdown 进度摘要，不含文件修改。
+`,
+    'openfeel-tool-usage': `---
+name: openfeel-tool-usage
+description: Agent 工具使用规范（todowrite/question/task/skill 四工具触发条件、使用要求、禁止行为 + 优先级表）。
+---
+
+# Agent 工具使用规范
+
+## 输入
+
+无
+
+## 执行步骤
+
+### 1. todowrite — 任务列表管理
+触发条件（任一即用）：多个独立步骤（多文件改动、需跨会话跟踪等） / 多任务下达 / 跨文件修改。使用要求：执行前创建、单条 in_progress、完成即标 completed、新步骤追加末尾。
 
+### 2. question — 向用户提问
+触发条件（任一必问）：需求歧义 / 多个同等合理方案 / 不可逆后果 / 架构决策。使用要求：(Recommended) 标记、选项附后果、≤3 选项、高风险含"取消"。禁止：模糊时自行假设、多方案不选直接实施。
+
+### 3. task — 子 Agent 调度
+触发条件：并行探索多代码区 / 复杂多步委托 general / 下游 Agent（经 Feel）。使用要求：并行一条消息多 task、prompt 含任务描述+期望返回、明确只读/可写。
+
+### 4. skill — 技能加载
+触发条件：查阶段状态→openfeel-get-stage-status / 查知识库→openfeel-check-kb / 取 Bug→openfeel-get-bugs。使用要求：会话开始载 check-kb、处理阶段任务前载 get-stage-status、不凭记忆跳过。
+
+### 5. 工具使用优先级
+| 场景 | 优先工具 | 禁止做法 |
+|------|---------|----------|
+| 多步骤任务 | todowrite | 凭记忆逐条执行 |
+| 需求不明确 | question | 自行假设后动手 |
+| 探索代码 | task(explore) | 手动逐个 grep/read |
+| 获取状态 | skill(openfeel-get-stage-status) | 凭记忆推断 |
+| 批量文件操作 | task(general) | 串行逐个处理 |
 `,
     'openfeel-update-stage-status': `---
 name: openfeel-update-stage-status
@@ -1179,6 +1331,43 @@ description: 交互式流水线向导，供 Agent 在终端中逐步推进流水
 向导推进结果：阶段 phase 变化（from → to），结束/退出提示
 
 > 注：需交互式终端（TTY），非交互环境请改用 \`openfeel flow advance --stage <id> --to <phase>\`
+>
+> ⚠️ **本仓自举**：本仓（openfeel 源码仓库）开发/执行时请用 \`node bin/openfeel.js <cmd>\`；安装后使用 \`openfeel <cmd>\`。
+>
+> 静态命令/参数/phase/stageId 参考见 \`openfeel-cli-usage\` skill（本 skill 负责交互式执行推进）。
+`,
+    'openfeel-workspace': `---
+name: openfeel-workspace
+description: 会话启动时检查并补齐 .openfeel/ 工作区目录结构与空文件的标准化操作步骤（mkdir 哪些目录、创建哪些空文件、读 .info.json 取用户名）。
+---
+
+# 工作区启动自检
+
+## 输入
+
+无（自动按 .openfeel/.info.json 与 ~/.openfeel/update_infos.md 推断）
+
+## 执行步骤
+
+### 1. 读取用户名
+读 \`.openfeel/.info.json\` 的 \`user\` 字段；缺失则 \`git config user.name\`。
+
+### 2. 检查公共域目录（缺失则 mkdir -p）
+\`.openfeel/dev/note/\`、\`.openfeel/dev/current_archive/\`、\`.openfeel/log/\`、\`.openfeel/code_review/\`、\`.openfeel/bugs/\`、\`.openfeel/plan/\`、\`.openfeel/kb/\`、\`.openfeel/tmp/\`
+
+### 3. 检查公共域文件（缺失则创建空文件）
+\`.openfeel/dev/dev_core.md\`、\`.openfeel/dev/current.md\`、\`.openfeel/dev/decisions.md\`、\`.openfeel/kb/index.md\`
+
+### 4. 检查私域目录（基于 {username}）
+\`.openfeel/users/{username}/log/\`、\`note/\`、\`code_review/\`、\`bugs/\`、\`tmp/\`、\`dev_last/\`（主题记录目录；**主题文件名英文**，如 \`pending.md\`/\`decisions.md\`）
+
+### 5. 检查私域文件
+\`.openfeel/users/{username}/dev_last.md\`（**索引**；同名目录 \`dev_last/\` 存主题文件，**文件名英文**）
+
+### 6. 增量更新复核
+检查 \`~/.openfeel/update_infos.md\`，若存在未修复条目（追加/异常），提醒用户重启会话或委托 Feel 处理；本 Agent 不自行修改该文件。
+
+> 目录结构语义、公共/私域分区、用户身份约束、路径自校验规则见全局 AGENTS.md（约束）；本 skill 仅承载操作步骤。
 `,
 };
 // AUTO-GENERATED-END: SKILL_DEFINITIONS
@@ -1196,7 +1385,7 @@ function composeManagedContent(content, type) {
  * 分派依据 detectFileType；jsonc 不走本函数（调用方走深度合并）。
  * target 供 update_infos 路径记录：全局资产 { isGlobal: true }，项目资产 { isGlobal: false, projectRoot }。
  */
-function writeManagedFile(filePath, content, stateKey, updateState, target) {
+function writeManagedFile(filePath, content, stateKey, updateState, target, command) {
     const type = detectFileType(filePath);
     if (type === null || type === 'jsonc') {
         // 无策略 / JSONC：不应到达（jsonc 由 updateProject 单独走深度合并）
@@ -1216,6 +1405,33 @@ function writeManagedFile(filePath, content, stateKey, updateState, target) {
     const existingFm = existingSplit?.frontmatter ?? null;
     const existingBody = existingSplit?.body ?? existing;
     const region = parseRegion(existingBody, type);
+    // 写前备份（B3）：目标已存在且本次将实际改变内容时调用；备份失败 → 'skipped'（不覆盖）
+    const runPreWriteBackup = () => {
+        try {
+            const backup = backupFileBeforeWrite(filePath, {
+                command,
+                projectPath: target.isGlobal ? undefined : target.projectRoot,
+            });
+            if (backup) {
+                appendUpdateInfo('backed', target.isGlobal
+                    ? { absolutePath: filePath, backupRel: backup.backupRel, command }
+                    : { projectRoot: target.projectRoot, relativePath: stateKey, backupRel: backup.backupRel, command });
+                notifyBackupIfTTY(backup.backupRel); // B6：仅 TTY
+            }
+            return 'ok';
+        }
+        catch (err) {
+            if (err instanceof BackupError) {
+                // 备份失败 → 记可区分异常（REV-004）并跳过该文件写入，返回既有 'skipped'
+                appendUpdateInfo('anomaly', target.isGlobal
+                    ? { absolutePath: filePath, note: 'backup_failed' }
+                    : { projectRoot: target.projectRoot, relativePath: stateKey, note: 'backup_failed' });
+                console.warn(t('update.fileWriteSkipTmpl', getCliLang(target.projectRoot ?? process.cwd()), { err: err.message }));
+                return 'skipped';
+            }
+            throw err;
+        }
+    };
     if (region.status === 'ok') {
         // 含标记：frontmatter 合并 + 正文区内替换，全文比对（REV-901 skip 判定）
         // incoming 无 frontmatter（如 core.md/AGENTS.md 模板）时保留用户已有 frontmatter，避免写入丢失（REV-1101）
@@ -1225,6 +1441,9 @@ function writeManagedFile(filePath, content, stateKey, updateState, target) {
         if (newContent === normalize(existing)) {
             return 'skipped';
         }
+        if (runPreWriteBackup() === 'skipped') {
+            return 'skipped';
+        }
         atomicWriteFileSync(filePath, newContent);
         return 'updated';
     }
@@ -1233,12 +1452,18 @@ function writeManagedFile(filePath, content, stateKey, updateState, target) {
         const fileState = updateState?.files[stateKey];
         if (fileState && hashContent(existing) === fileState.hash) {
             // adopt：存量框架文件未改 → 直接写带标记的新框架内容（等价 created 记为 updated）
+            if (runPreWriteBackup() === 'skipped') {
+                return 'skipped';
+            }
             atomicWriteFileSync(filePath, composeManagedContent(content, type));
             return 'updated';
         }
         // 追加受管区（标记包裹正文，不触碰 frontmatter），并记录待会话启动复核
         const appendedRegion = wrapRegion(incomingBody, type);
         const sep = existing.endsWith('\n') ? '' : '\n';
+        if (runPreWriteBackup() === 'skipped') {
+            return 'skipped';
+        }
         atomicWriteFileSync(filePath, `${existing}${sep}${appendedRegion}`);
         appendUpdateInfo('appended', target.isGlobal ? { absolutePath: filePath } : { projectRoot: target.projectRoot, relativePath: stateKey });
         return 'appended';
@@ -1254,8 +1479,8 @@ function writeManagedFile(filePath, content, stateKey, updateState, target) {
  * 即 stateKey = 绝对路径、target 为全局资产。
  * @returns 动作分类，供调用方报告。
  */
-export function deployGlobalAsset(filePath, content, state) {
-    return writeManagedFile(filePath, content, filePath, state, { isGlobal: true });
+export function deployGlobalAsset(filePath, content, state, command) {
+    return writeManagedFile(filePath, content, filePath, state, { isGlobal: true }, command);
 }
 /** 将 writeManagedFile 的动作分发到对应结果数组 */
 function pushAction(action, stateKey, created, updated, skipped, appended) {
@@ -1299,77 +1524,14 @@ export function updateProject(projectPath, selectedTools = ["opencode"], lang =
     const legacyDirs = ['agents', 'skills', 'instructions']
         .filter((d) => existsSync(resolve(projectPath, '.opencode', d)));
     if (legacyDirs.length > 0) {
-        console.warn(`[update] 检测到项目内旧布局 .opencode/{${legacyDirs.join(',')}}，请运行 openfeel migrate（stage-39 提供）迁移。`);
+        console.warn(t('update.legacyLayoutWarnTmpl', getCliLang(projectPath), { dirs: legacyDirs.join(',') }));
     }
     // 全局部署目标（D1）
     const agentsDir = getGlobalAgentsDir();
     const skillsDir = getGlobalSkillsDir();
-    // 项目内旧布局 agents 目录：仅用于 AGENTS.md 首次部署判定，保持原语义（项目级）
-    const projectLegacyAgentsDir = resolve(projectPath, '.opencode', 'agents');
     // 确保全局目标目录存在
     mkdirSync(agentsDir, { recursive: true });
     mkdirSync(skillsDir, { recursive: true });
-    // ── AGENTS.md 语言同步逻辑 ──
-    let agentsDirHasContent = false;
-    try {
-        agentsDirHasContent = existsSync(projectLegacyAgentsDir) && readdirSync(projectLegacyAgentsDir).length > 0;
-    }
-    catch {
-        agentsDirHasContent = false;
-    }
-    const agentsMdPath = resolve(projectPath, 'AGENTS.md');
-    const agentsMdExists = existsSync(agentsMdPath);
-    if (!agentsDirHasContent && !agentsMdExists) {
-        // 情况 1：首次部署 → 使用全局默认语言部署 AGENTS.md（受管区标记包裹）
-        const globalConfig = getGlobalConfig();
-        const deployLang = lang ?? globalConfig.lang ?? 'zh-CN';
-        const agentsMdContent = loadTemplate(deployLang, 'agents-md');
-        atomicWriteFileSync(agentsMdPath, composeManagedContent(agentsMdContent, 'markdown'));
-        created.push('AGENTS.md');
-    }
-    else if (!agentsMdExists && options?.lang) {
-        // 情况 2b：已有 agents 目录但 AGENTS.md 被手动删除 + --lang 指定
-        // → 用指定语言重新创建 AGENTS.md（受管区标记包裹）
-        const agentsMdContent = loadTemplate(options.lang, 'agents-md');
-        atomicWriteFileSync(agentsMdPath, composeManagedContent(agentsMdContent, 'markdown'));
-        created.push('AGENTS.md');
-    }
-    else if (agentsMdExists && options?.lang) {
-        // 情况 2：已有项目 + --lang 参数指定了语言
-        const projectLang = getLang(projectPath);
-        const requestedLang = options.lang;
-        if (requestedLang !== projectLang) {
-            // 语言不同 → 提示确认
-            if (options?.force) {
-                // --force → 跳过确认，直接覆盖（受管区标记包裹）
-                const agentsMdContent = loadTemplate(requestedLang, 'agents-md');
-                atomicWriteFileSync(agentsMdPath, composeManagedContent(agentsMdContent, 'markdown'));
-                updated.push('AGENTS.md');
-            }
-            else if (options?.interactive) {
-                // 交互模式 → 输出冲突警告，跳过 AGENTS.md，继续执行后续框架更新
-                console.warn(`[update] AGENTS.md language mismatch: project=${projectLang}, requested=${requestedLang}. Skipped. Use --force to override.`);
-                skipped.push('AGENTS.md (language conflict)');
-            }
-            else {
-                // 非交互模式 → 输出警告，不覆盖
-                console.warn(`[update] AGENTS.md language mismatch: project=${projectLang}, requested=${requestedLang}. Skipped. Use --force to override.`);
-                skipped.push('AGENTS.md');
-            }
-        }
-        else {
-            // 语言相同 → 走受管文件三态（含标记区内替换 / 无标记 hash 兜底 / 追加）
-            const templateContent = loadTemplate(requestedLang, 'agents-md');
-            const action = writeManagedFile(agentsMdPath, templateContent, 'AGENTS.md', state, { isGlobal: false, projectRoot: projectPath });
-            pushAction(action, 'AGENTS.md', created, updated, skipped, appended);
-        }
-    }
-    else if (agentsMdExists) {
-        // 情况 3：已有项目 + 无 --lang 参数 → 走受管文件三态
-        const templateContent = loadTemplate(lang, 'agents-md');
-        const action = writeManagedFile(agentsMdPath, templateContent, 'AGENTS.md', state, { isGlobal: false, projectRoot: projectPath });
-        pushAction(action, 'AGENTS.md', created, updated, skipped, appended);
-    }
     // 记录项目语言映射到全局配置
     // 使用 options?.lang（用户通过 --lang 显式指定的语言）优先，
     // 回退到 lang（getCliLang 三级回退结果）。确保记录的语言与实际部署语言一致。
@@ -1381,18 +1543,26 @@ export function updateProject(projectPath, selectedTools = ["opencode"], lang =
     }
     // 全局 state 可写实例：首次 null → 降级重建（后续全量写入全局资产，防静默不部署）
     const newGlobalState = globalState ?? createGlobalUpdateState({});
-    // 0. 生成全局框架约束 core.md（~/.config/opencode/openfeel/core.md）
-    const coreInstructionsPath = getGlobalCoreMdPath();
-    const coreContent = loadTemplate(lang, 'core-instructions');
+    // v1.1.1：存量全局 state 的 core.md key → 全局 AGENTS.md key（一次性重映射）
+    // 说明：在 newGlobalState 创建后执行（newGlobalState = globalState ?? createGlobalUpdateState({})；
+    // 非 null 时二者同引用，故直接改 globalState 即改 newGlobalState）。
+    const staleCoreKey = getGlobalCoreMdPath();
+    if (globalState && globalState.files[staleCoreKey] && !globalState.files[getGlobalAgentsMdPath()]) {
+        globalState.files[getGlobalAgentsMdPath()] = globalState.files[staleCoreKey];
+        delete globalState.files[staleCoreKey];
+    }
+    // 0. 生成全局框架约束 AGENTS.md（~/.config/opencode/AGENTS.md）
+    const agentsMdPath = getGlobalAgentsMdPath();
+    const agentsMdContent = loadTemplate(lang, 'agents-md');
     {
-        const action = deployGlobalAsset(coreInstructionsPath, coreContent, newGlobalState);
-        pushAction(action, coreInstructionsPath, created, updated, skipped, appended);
+        const action = deployGlobalAsset(agentsMdPath, agentsMdContent, newGlobalState, 'update');
+        pushAction(action, agentsMdPath, created, updated, skipped, appended);
     }
     // 1. 生成 Agent 定义文件到全局 agents 目录（绝对路径作 state key）
     for (const name of listAgentIds(lang)) {
         const content = loadAgentTemplate(lang, name);
         const filePath = join(agentsDir, `${name}.md`);
-        const action = deployGlobalAsset(filePath, content, newGlobalState);
+        const action = deployGlobalAsset(filePath, content, newGlobalState, 'update');
         pushAction(action, filePath, created, updated, skipped, appended);
     }
     // 2. 生成 Skill 定义文件到全局 skills 目录（每个 Skill 一个子目录，包含 SKILL.md）
@@ -1400,27 +1570,51 @@ export function updateProject(projectPath, selectedTools = ["opencode"], lang =
         const skillSubDir = join(skillsDir, name);
         mkdirSync(skillSubDir, { recursive: true });
         const filePath = join(skillSubDir, 'SKILL.md');
-        const action = deployGlobalAsset(filePath, content, newGlobalState);
+        const action = deployGlobalAsset(filePath, content, newGlobalState, 'update');
         pushAction(action, filePath, created, updated, skipped, appended);
     }
     // 3. 全局 opencode.jsonc：深度合并（保留用户字段），加全局锁 + 原子写
     const globalJsoncPath = getGlobalOpencodeJsoncPath();
-    // REV-1805：read-merge-write 全部置于锁内，消除与 model-config 锁内读写的 TOCTOU 竞态
-    const globalJsoncNew = withFileLock(globalLockPath('global-opencode-jsonc'), () => {
-        const current = existsSync(globalJsoncPath) ? readFileSync(globalJsoncPath, 'utf-8') : '{}\n';
-        let merged;
-        // 合并可能因块注释 parse 失败抛异常（parseJsonc 边界）：降级为「跳过合并、保留原文件」并告警
-        try {
-            merged = mergeGlobalOpencodeJsonc(current);
+    try {
+        // 写前备份（B3）：备份须在 jsonc 锁之外（之前）完成，避免 backup 锁与 jsonc 锁嵌套
+        const globalJsoncBackup = backupFileBeforeWrite(globalJsoncPath, { command: 'update' });
+        if (globalJsoncBackup) {
+            appendUpdateInfo('backed', { absolutePath: globalJsoncPath, backupRel: globalJsoncBackup.backupRel, command: 'update' });
+            notifyBackupIfTTY(globalJsoncBackup.backupRel);
         }
-        catch (err) {
-            console.warn(`[update] 全局 opencode.jsonc 解析失败（可能含块注释），跳过合并保留原文件: ${err.message}`);
-            merged = current;
+        // REV-1805：read-merge-write 全部置于锁内，消除与 model-config 锁内读写的 TOCTOU 竞态
+        const globalJsoncNew = withFileLock(globalLockPath('global-opencode-jsonc'), () => {
+            // 安全读取（T50）：目录占位/不可读 → null，跳过合并与写入，按空配置继续
+            const current = readJsoncFile(globalJsoncPath);
+            if (current === null) {
+                return null;
+            }
+            let merged;
+            // 合并可能因块注释 parse 失败抛异常（parseJsonc 边界）：降级为「跳过合并、保留原文件」并告警
+            try {
+                merged = mergeGlobalOpencodeJsonc(current);
+            }
+            catch (err) {
+                console.warn(t('update.globalJsoncParseSkipTmpl', getCliLang(projectPath), { err: err.message }));
+                merged = current;
+            }
+            atomicWriteFileSync(globalJsoncPath, merged);
+            return merged;
+        });
+        if (globalJsoncNew !== null) {
+            updateFileHash(newGlobalState, globalJsoncPath, globalJsoncNew);
+        }
+    }
+    catch (err) {
+        if (err instanceof BackupError) {
+            // 备份失败（REV-011-A）：跳过全局 jsonc 写入、记 anomaly、继续其余步骤（对齐 B3 幂等语义）
+            appendUpdateInfo('anomaly', { absolutePath: globalJsoncPath, note: 'backup_failed' });
+            console.warn(t('update.globalJsoncWriteSkipTmpl', getCliLang(projectPath), { err: err.message }));
         }
-        atomicWriteFileSync(globalJsoncPath, merged);
-        return merged;
-    });
-    updateFileHash(newGlobalState, globalJsoncPath, globalJsoncNew);
+        else {
+            throw err; // 非备份错误照旧上抛（锁超时等不回退）
+        }
+    }
     // 4. 项目 opencode.jsonc：不存在则写最小 { $schema }；已存在则保留（旧非法字段清理属 stage-39）
     const projectJsoncPath = resolve(projectPath, 'opencode.jsonc');
     if (!existsSync(projectJsoncPath)) {
@@ -1520,17 +1714,16 @@ function writeConflictFile(projectPath, relativePath, currentContent, incomingCo
 }
 /**
  * 根据路径获取 incoming（openfeel 期望写入）内容
- * relativePath 现为全局绝对路径（框架资产）或项目相对路径（AGENTS.md / opencode.jsonc）：
- *  - getGlobalCoreMdPath() → loadTemplate(lang, 'core-instructions')
+ * relativePath 现为全局绝对路径（框架资产）或项目相对路径（opencode.jsonc）：
+ *  - getGlobalAgentsMdPath() → loadTemplate(lang, 'agents-md')
  *  - getGlobalAgentsDir()/{name}.md → loadAgentTemplate(lang, name)
  *  - getGlobalSkillsDir()/{name}/SKILL.md → SKILL_DEFINITIONS[name]
  *  - opencode.jsonc → buildProjectOpencodeJsoncObj()
- *  - AGENTS.md → loadTemplate(lang, 'agents-md')
  */
 function getIncomingContent(relativePath, lang) {
-    // 全局框架约束 core.md
-    if (relativePath === getGlobalCoreMdPath()) {
-        return loadTemplate(lang, 'core-instructions');
+    // 全局框架约束 AGENTS.md（v1.1.1：约束唯一权威）
+    if (relativePath === getGlobalAgentsMdPath()) {
+        return loadTemplate(lang, 'agents-md');
     }
     // 全局 agent：位于 getGlobalAgentsDir() 下的 {name}.md
     if (relativePath.startsWith(getGlobalAgentsDir())) {
@@ -1546,10 +1739,6 @@ function getIncomingContent(relativePath, lang) {
     if (relativePath === 'opencode.jsonc') {
         return JSON.stringify(buildProjectOpencodeJsoncObj(), null, 2) + '\n';
     }
-    // 项目 AGENTS.md
-    if (relativePath === 'AGENTS.md') {
-        return loadTemplate(lang, 'agents-md');
-    }
     // 未知路径 → 空内容（不应发生）
     return '';
 }