docs: add workflow activation troubleshooting

Author: rockyshi1993

README.md

@@ -11,7 +11,7 @@ npm install -g devcodex
 devcodex --version
 ```
 
-安装或更新后，重新打开宿主的新会话即可开始使用。
+安装或更新后，先在目标项目或工作区完成下方初始化与状态检查，再完全退出并重新打开宿主的新会话。
 
 DevCodex 不替代业务框架、GitHub CI、安全审计或人工评审。它也不接管 Codex、Claude Code 等宿主原有的个人 Skill、项目指令或配置文件。
 
@@ -26,6 +26,7 @@ DevCodex 不替代业务框架、GitHub CI、安全审计或人工评审。它
 - [项目 Profile](#项目-profile)
 - [首次信任提示](#首次信任提示)
 - [常见任务怎么说](#常见任务怎么说)
+- [常见问题与排错](#常见问题与排错)
 - [更新](#更新)
 - [卸载](#卸载)
 - [运行态检查](#运行态检查)
@@ -303,6 +304,60 @@ DevCodex 会按任务意图选择流程和 Skill。普通使用者不需要手
 - “完成”不自动等于 commit、push 或发布；这些动作需要在当前请求中明确写出。
 - `@rocky` 只负责在已授权范围内自动推进，不会扩大删除、越界访问或发布权限。
 
+## 常见问题与排错
+
+### 安装最新版后，为什么没有需求概况、PC0~PC7 或 CP 流程？
+
+这通常不是版本缺少流程，而是以下某一层尚未就绪：npm 包、用户级宿主适配器、当前 workspace 运行态，或者宿主新会话加载。
+
+先进入真正要使用 DevCodex 的项目或 workspace 根目录，再检查状态：
+
+```bash
+cd <你的项目或 workspace 根目录>
+devcodex status
+```
+
+按输出处理：
+
+| `devcodex status` 输出 | 含义与处理 |
+|------------------------|------------|
+| Codex 显示 `adapter=not-ready` 或 `contract=failed` | 用户级 Codex 适配器未通过合同检查。完全退出 Codex Desktop 或 CLI 会话，然后执行下方的适配器刷新命令。 |
+| `.devcodex not initialized` 或 Profile `missing` | 只表示当前终端所在目录没有 workspace 运行态。先确认目录正确；只有该目录确实是目标项目或 workspace 根时才执行 `devcodex init`。 |
+| Codex 为 `adapter=ready; contract=passed`，且 `.devcodex present`、Profile `complete` | 安装与 workspace 已就绪。完全退出并重新打开宿主，在同一项目目录新建任务；不要继续使用修复前已经打开的旧任务。 |
+| `native=unverified` | 只表示对应宿主的原生 CLI 探针未验证。若你使用的是 Codex Desktop，且 adapter/contract 已通过，这不是工作流阻断。 |
+| workspace 显示 `host kernel not installed` | 当前版本的宿主入口安装在用户 HOME，不要求项目目录再保存一套宿主文件；只要上方用户级 adapter/contract 已通过，这不是故障。 |
+
+修复用户级适配器：
+
+```bash
+devcodex global-adapters apply
+devcodex status
+```
+
+初始化正确的项目或 workspace：
+
+```bash
+devcodex init
+devcodex status
+```
+
+`devcodex status` 只检查当前目录。若你在用户 HOME 中运行它，看到 `.devcodex not initialized` 或 Profile `missing`，并不能说明另一个项目目录未初始化；除非 HOME 本身就是目标 workspace，否则不要在那里执行 `devcodex init`。
+
+`devcodex update` 只刷新 workspace 运行态，不能替代 `devcodex global-adapters apply` 修复用户级适配器。Codex 会在每次新任务开始时构建一次指令链，因此适配器修复后必须新建任务，已打开的任务不会中途重新加载。参见 [OpenAI Codex 的 AGENTS.md 官方说明](https://learn.chatgpt.com/docs/agent-configuration/agents-md)。
+
+如果刷新后仍然失败，再运行：
+
+```bash
+devcodex doctor --json
+```
+
+Windows 使用 Scoop、NVM 或多套 Node.js 时，还应确认 `devcodex` 与 npm 全局目录属于同一套 Node.js：
+
+```powershell
+Get-Command devcodex
+npm root -g
+```
+
 ## 更新
 
 ```bash

changelogs/unreleased.md

@@ -5,6 +5,7 @@
 
 ## 当前未发布实现候选
 
