openfeel 1.0.8 → 1.1.0

package/dist/core/update.js

@@ -5,13 +5,19 @@
  * 变更摘要 (v3-stage-04 第二轮):
  * - 新增 instructions/core.md 创建（从 init.ts 迁移至此，职责归位适配器层）
  */
-import { writeFileSync, existsSync, readFileSync, mkdirSync, readdirSync } from 'node:fs';
-import { resolve, dirname, join } from 'node:path';
+import { existsSync, readFileSync, mkdirSync, readdirSync } 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';
-// 新增：update_state.json hash 比对与冲突检测
-import { hashContent, loadUpdateState, saveUpdateState, createUpdateState, updateFileHash, markFileConflict, getOpenfeelVersion, } from './update-state.js';
+import { getOpencodeGlobalDir, getGlobalAgentsDir, getGlobalSkillsDir, getGlobalCoreMdPath, 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';
+// 新增：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;
@@ -28,7 +34,7 @@ export const supportedTools = [
     {
         id: 'opencode',
         name: 'OpenCode',
-        description: 'OpenCode AI 编码助手 — 生成 Agent 定义和 /opfx:* 技能',
+        description: 'OpenCode AI 编码助手 — 生成 Agent 定义和 openfeel-* 技能',
         enabled: true,
     },
     // 后续扩展：
@@ -64,13 +70,13 @@ export async function selectTools() {
 // ─── Agent 定义由 template-loader.ts 统一管理 ──────────────────────────
 // ─── Skill 定义内容 ─────────────────────────────────────────────────
 // AUTO-GENERATED-BEGIN: SKILL_DEFINITIONS
-const SKILL_DEFINITIONS = {
-    'agent-model-check': `---
-name: agent-model-check
-description: Agent 模型检查与修复。当 Agent 报 "Model not found" 或需要排查模型配置时使用。涵盖 auth.json 校验、provider key 匹配、模型能力确认、Vision 多模态专项指南。
+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 多模态专项指南。
 ---
 
-# Skill: agent-model-check
+# Skill: openfeel-agent-model-check
 
 # Agent 模型检查与修复
 
@@ -79,7 +85,7 @@ description: Agent 模型检查与修复。当 Agent 报 "Model not found" 或
 - Agent 调度时报 \`Model not found: xxx\`
 - 需要验证某个 Agent 的模型是否可用
 - 新增 Agent 后需确认模型配置正确
-- 排查多模态（Vision）Agent 无法处理图片的问题
+- 排查多模态（openfeel-vision）Agent 无法处理图片的问题
 
 ## 排查流程
 
@@ -113,22 +119,22 @@ cat ~/.local/share/opencode/auth.json
 
 | 能力需求 | 需确认的字段 | 示例 |
 |----------|-------------|------|
-| 视觉/图像分析 | Input = Yes | \`qwen3-vl-plus\` |
+| 视觉/图像分析 | Input = Yes | \`deepseek-flash\` |
 | 工具调用 | Tool Call = Yes | \`qwen3.7-plus\` |
 | 结构化输出 | Structured = Yes | \`qwen3.7-flash\` |
 | 推理/思考 | Reasoning = Yes | \`qwq-plus\` |
 
 **常见陷阱**：
 - \`qwen3.7-plus\` 是纯文本模型，不支持图像输入
-- \`qwen3-vl-plus\` 是视觉模型，支持图像分析
-- 模型名中的 \`vl\` 表示 Vision-Language
+- \`deepseek-flash\` 支持多模态图像输入（openfeel-vision 现用模型）
+- 备选视觉模型：\`qwen3-vl-plus\`（模型名中的 \`vl\` 表示 Vision-Language）
 
 ### 第四步：检查 opencode.jsonc 配置
 
 \`\`\`jsonc
 {
   "agent": {
-    "vision": {
+    "openfeel-vision": {
       "model": "{auth.json_key}/{model_id}"  // 格式：provider_key/model_id
     }
   }
@@ -159,17 +165,18 @@ cat ~/.local/share/opencode/auth.json
 | opencode.jsonc 语法 | 检查 JSON 格式 | 无语法错误 |
 | 重启生效 | 重启 opencode 后重新测试 | 无 Model not found 报错 |
 
-## 多模态（Vision）Agent 专项
+## 多模态（openfeel-vision）Agent 专项
 
-Vision Agent 必须配置多模态模型。Alibaba 系列视觉模型：
+openfeel-vision Agent 必须配置多模态模型。当前默认使用 \`deepseek/deepseek-flash\`（已支持多模态图像输入）：
 
-| 模型 ID | 完整引用（alibaba-cn） | 上下文 | 图像输入 |
-|---------|----------------------|--------|---------|
-| qwen3-vl-plus | \`alibaba-cn/qwen3-vl-plus\` | 262K | ✅ |
+| 模型 ID | 完整引用 | 上下文 | 图像输入 |
+|---------|---------|--------|---------|
+| deepseek-flash | \`deepseek/deepseek-flash\` | — | ✅ |
+| qwen3-vl-plus | \`alibaba-cn/qwen3-vl-plus\` | 262K | ✅（备选） |
 | qwen-vl-plus | \`alibaba-cn/qwen-vl-plus\` | 131K | ❌（旧版） |
 | qwen-vl-max | \`alibaba-cn/qwen-vl-max\` | 131K | ❌（旧版） |
 
-**推荐**：优先使用 \`qwen3-vl-plus\`，上下文最大且为最新视觉模型。
+**推荐**：优先使用 \`deepseek-flash\`（已内置多模态）；如需更大上下文可备选 \`qwen3-vl-plus\`。
 
 ## 常见错误与修复
 
@@ -178,10 +185,10 @@ Vision Agent 必须配置多模态模型。Alibaba 系列视觉模型：
 | \`Model not found: Alibaba(China)/xxx\` | 使用了自定义 provider name 而非 auth.json key | 改为 auth.json 中的实际 key |
 | \`Model not found: alibaba/xxx\` | 内置 key 与实际注册的 key 不一致 | 检查 auth.json，使用实际 key |
 | \`Model not found: xxx. Did you mean: yyy\` | 模型名拼写错误或不存在 | 使用 \`Did you mean\` 建议的名称 |
-| Agent 调度成功但无法处理图片 | 配置了纯文本模型 | 改为带 \`vl\` 后缀的视觉模型 |
+| Agent 调度成功但无法处理图片 | 配置了纯文本模型 | 改为支持图像输入的模型（如 \`deepseek-flash\`） |
 `,
-    'bug-acceptance': `---
-name: bug-acceptance
+    'openfeel-bug-acceptance': `---
+name: openfeel-bug-acceptance
 description: 标准化 Bug 验收流程，供测试 Agent 或代码 Agent（自测后自查）调用。
 ---
 
@@ -233,8 +240,8 @@ description: 标准化 Bug 验收流程，供测试 Agent 或代码 Agent（自
 
 验收通过后，核心结论写入 \`.openfeel/bugs/{module}.md\`，并在公共日志简要记录。
 `,
-    'check-kb': `---
-name: check-kb
+    'openfeel-check-kb': `---
+name: openfeel-check-kb
 description: 渐进式查阅 .openfeel/kb/ 项目知识库，按当前任务需求返回最相关的参考信息。精确匹配无结果时自动触发语义检索回退，避免一次加载全量内容。
 ---
 
@@ -284,7 +291,7 @@ description: 渐进式查阅 .openfeel/kb/ 项目知识库，按当前任务需
 
 ### 5. 语义检索回退（自动）
 
-当精确匹配未找到任何相关条目（无 \`[+]\` 条目或所有条目与当前任务无关）时，**本技能自行执行语义检索**，无需调用方另行加载 \`search-kb\`：
+当精确匹配未找到任何相关条目（无 \`[+]\` 条目或所有条目与当前任务无关）时，**本技能自行执行语义检索**，无需调用方另行加载 \`openfeel-search-kb\`：
 
 1. **索引就绪检查**：检查 \`.openfeel/tmp/vectors/index.json\` 是否存在
 2. **索引缺失时**：输出以下提示后结束，不再继续回退：
@@ -323,7 +330,7 @@ description: 渐进式查阅 .openfeel/kb/ 项目知识库，按当前任务需
    💡 如需确保索引为最新，可运行: python scripts/build_kb_index.py --dry-run
    \`\`\`
 
-> 注：语义检索是 \`check-kb\` 的内置回退能力。调用方只需 \`skill("check-kb")\` 一次，无需再手动调用 \`search-kb\`。
+> 注：语义检索是 \`openfeel-check-kb\` 的内置回退能力。调用方只需 \`skill("openfeel-check-kb")\` 一次，无需再手动调用 \`openfeel-search-kb\`。
 
 ### 6. 强制检索标记
 
@@ -335,8 +342,8 @@ Skill 加载后，根据步骤 3 的匹配结果决定是否追加提示：
 
 - **若步骤 3 无相关条目**：不追加强制提示，静默返回（已在步骤 4 输出"知识库中暂无相关记录，可继续执行"）。
 `,
-    'get-bugs': `---
-name: get-bugs
+    'openfeel-get-bugs': `---
+name: openfeel-get-bugs
 description: 获取当前模块下状态为 open 或 fixing 的 Bug 列表，供代码 Agent 会话启动或承接时使用。
 ---
 
@@ -372,9 +379,9 @@ description: 获取当前模块下状态为 open 或 fixing 的 Bug 列表，供
 
 输出：\`模块 [模块名] 当前无待处理 Bug。\`
 `,
-    'get-stage-status': `---
-name: get-stage-status
-description: 读取 .openfeel/plan/{stage}/status.md，判断当前子计划状态、责任 Agent、是否允许自动推进以及下一步建议。用于 Reviewer/Executor/Feel Tester 在处理阶段任务前确认流程状态。
+    'openfeel-get-stage-status': `---
+name: openfeel-get-stage-status
+description: 读取 .openfeel/plan/{series}/{stage}/status.md，判断当前子计划状态、责任 Agent、是否允许自动推进以及下一步建议。用于 openfeel-reviewer/openfeel-executor/openfeel-feel-tester 在处理阶段任务前确认流程状态。
 ---
 
 # 获取子计划状态
@@ -382,6 +389,7 @@ description: 读取 .openfeel/plan/{stage}/status.md，判断当前子计划状
 ## 输入
 
 - 计划阶段名 \`{stage}\`（如 \`stage01\`、\`auth-login\`）
+- 阶段 ID \`{stage}\` 可为完整 \`vX.Y.Z.W-stage-NN\` 或短名 \`stage-NN\`，对应目录 \`plan/{series}/stage-NN/\`（\`{series}\` = 主版本系列，如 \`v1\`；短名默认 \`v1\`）
 - 若用户未提供阶段名，先读取 \`.openfeel/plan/index.md\` 查找当前活跃阶段；仍不明确时询问用户
 
 ## 执行步骤
@@ -392,7 +400,7 @@ description: 读取 .openfeel/plan/{stage}/status.md，判断当前子计划状
 
 ### 1. 定位状态文件
 
-读取 \`.openfeel/plan/{stage}/status.md\`。
+读取 \`.openfeel/plan/{series}/{stage}/status.md\`。
 
 若文件不存在：
 - 不要自行进入自动流程。
@@ -478,29 +486,29 @@ description: 读取 .openfeel/plan/{stage}/status.md，判断当前子计划状
 {若依赖就绪且可自动推进，列出同批次可并行启动的其他阶段}
 
 ## 下一步建议
-{根据状态给出下一步，例如：启动 Code、等待用户、启动 Tester、停止流程；若存在并行候选则建议批量启动}
+{根据状态给出下一步，例如：启动 Code、等待用户、启动 openfeel-feel-tester、停止流程；若存在并行候选则建议批量启动}
 \`\`\`
 
 ## 状态到下一步映射
 
 | 状态 | 下一步建议 |
 |------|------------|
-| \`planned\` | 等待用户确认或 Planner 细化计划 |
-| \`ready_for_code\` | Planner 可启动 Executor |
-| \`coding\` | Executor 正在开发 |
-| \`ready_for_review\` | Executor 可启动 Reviewer 审查，或等待用户触发 |
-| \`review_failed\` | Reviewer 可启动 Executor 修复审查问题 |
+| \`planned\` | 等待用户确认或 openfeel-planner 细化计划 |
+| \`ready_for_code\` | openfeel-planner 可启动 openfeel-executor |
+| \`coding\` | openfeel-executor 正在开发 |
+| \`ready_for_review\` | openfeel-executor 可启动 openfeel-reviewer 审查，或等待用户触发 |
+| \`review_failed\` | openfeel-reviewer 可启动 openfeel-executor 修复审查问题 |
 | \`review_passed\` | Feel 可推进到 ready_for_test |
-| \`ready_for_test\` | Feel 可启动 Feel Tester |
-| \`test_writing\` | Feel Tester 正在写测试 |
-| \`testing\` | Feel Tester 正在测试 |
-| \`bug_found\` | Feel Tester 可启动 Executor 修复 Bug |
-| \`bug_fixing\` | Executor 正在修复 Bug |
+| \`ready_for_test\` | Feel 可启动 openfeel-feel-tester |
+| \`test_writing\` | openfeel-feel-tester 正在写测试 |
+| \`testing\` | openfeel-feel-tester 正在测试 |
+| \`bug_found\` | openfeel-feel-tester 可启动 openfeel-executor 修复 Bug |
+| \`bug_fixing\` | openfeel-executor 正在修复 Bug |
 | \`done\` | 流程完成，停止 |
 | \`paused\` | 等待用户处理暂停原因 |
 `,
-    'health': `---
-name: health
+    'openfeel-health': `---
+name: openfeel-health
 description: 加载流水线健康检查结果，供 Agent 判断 flow.json 与工作区状态是否一致。
 ---
 
@@ -520,8 +528,8 @@ description: 加载流水线健康检查结果，供 Agent 判断 flow.json 与
 
 健康检查摘要：通过项数、失败项列表及原因，失败时给出修复建议
 `,
-    'model-check': `---
-name: model-check
+    'openfeel-model-check': `---
+name: openfeel-model-check
 description: Feel 自检时检查所有 Agent 的模型配置状态，识别期望模型 vs 实际模型的差距，引导用户在目标工具中完成配置。首次配置后存储为部署模板，新项目可直接复用。
 ---
 
@@ -566,14 +574,14 @@ Feel Agent 在以下时机加载本 Skill：
 | Agent 文件 | 默认模型角色 |
 |------------|-------------|
 | \`feel.md\` | \`primary_reasoning\`（主力推理） |
-| \`planner.md\` | \`reasoning\`（推理） |
-| \`executor.md\` | \`fast\`（快速） |
-| \`reviewer.md\` | \`cross_model\`（异种推理） |
-| \`archiver.md\` | \`reasoning\`（推理） |
-| \`schemer.md\` | \`reasoning\`（推理） |
-| \`feel-tester.md\` | \`reasoning\`（推理） |
-| \`utility.md\` | \`fast\`（快速） |
-| \`vision.md\` | \`multimodal\`（多模态） |
+| \`openfeel-planner.md\` | \`reasoning\`（推理） |
+| \`openfeel-executor.md\` | \`fast\`（快速） |
+| \`openfeel-reviewer.md\` | \`cross_model\`（异种推理） |
+| \`openfeel-archiver.md\` | \`reasoning\`（推理） |
+| \`openfeel-schemer.md\` | \`reasoning\`（推理） |
+| \`openfeel-feel-tester.md\` | \`reasoning\`（推理） |
+| \`openfeel-utility.md\` | \`fast\`（快速） |
+| \`openfeel-vision.md\` | \`multimodal\`（多模态） |
 
 ### 3. 检查 config.yaml 模型配置
 
@@ -588,14 +596,14 @@ models:
     base_url: https://api.deepseek.com
     api_key_env: DEEPSEEK_API_KEY
   agents:            # Agent 级覆盖（可选）
-    reviewer:
+    openfeel-reviewer:
       provider: anthropic
       model_name: claude-sonnet-4-20250514
       base_url: https://api.anthropic.com
       api_key_env: ANTHROPIC_API_KEY
-    executor:
+    openfeel-executor:
       provider: deepseek
-      model_name: deepseek-v4-flash
+      model_name: deepseek-flash
   roles:             # 角色级覆盖（可选）
     cross_model:
       provider: openai
@@ -628,8 +636,8 @@ models:
 | Agent | 角色要求 | 实际模型 | 配置来源 | 状态 |
 |-------|----------|----------|----------|:--:|
 | Feel | 主力推理 | deepseek-v4-pro | default | ⚠️ |
-| Reviewer | **异种推理** | deepseek-v4-pro | default | ❌ 与主力相同！ |
-| Executor | 快速 | deepseek-v4-pro | default | ⚠️ 未使用快速模型 |
+| openfeel-reviewer | **异种推理** | deepseek-v4-pro | default | ❌ 与主力相同！ |
+| openfeel-executor | 快速 | deepseek-v4-pro | default | ⚠️ 未使用快速模型 |
 \`\`\`
 
 ### 5. 输出检查报告
@@ -672,8 +680,8 @@ models:
 | 触发条件 | 引导内容 |
 |----------|----------|
 | \`models\` 节不存在 | "未检测到模型配置。你需要为不同角色分配模型吗？" → 引导创建 |
-| Reviewer 使用与主力相同模型 | "⚠️ Reviewer 当前与 Feel 使用相同模型，异种交叉审查的核心优势无法发挥。建议为 Reviewer 配置不同的模型系列。" |
-| Executor 使用推理模型 | "⚠️ Executor 建议使用快速模型以节省成本。是否配置？" |
+| openfeel-reviewer 使用与主力相同模型 | "⚠️ openfeel-reviewer 当前与 Feel 使用相同模型，异种交叉审查的核心优势无法发挥。建议为 openfeel-reviewer 配置不同的模型系列。" |
+| openfeel-executor 使用推理模型 | "⚠️ openfeel-executor 建议使用快速模型以节省成本。是否配置？" |
 | 关键 Agent 无任何配置 | "以下 Agent 无模型配置：{列表}。请配置。" |
 
 ### 7. 写入配置
@@ -700,7 +708,7 @@ models:
     model_name: xxx
     ...
   agents:
-    reviewer:
+    openfeel-reviewer:
       provider: xxx
       ...
   roles:
@@ -717,12 +725,12 @@ models:
 - 报告语言：中文
 - 每次检查后将结果摘要写入 \`.openfeel/log/\`（仅首次发现关键问题时）
 `,
-    'model-config': `---
-name: model-config
-description: 查找和配置 Agent 模型。当 Agent 报 "Model not found" 或需要调整/新增 Agent 模型时使用。覆盖 opencode.jsonc 配置、模型名查找方法、多模态模型（Vision）特殊注意事项。
+    'openfeel-model-config': `---
+name: openfeel-model-config
+description: 查找和配置 Agent 模型。当 Agent 报 "Model not found" 或需要调整/新增 Agent 模型时使用。覆盖 opencode.jsonc 配置、模型名查找方法、多模态模型（openfeel-vision）特殊注意事项。
 ---
 
-# Skill: model-config
+# Skill: openfeel-model-config
 
 # Agent 模型查找与配置
 
@@ -731,7 +739,7 @@ description: 查找和配置 Agent 模型。当 Agent 报 "Model not found" 或
 - Agent 调用时报 \`Model not found: xxx\`
 - 需要为 Agent 更换或指定模型
 - 新增 Agent 后需要配置其模型
-- Vision / 多模态模型无法正常调用
+- openfeel-vision / 多模态模型无法正常调用
 
 ## 配置位置
 
@@ -740,8 +748,8 @@ Agent 模型配置在 **\`opencode.jsonc\`**（项目根目录）中：
 \`\`\`jsonc
 {
   "agent": {
-    "vision": {
-      "model": "qwen3-vl-plus"   // 模型名格式：provider/model-id 或 model-id
+    "openfeel-vision": {
+      "model": "deepseek/deepseek-flash"   // 模型名格式：provider/model-id 或 model-id
     }
   }
 }
@@ -749,6 +757,8 @@ Agent 模型配置在 **\`opencode.jsonc\`**（项目根目录）中：
 
 > ⚠️ **配置修改后必须重启 opencode 才能生效**。运行中的会话使用启动时加载的配置。
 
+> 💡 **推荐**：可用 \`openfeel model set/get/list --scope default|global|project\` 一键读写三层级模型（工具默认 / 全局 / 当前项目），无需手工定位文件。
+
 ## 查找可用模型名
 
 当收到 \`"Model not found: xxx. Did you mean: aaa, bbb?"\` 错误时：
@@ -758,17 +768,21 @@ Agent 模型配置在 **\`opencode.jsonc\`**（项目根目录）中：
 
 ## Agent 定义文件中的 model 字段
 
-\`.opencode/agents/<name>.md\` 中的 \`model\` 字段是声明性的（供 Agent 自述），**不直接控制平台模型分配**。实际的模型绑定由 \`opencode.jsonc\` 的 \`agent.<name>.model\` 控制。
+\`.opencode/agents/<name>.md\` 的 frontmatter \`model:\` 字段**是生效的，且优先于** \`opencode.jsonc\` 的 \`agent.<name>.model\`（stage-40 REV-1606 实测）。opencode 模型解析优先级链：
+
+\`\`\`
+项目 agents frontmatter > 全局 agents frontmatter > 项目 opencode.jsonc agent.model > 全局 opencode.jsonc agent.model > opencode 默认
+\`\`\`
 
-因此修改模型需要两步：
-1. 修改 \`opencode.jsonc\` 中的 \`agent.<name>.model\`
-2. （可选）同步修改 \`.opencode/agents/<name>.md\` 和模板文件 \`src/core/templates-data/agents/\` 中的 \`model\` 字段，保持一致性
+因此修改模型时以 frontmatter 为准（只改 jsonc 会被 frontmatter 遮蔽），建议两处同步保持一致：
+1. 修改 \`.opencode/agents/<name>.md\` 的 frontmatter \`model:\`（模板源 \`src/core/templates-data/opencode/agents/\` 同步）
+2. （可选，保持一致）同步修改 \`opencode.jsonc\` 的 \`agent.<name>.model\`
 
-## 多模态（Vision）模型特殊规则
+## 多模态（openfeel-vision）模型特殊规则
 
 - Feel 的主力模型（DeepSeek V4 Pro）不支持图片输入
-- 遇到图片输入时 Feel 会自动委托 Vision Agent
-- Vision Agent 需要配置多模态模型（如 \`qwen-vl-plus\`、\`qwen3-vl-plus\`）
+- 遇到图片输入时 Feel 会自动委托 openfeel-vision Agent
+- openfeel-vision Agent 需要配置多模态模型（现用 \`deepseek-flash\`，备选 \`qwen3-vl-plus\`）
 - 模型名不要随意添加前缀（如 \`alibaba/\`），以平台提示的可用名为准
 - **模型引用格式**：\`{auth.json中的key}/{模型ID}\`，不是 \`provider.name\` 也不是 \`provider.id\`
 - 读取 \`~/.local/share/opencode/auth.json\` 确认实际 provider key（常见：\`alibaba-cn\`、\`deepseek\`、\`zhipuai\`）
@@ -779,17 +793,17 @@ Agent 模型配置在 **\`opencode.jsonc\`**（项目根目录）中：
 | Agent | 模型类型 | 备注 |
 |-------|---------|------|
 | Feel（总统领） | 推理模型 | DeepSeek V4 Pro — 不支持多模态 |
-| Planner | 推理模型 | — |
-| Schemer | 推理模型 | — |
-| Executor | 快速模型 (Flash) | — |
-| Reviewer | 异种推理模型 (GLM) | — |
-| Feel Tester | 推理模型 | — |
+| openfeel-planner | 推理模型 | — |
+| openfeel-schemer | 推理模型 | — |
+| openfeel-executor | 快速模型 (Flash) | — |
+| openfeel-reviewer | 异种推理模型 (GLM) | — |
+| openfeel-feel-tester | 推理模型 | — |
 | 事务官 | 快速模型 (Flash) | — |
-| Vision | 多模态模型 | 需配 qwen3-vl-plus |
-| Archiver | 推理模型 | — |
+| openfeel-vision | 多模态模型 | 需配 deepseek-flash |
+| openfeel-archiver | 推理模型 | — |
 `,
-    'recover': `---
-name: recover
+    'openfeel-recover': `---
+name: openfeel-recover
 description: 跨会话上下文恢复，供 Agent 在会话启动时重建流水线状态。
 ---
 
@@ -809,8 +823,8 @@ description: 跨会话上下文恢复，供 Agent 在会话启动时重建流水
 
 恢复摘要：流水线状态 + 阻塞项 + 待处理任务列表
 `,
-    'roadmap': `---
-name: roadmap
+    'openfeel-roadmap': `---
+name: openfeel-roadmap
 description: 加载项目路线图，供 Agent 查看版本规划和里程碑。
 ---
 
@@ -830,8 +844,8 @@ description: 加载项目路线图，供 Agent 查看版本规划和里程碑。
 
 格式化路线图摘要：版本清单 + 各版本阶段进度
 `,
-    'search-kb': `---
-name: search-kb
+    'openfeel-search-kb': `---
+name: openfeel-search-kb
 description: 语义检索 .openfeel/kb/ 项目知识库。当精确匹配无结果或任务描述模糊时，通过向量相似度搜索语义相关的知识条目。支持图谱遍历返回关联条目。
 ---
 
@@ -950,16 +964,16 @@ description: 语义检索 .openfeel/kb/ 项目知识库。当精确匹配无结
 
 - 向量索引是缓存层，文件系统始终是 single source of truth。若检索结果与预期不符，检查索引是否过期（运行 \`--dry-run\` 查看变更文件）
 - 图谱链接亦是缓存层，Markdown 文件中 \`[[wikilink]]\` 是真实数据源；图谱可随时通过 \`python scripts/build_kb_index.py --graph\` 重建
-- 语义检索适合模糊查询和探索性搜索，精确关键词匹配优先使用 \`check-kb\`
-- 此技能是 \`check-kb\` 的回退方案——当 \`check-kb\` 精确匹配无结果时可自动调用
+- 语义检索适合模糊查询和探索性搜索，精确关键词匹配优先使用 \`openfeel-check-kb\`
+- 此技能是 \`openfeel-check-kb\` 的回退方案——当 \`openfeel-check-kb\` 精确匹配无结果时可自动调用
 - 图遍历返回的关联条目仅基于已建立的 wikilink 链接，若条目未引用或被引用其他条目，图谱中不会出现对应关联
 `,
-    'sync-status': `---
-name: sync-status
+    'openfeel-sync-status': `---
+name: openfeel-sync-status
 description: 聚合所有成员的任务进度视图，供任意 Agent 快速了解项目整体协作状态。
 ---
 
-# Skill: sync-status
+# Skill: openfeel-sync-status
 
 # 聚合任务进度
 
@@ -1022,11 +1036,10 @@ description: 聚合所有成员的任务进度视图，供任意 Agent 快速了
 
 格式化后的 Markdown 进度摘要，不含文件修改。
 
-Base directory for this skill: file:///C:/Code/AI/AI_Prompt/.kilo/skills/sync-status
 `,
-    'update-stage-status': `---
-name: update-stage-status
-description: 标准化更新 .openfeel/plan/{stage}/status.md 的子计划状态、责任 Agent 和状态记录，避免各 Agent 随意改写状态文件。适用于自动闭环和人工流程中的阶段状态变更。
+    'openfeel-update-stage-status': `---
+name: openfeel-update-stage-status
+description: 标准化更新 .openfeel/plan/{series}/{stage}/status.md 的子计划状态、责任 Agent 和状态记录，避免各 Agent 随意改写状态文件。适用于自动闭环和人工流程中的阶段状态变更。
 ---
 
 # 更新子计划状态
@@ -1034,6 +1047,7 @@ description: 标准化更新 .openfeel/plan/{stage}/status.md 的子计划状态
 ## 输入
 
 - 计划阶段名 \`{stage}\`
+- 阶段 ID \`{stage}\` 可为完整 \`vX.Y.Z.W-stage-NN\` 或短名 \`stage-NN\`，对应目录 \`plan/{series}/stage-NN/\`（\`{series}\` = 主版本系列，如 \`v1\`；短名默认 \`v1\`）
 - 新状态 \`{status}\`
 - 当前责任 Agent \`{current_agent}\`
 - 上一责任 Agent \`{previous_agent}\`
@@ -1058,7 +1072,7 @@ description: 标准化更新 .openfeel/plan/{stage}/status.md 的子计划状态
 
 ### 1. 读取状态文件
 
-读取 \`.openfeel/plan/{stage}/status.md\`。
+读取 \`.openfeel/plan/{series}/{stage}/status.md\`。
 
 若文件不存在且当前 Agent 为 Architect：
   1. 从 \`.openfeel/config.yaml\` \`defaults\` 读取 \`execution_mode\`、\`auto_advance\` 作为初始值
@@ -1122,10 +1136,10 @@ planned | ready_for_code | coding | ready_for_review | review_failed | review_pa
 
 ### 6. 合并状态处理
 
-当子计划状态变为 \`done\` 或 \`review_passed\`（且 Reviewer 验收完毕）时，根据 \`.openfeel/config.yaml\` 中的 \`merge_mode\` 决定合并行为：
+当子计划状态变为 \`done\` 或 \`review_passed\`（且 openfeel-reviewer 验收完毕）时，根据 \`.openfeel/config.yaml\` 中的 \`merge_mode\` 决定合并行为：
 
 - **\`merge_mode=auto\`**：
-  1. 将 \`合并状态\` 更新为 \`merged\`（实际合并由 Executor 执行 git 操作，Skill 仅更新状态字段）
+  1. 将 \`合并状态\` 更新为 \`merged\`（实际合并由 openfeel-executor 执行 git 操作，Skill 仅更新状态字段）
   2. 将 \`合并状态\` 更新为 \`cleaned\`
   3. 在状态记录中注明"自动合并"
 - **\`merge_mode=manual\`**：
@@ -1143,8 +1157,8 @@ planned | ready_for_code | coding | ready_for_review | review_failed | review_pa
 - 自动推进：保持 {enabled/disabled}
 \`\`\`
 `,
-    'wizard': `---
-name: wizard
+    'openfeel-wizard': `---
+name: openfeel-wizard
 description: 交互式流水线向导，供 Agent 在终端中逐步推进流水线阶段。
 ---
 
@@ -1168,301 +1182,97 @@ description: 交互式流水线向导，供 Agent 在终端中逐步推进流水
 `,
 };
 // AUTO-GENERATED-END: SKILL_DEFINITIONS
-// ─── 新增的 Skill 名称列表 ─────────────────────────────────────────
-const NEW_SKILL_NAMES = [
-    'bug-acceptance',
-    'check-kb',
-    'get-bugs',
-    'get-stage-status',
-    'model-check',
-    'search-kb',
-    'sync-status',
-    'update-stage-status',
-];
 // ─── 辅助函数 ──────────────────────────────────────────────────────
+/** 写全文时的受管内容组合：frontmatter 序列化 + 正文标记包裹 */
+function composeManagedContent(content, type) {
+    const split = type === 'markdown' ? splitFrontmatter(content) : null;
+    if (split) {
+        return serializeFrontmatter(split.frontmatter) + wrapRegion(split.body, type);
+    }
+    return wrapRegion(content, type);
+}
 /**
- * 带冲突检测的写入函数（替代原 writeIfChanged）
- *
- * 三态逻辑：
- *  - 文件不存在 → created
- *  - 文件已存在 + hash 匹配 update_state 中记录 → 安全覆盖 → updated
- *  - 文件已存在 + hash 不匹配 → 拒绝覆盖 → conflicts
- *  - 文件已存在 + 不在 update_state 管理中 → 安全覆盖 → updated（降级）
- *  - 文件已存在 + update_state 不存在或损坏 → 安全覆盖 → updated（降级为旧行为）
- *
- * REV-001：此函数仅负责分类（created/updated/skipped/conflicts），
- * hash 的实际更新在 updateProject() 末尾统一处理，
- * 确保"冲突路径非冲突文件 hash 同步更新"。
+ * 受管文件写入（控制区优先 + hash 兜底 三态）。
+ * 分派依据 detectFileType；jsonc 不走本函数（调用方走深度合并）。
+ * target 供 update_infos 路径记录：全局资产 { isGlobal: true }，项目资产 { isGlobal: false, projectRoot }。
  */
-function writeWithMergeDetection(filePath, content, relativePath, updateState, created, updated, skipped, conflicts) {
+function writeManagedFile(filePath, content, stateKey, updateState, target) {
+    const type = detectFileType(filePath);
+    if (type === null || type === 'jsonc') {
+        // 无策略 / JSONC：不应到达（jsonc 由 updateProject 单独走深度合并）
+        throw new Error(`writeManagedFile: 不支持的类型 ${filePath}`);
+    }
+    // 拆 incoming 的 frontmatter + 正文（gitignore 无 frontmatter，body=content）
+    const incomingSplit = type === 'markdown' ? splitFrontmatter(content) : null;
+    const incomingFm = incomingSplit?.frontmatter ?? null;
+    const incomingBody = incomingSplit?.body ?? content;
+    // 不存在 → created（写全文：frontmatter + 标记包裹正文）
     if (!existsSync(filePath)) {
-        // 文件不存在 → 新建
-        mkdirSync(dirname(filePath), { recursive: true });
-        writeFileSync(filePath, content, 'utf-8');
-        created.push(relativePath);
-        return;
+        atomicWriteFileSync(filePath, composeManagedContent(content, type));
+        return 'created';
     }
     const existing = readFileSync(filePath, 'utf-8');
-    // 内容相同 → skip（快速路径：全文比对，避免 hash 计算）
-    if (existing === content) {
-        skipped.push(relativePath);
-        return;
-    }
-    // 检查 update_state 中是否有该文件的记录
-    const fileState = updateState?.files[relativePath];
-    if (fileState) {
-        // 有记录 → 比对 hash
-        const currentHash = hashContent(existing);
-        if (currentHash === fileState.hash) {
-            // hash 一致 → 用户未修改 → 安全覆盖
-            writeFileSync(filePath, content, 'utf-8');
-            updated.push(relativePath);
-            return;
+    const existingSplit = type === 'markdown' ? splitFrontmatter(existing) : null;
+    const existingFm = existingSplit?.frontmatter ?? null;
+    const existingBody = existingSplit?.body ?? existing;
+    const region = parseRegion(existingBody, type);
+    if (region.status === 'ok') {
+        // 含标记：frontmatter 合并 + 正文区内替换，全文比对（REV-901 skip 判定）
+        // incoming 无 frontmatter（如 core.md/AGENTS.md 模板）时保留用户已有 frontmatter，避免写入丢失（REV-1101）
+        const newFm = existingFm && incomingFm ? mergeFrontmatter(existingFm, incomingFm) : (existingFm ?? incomingFm);
+        const newBody = replaceRegion(existingBody, incomingBody, type);
+        const newContent = newFm ? serializeFrontmatter(newFm) + newBody : newBody;
+        if (newContent === normalize(existing)) {
+            return 'skipped';
         }
-        // hash 不一致 → 用户已修改 → 冲突！
-        conflicts.push(relativePath);
-        return;
+        atomicWriteFileSync(filePath, newContent);
+        return 'updated';
     }
-    // 无记录（降级路径：update_state 损坏或旧版本）→ 安全覆盖
-    writeFileSync(filePath, content, 'utf-8');
-    updated.push(relativePath);
-}
-/**
- * 解析 JSONC 文本为 JavaScript 对象
- * 先规范化换行符，再去除行注释（跳过字符串内部），最后解析
- */
-function parseJsonc(text) {
-    // 去除 \r 控制字符（避免 Windows CRLF 导致 JSON 解析报 "bad control character"）
-    const normalized = text.replace(/\r/g, '');
-    // 逐字符处理，去除行注释（跳过字符串内部，避免匹配到 https:// 等 URL 中的 //）
-    let result = '';
-    let inString = false;
-    let inEscape = false;
-    let i = 0;
-    while (i < normalized.length) {
-        const ch = normalized[i];
-        const next = normalized[i + 1];
-        // 处理转义字符
-        if (inEscape) {
-            result += ch;
-            inEscape = false;
-            i++;
-            continue;
-        }
-        if (ch === '\\' && inString) {
-            result += ch;
-            inEscape = true;
-            i++;
-            continue;
-        }
-        // 字符串边界
-        if (ch === '"') {
-            inString = !inString;
-            result += ch;
-            i++;
-            continue;
+    if (region.status === 'none') {
+        // 无标记：hash 兜底（N3）
+        const fileState = updateState?.files[stateKey];
+        if (fileState && hashContent(existing) === fileState.hash) {
+            // adopt：存量框架文件未改 → 直接写带标记的新框架内容（等价 created 记为 updated）
+            atomicWriteFileSync(filePath, composeManagedContent(content, type));
+            return 'updated';
         }
-        // 行注释：不在字符串内时遇到 //
-        if (!inString && ch === '/' && next === '/') {
-            // 跳过直到行尾
-            i += 2; // 跳过 //
-            while (i < normalized.length && normalized[i] !== '\n') {
-                i++;
-            }
-            // 保留换行符
-            if (i < normalized.length && normalized[i] === '\n') {
-                result += '\n';
-                i++;
-            }
-            continue;
-        }
-        result += ch;
-        i++;
-    }
-    return JSON.parse(result);
-}
-/**
- * 获取 opencode.jsonc 更新后的完整内容
- * 读取现有文件（若存在），合并更新后生成新的 JSONC 文本
- */
-function buildUpdatedJsonc(projectPath) {
-    const jsoncPath = resolve(projectPath, 'opencode.jsonc');
-    let jsoncObj;
-    let rawContent;
-    if (existsSync(jsoncPath)) {
-        // 已有文件 → 解析并合并，保留原始字符串用于后续补丁式更新
-        rawContent = readFileSync(jsoncPath, 'utf-8');
-        jsoncObj = parseJsonc(rawContent);
-    }
-    else {
-        // 新文件 → 基础结构
-        jsoncObj = {
-            $schema: 'https://opencode.openfeel/config.json',
-            default_agent: 'feel',
-            instructions: ['AGENTS.md', '.opencode/instructions/core.md'],
-            skills: {},
-        };
-    }
-    // 更新 default_agent
-    jsoncObj.default_agent = 'feel';
-    // 确保 instructions 存在
-    if (!jsoncObj.instructions) {
-        jsoncObj.instructions = ['AGENTS.md', '.opencode/instructions/core.md'];
-    }
-    // 合并 skills：保留原有 skill，添加新的 /opfx:* skill
-    const skills = jsoncObj.skills || {};
-    for (const name of NEW_SKILL_NAMES) {
-        skills[name] = `.opencode/skills/${name}`;
+        // 追加受管区（标记包裹正文，不触碰 frontmatter），并记录待会话启动复核
+        const appendedRegion = wrapRegion(incomingBody, type);
+        const sep = existing.endsWith('\n') ? '' : '\n';
+        atomicWriteFileSync(filePath, `${existing}${sep}${appendedRegion}`);
+        appendUpdateInfo('appended', target.isGlobal ? { absolutePath: filePath } : { projectRoot: target.projectRoot, relativePath: stateKey });
+        return 'appended';
     }
-    jsoncObj.skills = skills;
-    // 格式化为 JSONC 输出：若有原始内容则基于它做补丁式替换，否则从头构建
-    return formatJsonc(jsoncObj, rawContent);
+    // malformed（>1 对 / 不成对）：不追加、不写盘，仅记录异常条目待人工修复标记；
+    // 修复后下次 update 走 ok（区内替换）/ none（hash 兜底）正常路径，杜绝重复追加死循环（REV-1001 修订）
+    appendUpdateInfo('anomaly', target.isGlobal ? { absolutePath: filePath } : { projectRoot: target.projectRoot, relativePath: stateKey });
+    return 'skipped';
 }
 /**
- * 将对象格式化为美观的 JSONC 字符串
- * 若提供了 originalContent，基于原始字符串做补丁式替换，
- * 仅更新 default_agent 和 skills，其余字段（含注释和未识别字段）原样保留。
+ * 写单个全局资产文件（REV-1205 最小侵入抽取，供 migrate 复用）。
+ * 等价 writeManagedFile(filePath, content, filePath, state, { isGlobal: true })，
+ * 即 stateKey = 绝对路径、target 为全局资产。
+ * @returns 动作分类，供调用方报告。
  */
-function formatJsonc(obj, originalContent) {
-    // 有原始内容 → 补丁模式：仅替换需要更新的字段，保留注释和未知字段
-    if (originalContent) {
-        let result = originalContent;
-        // 替换 "default_agent" 的值
-        result = result.replace(/("default_agent"\s*:\s*)("[^"]*")/, `$1"${obj.default_agent}"`);
-        // 替换 "skills" 块
-        const skills = obj.skills;
-        result = replaceSkillsFieldInJsonc(result, skills);
-        return result;
-    }
-    // 无原始内容 → 从头构建（新文件场景）
-    return buildJsoncFromObject(obj);
+export function deployGlobalAsset(filePath, content, state) {
+    return writeManagedFile(filePath, content, filePath, state, { isGlobal: true });
 }
-/**
- * 在 JSONC 原始字符串中查找并替换 "skills" 字段的整个对象块
- * 使用括号计数来正确处理嵌套对象，并自动处理末尾逗号
- */
-function replaceSkillsFieldInJsonc(content, skills) {
-    // 查找 "skills" 键及冒号
-    const keyRegex = /("skills"\s*:\s*)\{/;
-    const keyMatch = content.match(keyRegex);
-    if (!keyMatch || keyMatch.index === undefined) {
-        // skills 字段不存在于原始文件中，不需要替换
-        return content;
-    }
-    const keyStart = keyMatch.index;
-    const openBraceIdx = keyStart + keyMatch[0].length - 1; // { 的位置
-    // 找到匹配的 }，处理字符串内的大括号
-    let depth = 1;
-    let closeBraceIdx = openBraceIdx;
-    let inString = false;
-    let inEscape = false;
-    for (let i = openBraceIdx + 1; i < content.length && depth > 0; i++) {
-        const ch = content[i];
-        if (inEscape) {
-            inEscape = false;
-            continue;
-        }
-        if (ch === '\\' && inString) {
-            inEscape = true;
-            continue;
-        }
-        if (ch === '"') {
-            inString = !inString;
-            continue;
-        }
-        if (!inString) {
-            if (ch === '{') {
-                depth++;
-            }
-            else if (ch === '}') {
-                depth--;
-            }
-        }
-        if (depth === 0) {
-            closeBraceIdx = i;
+/** 将 writeManagedFile 的动作分发到对应结果数组 */
+function pushAction(action, stateKey, created, updated, skipped, appended) {
+    switch (action) {
+        case 'created':
+            created.push(stateKey);
+            break;
+        case 'updated':
+            updated.push(stateKey);
+            break;
+        case 'skipped':
+            skipped.push(stateKey);
+            break;
+        case 'appended':
+            appended.push(stateKey);
             break;
-        }
-    }
-    // 检查 } 后面是否有逗号：若 } 后紧跟（仅跳过空白）有逗号，则将逗号及其后空白纳入 endIdx
-    let endIdx = closeBraceIdx + 1;
-    let scanIdx = endIdx;
-    while (scanIdx < content.length && /[ \t]/.test(content[scanIdx])) {
-        scanIdx++;
-    }
-    if (scanIdx < content.length && content[scanIdx] === ',') {
-        scanIdx++; // 跳过逗号
-        // 跳过逗号后的空白（包括换行）
-        while (scanIdx < content.length && /[\s\n\r]/.test(content[scanIdx])) {
-            scanIdx++;
-        }
-        endIdx = scanIdx;
-    }
-    // 确定替换后是否需要末尾逗号：检查 skills 之后是否还有其他顶层字段
-    let hasMoreFields = false;
-    if (endIdx < content.length) {
-        // 从 endIdx 找到内容末尾前最后一个 }（根对象闭合）
-        const remaining = content.slice(endIdx);
-        const rootCloseIdx = remaining.lastIndexOf('}');
-        if (rootCloseIdx > 0) {
-            const between = remaining.slice(0, rootCloseIdx);
-            hasMoreFields = /[^\s]/.test(between);
-        }
-    }
-    // 构建新的 skills 块内容
-    const skillEntries = Object.entries(skills);
-    const skillLines = skillEntries.map(([key, value], idx) => {
-        const comma = idx < skillEntries.length - 1 ? ',' : '';
-        return `    "${key}": "${value}"${comma}`;
-    });
-    const blockContent = skillLines.join('\n');
-    const newBlock = `"skills": {\n${blockContent}\n  }${hasMoreFields ? ',' : ''}`;
-    return content.slice(0, keyStart) + newBlock + content.slice(endIdx);
-}
-/**
- * 从对象从头构建 JSONC（无原始内容时的回退路径）
- */
-function buildJsoncFromObject(obj) {
-    const skills = obj.skills;
-    // 构建 skills 条目行
-    const skillEntries = Object.entries(skills);
-    const skillsLines = skillEntries.map(([key, value], index) => {
-        const comma = index < skillEntries.length - 1 ? ',' : '';
-        return `    "${key}": "${value}"${comma}`;
-    });
-    const instructions = obj.instructions;
-    const instructionLines = instructions.map((inst, index) => {
-        const comma = index < instructions.length - 1 ? ',' : '';
-        return `    "${inst}"${comma}`;
-    });
-    // 构建完整 JSONC
-    const hasExperimental = typeof obj.experimental === 'object' && obj.experimental !== null;
-    const lines = [
-        '{',
-        '  "$schema": "https://opencode.openfeel/config.json",',
-        `  "default_agent": "${obj.default_agent}",`,
-        '  "instructions": [',
-        ...instructionLines,
-        '  ],',
-        '  "skills": {',
-        ...skillsLines,
-        hasExperimental ? '  },' : '  }',
-    ];
-    // 如果有 experimental 字段，保留它
-    if (hasExperimental) {
-        const exp = obj.experimental;
-        const expEntries = Object.entries(exp);
-        const expLines = expEntries.map(([key, value], index) => {
-            const comma = index < expEntries.length - 1 ? ',' : '';
-            const val = typeof value === 'string' ? `"${value}"` : String(value);
-            return `    "${key}": ${val}${comma}`;
-        });
-        lines.push('  "experimental": {');
-        lines.push(...expLines);
-        lines.push('  }');
     }
-    lines.push('}');
-    lines.push(''); // 末尾换行符
-    return lines.join('\n');
 }
 // ─── 主函数 ────────────────────────────────────────────────────────
 /**
@@ -1476,22 +1286,33 @@ export function updateProject(projectPath, selectedTools = ["opencode"], lang =
     const created = [];
     const updated = [];
     const skipped = [];
-    // ── 增量更新：加载 update_state.json ──
+    const appended = [];
+    // ── 增量更新：加载项目 state（AGENTS.md / 项目 opencode.jsonc）与全局 state（框架资产）──
     const state = loadUpdateState(projectPath);
+    const globalState = loadGlobalUpdateState();
     const conflicts = [];
-    const agentsDir = resolve(projectPath, '.opencode', 'agents');
-    const skillsDir = resolve(projectPath, '.opencode', 'skills');
-    // 确保目标目录存在
-    mkdirSync(agentsDir, { recursive: true });
-    mkdirSync(skillsDir, { recursive: true });
     // 过滤：仅处理选中的工具
     if (!selectedTools.includes('opencode')) {
-        return { created: [], updated: [], skipped: [], conflicts: [] };
+        return { created: [], updated: [], skipped: [], conflicts: [], appended: [] };
     }
+    // N8：检测项目内遗留 .opencode/{agents,skills,instructions}，只提示不迁移
+    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 提供）迁移。`);
+    }
+    // 全局部署目标（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(agentsDir) && readdirSync(agentsDir).length > 0;
+        agentsDirHasContent = existsSync(projectLegacyAgentsDir) && readdirSync(projectLegacyAgentsDir).length > 0;
     }
     catch {
         agentsDirHasContent = false;
@@ -1499,18 +1320,18 @@ export function updateProject(projectPath, selectedTools = ["opencode"], lang =
     const agentsMdPath = resolve(projectPath, 'AGENTS.md');
     const agentsMdExists = existsSync(agentsMdPath);
     if (!agentsDirHasContent && !agentsMdExists) {
-        // 情况 1：首次部署 → 使用全局默认语言部署 AGENTS.md
+        // 情况 1：首次部署 → 使用全局默认语言部署 AGENTS.md（受管区标记包裹）
         const globalConfig = getGlobalConfig();
         const deployLang = lang ?? globalConfig.lang ?? 'zh-CN';
         const agentsMdContent = loadTemplate(deployLang, 'agents-md');
-        writeFileSync(agentsMdPath, agentsMdContent, 'utf-8');
+        atomicWriteFileSync(agentsMdPath, composeManagedContent(agentsMdContent, 'markdown'));
         created.push('AGENTS.md');
     }
     else if (!agentsMdExists && options?.lang) {
         // 情况 2b：已有 agents 目录但 AGENTS.md 被手动删除 + --lang 指定
-        // → 用指定语言重新创建 AGENTS.md
+        // → 用指定语言重新创建 AGENTS.md（受管区标记包裹）
         const agentsMdContent = loadTemplate(options.lang, 'agents-md');
-        writeFileSync(agentsMdPath, agentsMdContent, 'utf-8');
+        atomicWriteFileSync(agentsMdPath, composeManagedContent(agentsMdContent, 'markdown'));
         created.push('AGENTS.md');
     }
     else if (agentsMdExists && options?.lang) {
@@ -1520,9 +1341,9 @@ export function updateProject(projectPath, selectedTools = ["opencode"], lang =
         if (requestedLang !== projectLang) {
             // 语言不同 → 提示确认
             if (options?.force) {
-                // --force → 跳过确认，直接覆盖
+                // --force → 跳过确认，直接覆盖（受管区标记包裹）
                 const agentsMdContent = loadTemplate(requestedLang, 'agents-md');
-                writeFileSync(agentsMdPath, agentsMdContent, 'utf-8');
+                atomicWriteFileSync(agentsMdPath, composeManagedContent(agentsMdContent, 'markdown'));
                 updated.push('AGENTS.md');
             }
             else if (options?.interactive) {
@@ -1537,29 +1358,17 @@ export function updateProject(projectPath, selectedTools = ["opencode"], lang =
             }
         }
         else {
-            // 语言相同 → 比较内容，模板更新时传播部署
+            // 语言相同 → 走受管文件三态（含标记区内替换 / 无标记 hash 兜底 / 追加）
             const templateContent = loadTemplate(requestedLang, 'agents-md');
-            const existingContent = readFileSync(agentsMdPath, 'utf-8');
-            if (existingContent !== templateContent) {
-                writeFileSync(agentsMdPath, templateContent, 'utf-8');
-                updated.push('AGENTS.md');
-            }
-            else {
-                skipped.push('AGENTS.md (language unchanged)');
-            }
+            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 参数 → 比较内容，模板更新时传播部署
+        // 情况 3：已有项目 + 无 --lang 参数 → 走受管文件三态
         const templateContent = loadTemplate(lang, 'agents-md');
-        const existingContent = readFileSync(agentsMdPath, 'utf-8');
-        if (existingContent !== templateContent) {
-            writeFileSync(agentsMdPath, templateContent, 'utf-8');
-            updated.push('AGENTS.md');
-        }
-        else {
-            skipped.push('AGENTS.md (use existing)');
-        }
+        const action = writeManagedFile(agentsMdPath, templateContent, 'AGENTS.md', state, { isGlobal: false, projectRoot: projectPath });
+        pushAction(action, 'AGENTS.md', created, updated, skipped, appended);
     }
     // 记录项目语言映射到全局配置
     // 使用 options?.lang（用户通过 --lang 显式指定的语言）优先，
@@ -1570,76 +1379,123 @@ export function updateProject(projectPath, selectedTools = ["opencode"], lang =
     catch {
         // 记录失败不影响主流程
     }
-    // 0. 生成 instructions/core.md（适配器层核心指令，与 init 的核心层分离）
-    const instructionsDir = resolve(projectPath, '.opencode', 'instructions');
-    mkdirSync(instructionsDir, { recursive: true });
-    const coreInstructionsPath = join(instructionsDir, 'core.md');
+    // 全局 state 可写实例：首次 null → 降级重建（后续全量写入全局资产，防静默不部署）
+    const newGlobalState = globalState ?? createGlobalUpdateState({});
+    // 0. 生成全局框架约束 core.md（~/.config/opencode/openfeel/core.md）
+    const coreInstructionsPath = getGlobalCoreMdPath();
     const coreContent = loadTemplate(lang, 'core-instructions');
-    writeWithMergeDetection(coreInstructionsPath, coreContent, '.opencode/instructions/core.md', state, created, updated, skipped, conflicts);
-    // 1. 生成 Agent 定义文件（从 template-loader 加载模板，按语言选择）
+    {
+        const action = deployGlobalAsset(coreInstructionsPath, coreContent, newGlobalState);
+        pushAction(action, coreInstructionsPath, 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 relPath = `.opencode/agents/${name}.md`;
-        writeWithMergeDetection(filePath, content, relPath, state, created, updated, skipped, conflicts);
+        const action = deployGlobalAsset(filePath, content, newGlobalState);
+        pushAction(action, filePath, created, updated, skipped, appended);
     }
-    // 2. 生成 Skill 定义文件（每个 Skill 一个子目录，包含 SKILL.md）
+    // 2. 生成 Skill 定义文件到全局 skills 目录（每个 Skill 一个子目录，包含 SKILL.md）
     for (const [name, content] of Object.entries(SKILL_DEFINITIONS)) {
         const skillSubDir = join(skillsDir, name);
         mkdirSync(skillSubDir, { recursive: true });
         const filePath = join(skillSubDir, 'SKILL.md');
-        const relPath = `.opencode/skills/${name}/SKILL.md`;
-        writeWithMergeDetection(filePath, content, relPath, state, created, updated, skipped, conflicts);
+        const action = deployGlobalAsset(filePath, content, newGlobalState);
+        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);
+        }
+        catch (err) {
+            console.warn(`[update] 全局 opencode.jsonc 解析失败（可能含块注释），跳过合并保留原文件: ${err.message}`);
+            merged = current;
+        }
+        atomicWriteFileSync(globalJsoncPath, merged);
+        return merged;
+    });
+    updateFileHash(newGlobalState, globalJsoncPath, globalJsoncNew);
+    // 4. 项目 opencode.jsonc：不存在则写最小 { $schema }；已存在则保留（旧非法字段清理属 stage-39）
+    const projectJsoncPath = resolve(projectPath, 'opencode.jsonc');
+    if (!existsSync(projectJsoncPath)) {
+        atomicWriteFileSync(projectJsoncPath, JSON.stringify(buildProjectOpencodeJsoncObj(), null, 2) + '\n');
+        created.push('opencode.jsonc');
+    }
+    else {
+        skipped.push('opencode.jsonc (use existing)');
     }
-    // 3. 更新 opencode.jsonc
-    const jsoncPath = resolve(projectPath, 'opencode.jsonc');
-    const newContent = buildUpdatedJsonc(projectPath);
-    const relJsoncPath = 'opencode.jsonc';
-    writeWithMergeDetection(jsoncPath, newContent, relJsoncPath, state, created, updated, skipped, conflicts);
-    // 重启提醒（仅在 opencode agent 配置更新时，且为交互模式）
-    if (updated.some(f => f.startsWith('.opencode/agents/')) && process.stdout.isTTY) {
-        const lang = getCliLang(projectPath);
-        console.log(lang === 'en'
-            ? 'opencode agent configuration updated. Please restart opencode to load the new configuration.'
-            : 'opencode agent 配置已更新，请重启 opencode 以加载新配置。');
+    // 重启提醒（仅在 opencode 全局 agent 配置更新时，且为交互模式）
+    if (updated.some((f) => f.startsWith(getGlobalAgentsDir())) && process.stdout.isTTY) {
+        const reminderLang = getCliLang(projectPath);
+        console.log(reminderLang === 'en'
+            ? 'opencode global configuration updated. Please restart opencode to load the new configuration.'
+            : 'opencode 全局配置已更新，请重启 opencode 以加载新配置。');
     }
     // ── 写入冲突标记文件 ──
     if (conflicts.length > 0) {
         const openfeelVersion = getOpenfeelVersion();
-        for (const relPath of conflicts) {
-            const absPath = resolve(projectPath, relPath);
-            const currentContent = existsSync(absPath)
-                ? readFileSync(absPath, 'utf-8')
-                : '';
-            // 获取 incoming 内容：从模板/构建产物中重新读取
-            // 注意：由于 writeWithMergeDetection 未实际写入，需单独获取 incoming 内容
-            const incomingContent = getIncomingContent(projectPath, relPath, lang);
-            writeConflictFile(projectPath, relPath, currentContent, incomingContent, openfeelVersion);
+        for (const conflictPath of conflicts) {
+            // 全局冲突（绝对路径）写 ~/.openfeel/update_conflicts/；项目冲突写项目 .openfeel/update_conflicts/
+            if (isAbsolute(conflictPath)) {
+                const currentContent = existsSync(conflictPath) ? readFileSync(conflictPath, 'utf-8') : '';
+                const incomingContent = getIncomingContent(conflictPath, lang);
+                const relFromGlobal = relative(getOpencodeGlobalDir(), conflictPath);
+                // 全局冲突根目录 ~/.openfeel/update_conflicts/（与项目 .openfeel/update_conflicts/ 对称）
+                const globalConflictsBase = resolve(dirname(getGlobalUpdateStatePath()), 'update_conflicts');
+                writeConflictFile(projectPath, relFromGlobal, currentContent, incomingContent, openfeelVersion, globalConflictsBase);
+            }
+            else {
+                const absPath = resolve(projectPath, conflictPath);
+                const currentContent = existsSync(absPath) ? readFileSync(absPath, 'utf-8') : '';
+                // 获取 incoming 内容：冲突未实际写入，需单独获取
+                const incomingContent = getIncomingContent(conflictPath, lang);
+                writeConflictFile(projectPath, conflictPath, currentContent, incomingContent, openfeelVersion);
+            }
         }
     }
-    // ── REV-001：统一更新 update_state.json ──
+    // ── REV-001：统一更新双 update_state.json ──
     // 规则：
     // 1. 无论有无冲突，所有 created/updated 文件的 hash 都必须更新到 state
     // 2. 有冲突时，额外标记冲突文件
     // 3. 首次 update（state === null）→ 创建新 state
     const newState = state ?? createUpdateState(projectPath, {});
-    // 更新所有非冲突文件的 hash（created 和 updated）
-    for (const relPath of [...created, ...updated]) {
-        const absPath = resolve(projectPath, relPath);
-        if (existsSync(absPath)) {
-            const content = readFileSync(absPath, 'utf-8');
-            updateFileHash(newState, relPath, content);
+    // 更新非冲突文件 hash：项目资产（相对路径）→ 项目 state；全局资产（绝对路径）→ 全局 state
+    // appended 追加后同样记录 clean + 新 hash（D38-1：追加即建区，下次走区内替换而非误判无记录）
+    for (const p of [...created, ...updated, ...appended]) {
+        if (isAbsolute(p)) {
+            if (existsSync(p)) {
+                updateFileHash(newGlobalState, p, readFileSync(p, 'utf-8'));
+            }
+        }
+        else {
+            const absPath = resolve(projectPath, p);
+            if (existsSync(absPath)) {
+                updateFileHash(newState, p, readFileSync(absPath, 'utf-8'));
+            }
         }
     }
-    // 标记冲突文件
-    for (const relPath of conflicts) {
-        markFileConflict(newState, relPath);
+    // 标记冲突文件（按绝对/相对路由到对应 state）
+    for (const p of conflicts) {
+        if (isAbsolute(p)) {
+            markFileConflict(newGlobalState, p);
+        }
+        else {
+            markFileConflict(newState, p);
+        }
     }
     // 更新时间戳
     newState.last_update = new Date().toISOString();
-    // 持久化
+    newGlobalState.last_update = new Date().toISOString();
+    // 持久化双 state
     saveUpdateState(projectPath, newState);
-    return { created, updated, skipped, conflicts };
+    saveGlobalUpdateState(newGlobalState);
+    return { created, updated, skipped, conflicts, appended };
 }
 /**
  * 写入冲突标记文件到 .openfeel/update_conflicts/{relativePath}
@@ -1647,10 +1503,11 @@ export function updateProject(projectPath, selectedTools = ["opencode"], lang =
  *
  * REV-006：update_conflicts/ 目录已加入 .gitignore，不纳入版本管理。
  */
-function writeConflictFile(projectPath, relativePath, currentContent, incomingContent, openfeelVersion) {
-    const conflictsBase = resolve(projectPath, '.openfeel', 'update_conflicts');
-    mkdirSync(conflictsBase, { recursive: true });
-    const conflictPath = resolve(conflictsBase, relativePath);
+function writeConflictFile(projectPath, relativePath, currentContent, incomingContent, openfeelVersion, conflictsBase) {
+    // 全局冲突传全局 base（~/.openfeel），项目冲突默认项目 .openfeel/update_conflicts
+    const base = conflictsBase ?? resolve(projectPath, '.openfeel', 'update_conflicts');
+    mkdirSync(base, { recursive: true });
+    const conflictPath = resolve(base, relativePath);
     mkdirSync(dirname(conflictPath), { recursive: true });
     const conflictContent = [
         `<<<<<<< CURRENT (用户修改版)`,
@@ -1659,39 +1516,37 @@ function writeConflictFile(projectPath, relativePath, currentContent, incomingCo
         incomingContent,
         `>>>>>>> INCOMING (openfeel v${openfeelVersion} 更新)`,
     ].join('\n');
-    writeFileSync(conflictPath, conflictContent, 'utf-8');
+    atomicWriteFileSync(conflictPath, conflictContent);
 }
 /**
- * 根据相对路径获取 incoming（openfeel 期望写入）内容
- * 与 updateProject() 中生成内容的逻辑一一对应：
- *  - .opencode/instructions/core.md → loadTemplate(lang, 'core-instructions')
- *  - .opencode/agents/{name}.md → loadAgentTemplate(lang, name)
- *  - .opencode/skills/{name}/SKILL.md → SKILL_DEFINITIONS[name]
- *  - opencode.jsonc → buildUpdatedJsonc(projectPath)
+ * 根据路径获取 incoming（openfeel 期望写入）内容
+ * relativePath 现为全局绝对路径（框架资产）或项目相对路径（AGENTS.md / opencode.jsonc）：
+ *  - getGlobalCoreMdPath() → loadTemplate(lang, 'core-instructions')
+ *  - getGlobalAgentsDir()/{name}.md → loadAgentTemplate(lang, name)
+ *  - getGlobalSkillsDir()/{name}/SKILL.md → SKILL_DEFINITIONS[name]
+ *  - opencode.jsonc → buildProjectOpencodeJsoncObj()
  *  - AGENTS.md → loadTemplate(lang, 'agents-md')
  */
-function getIncomingContent(projectPath, relativePath, lang) {
-    // instructions/core.md
-    if (relativePath === '.opencode/instructions/core.md') {
+function getIncomingContent(relativePath, lang) {
+    // 全局框架约束 core.md
+    if (relativePath === getGlobalCoreMdPath()) {
         return loadTemplate(lang, 'core-instructions');
     }
-    // Agent 定义文件
-    const agentMatch = relativePath.match(/^\.opencode\/agents\/(.+)\.md$/);
-    if (agentMatch) {
-        const name = agentMatch[1];
+    // 全局 agent：位于 getGlobalAgentsDir() 下的 {name}.md
+    if (relativePath.startsWith(getGlobalAgentsDir())) {
+        const name = basename(relativePath, '.md');
         return loadAgentTemplate(lang, name);
     }
-    // Skill 定义文件
-    const skillMatch = relativePath.match(/^\.opencode\/skills\/(.+)\/SKILL\.md$/);
-    if (skillMatch) {
-        const name = skillMatch[1];
+    // 全局 skill：位于 getGlobalSkillsDir() 下的 {name}/SKILL.md（跨平台 basename 匹配）
+    if (relativePath.startsWith(getGlobalSkillsDir()) && basename(relativePath) === 'SKILL.md') {
+        const name = basename(dirname(relativePath));
         return SKILL_DEFINITIONS[name] ?? '';
     }
-    // opencode.jsonc
+    // 项目 opencode.jsonc
     if (relativePath === 'opencode.jsonc') {
-        return buildUpdatedJsonc(projectPath);
+        return JSON.stringify(buildProjectOpencodeJsoncObj(), null, 2) + '\n';
     }
-    // AGENTS.md
+    // 项目 AGENTS.md
     if (relativePath === 'AGENTS.md') {
         return loadTemplate(lang, 'agents-md');
     }