+- **新电脑工作流未激活 FAQ 与防回归合同**：公共 README 新增“安装最新版后没有需求概况、PC0~PC7 或 CP 流程”的状态分流，区分用户级 adapter contract、当前 cwd 的 workspace/Profile、Codex 新任务指令加载、Desktop 可接受的 `native=unverified` 与 GlobalOnly 下非故障的 `host kernel not installed`；提供 `global-adapters apply`、`init`、`status`、`doctor --json` 及 Windows 多 Node 根核对命令。公共 README 合同和负向测试同步要求 FAQ 与适配器修复入口不可回退。
 - **v1.16.5 发布候选已归档**：SkillRoute 累计正文预算循环修复已进入 `changelogs/releases/v1.16.5.md`。新增 `SkillRouteBodyChargeLedgerV1`、`SkillRouteBudgetProjectionV1` 与结构化预算 recovery；commit/rebind 全计划预留，load_stage 首次交付原子计费，跨 generation/cache reopen 去重；预算不足、预留不足或账本不一致时 fail closed、零写入并投影 `nextCall=null` 的有限退役终态。在线发布审计另将维护者本地站点 Mermaid、DOMPurify 与 React Router 安全下限分别提升至 10.9.8、3.4.13 与 7.18.2，移除旧 RSC 临时例外并恢复零 advisory；npm 包资格验证同步修复 SkillRoute 测试、intent/registry 生成器与 closure owner 的 source/package 布局闭环，隔离安装包内完整七段路由链已通过；最终 tarball production S15、远端 CI、tag/Release、npm publish 与 fresh-install R7 仍待发布阶段完成。
 - **v1.16.4 发布候选已归档**：14 个审计与候选实机验证缺陷、8 项运行时/验证优化、截图所示 ContextRead/SkillRoute 三次无进展恢复修复，以及有界 MCP/宿主 I/O 与安全审计证据闭环已进入 `changelogs/releases/v1.16.4.md`；远端发布事实仍以 tag、npm registry 和最终回读为准。
 - **v1.16.3 已归档**：Profile 目标解析、memory 会话写入绑定、SkillRoute 不可执行旧路由退役、ContextRead 上一版本兼容、宿主运行态滚动升级、索引证据和治理台账完整性修复已进入 `changelogs/releases/v1.16.3.md`。

scripts/lib/canonical-consumer-contracts.js

@@ -51,6 +51,14 @@ const PUBLIC_README_REQUIRED_MARKERS = Object.freeze([
   'DevCodex 不扫描、复制、合并、覆盖或删除这些用户资产',
   '不替代业务框架、GitHub CI、安全审计或人工评审',
   '## 常见任务怎么说',
+  '## 常见问题与排错',
+  '安装最新版后，为什么没有需求概况、PC0~PC7 或 CP 流程？',
+  'devcodex status',
+  'devcodex global-adapters apply',
+  'adapter=not-ready',
+  'contract=failed',
+  'native=unverified',
+  'host kernel not installed',
   '只分析，不修改文件',
   '继续<任务名>任务',
   'push、tag、GitHub Release 和 npm publish',
@@ -59,6 +67,7 @@ const PUBLIC_README_REQUIRED_MARKERS = Object.freeze([
   '[为什么需要 DevCodex？](#为什么需要-devcodex)',
   '[5 分钟开始](#5-分钟开始)',
   '[常见任务怎么说](#常见任务怎么说)',
+  '[常见问题与排错](#常见问题与排错)',
   '[添加自己的 Skill](#添加自己的-skill)',
   '[许可证](#许可证)'
 ])

scripts/test-client-contracts.js

@@ -39,6 +39,14 @@ const missingTaskTutorial = publicReadme.replace('## 常见任务怎么说', '##
 if (evaluatePublicReadmeContract(missingTaskTutorial).valid) {
   failures.push('public README without the common-task tutorial must fail its contract')
 }
+const missingTroubleshooting = publicReadme.replace('## 常见问题与排错', '## 排错')
+if (evaluatePublicReadmeContract(missingTroubleshooting).valid) {
+  failures.push('public README without the troubleshooting entry must fail its contract')
+}
+const missingAdapterRepair = publicReadme.replaceAll('devcodex global-adapters apply', '')
+if (evaluatePublicReadmeContract(missingAdapterRepair).valid) {
+  failures.push('public README without the global adapter repair command must fail its contract')
+}
 
 const readAbsolute = createCanonicalAwareReader(ROOT, file => fs.readFileSync(file, 'utf8'))
 const read = file => readAbsolute(path.join(ROOT, file))