helloagents 3.0.12 → 3.0.16-beta.1

package/README_CN.md

@@ -8,7 +8,7 @@
 
 **面向 AI 编码 CLI 的工作流层：技能、知识库、交付检查、更安全的配置写入，以及可恢复的执行流程。**
 
-[![Version](https://img.shields.io/badge/version-3.0.12-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.16-orange.svg)](./package.json)
 [![npm](https://img.shields.io/npm/v/helloagents.svg)](https://www.npmjs.com/package/helloagents)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](./package.json)
 [![Skills](https://img.shields.io/badge/skills-14-6366f1.svg)](./skills)
@@ -30,7 +30,7 @@
 ## 目录
 
 - [HelloAGENTS 做什么](#helloagents-做什么)
-- [相对 v3.0.11 的真实变化](#相对-v3011-的真实变化)
+- [相对 v3.0.15 的真实变化](#相对-v3015-的真实变化)
 - [核心功能](#核心功能)
 - [快速开始](#快速开始)
 - [CLI 管理](#cli-管理)
@@ -77,13 +77,17 @@ HelloAGENTS 叠加在 Claude Code、Gemini CLI 和 Codex CLI 之上，帮助模
 | 完成态模糊 | 自然语言说“完成” | 按状态、证据和验证结果交付 |
 | 配置容易漂移 | CLI 文件可能不一致 | 安装、更新、清理和 doctor 会检查受管文件 |
 
-## 相对 v3.0.11 的真实变化
+## 相对 v3.0.15 的真实变化
 
-下面是当前 `v3.0.12` 相对 `v3.0.11` 的主要运行时变化：
+下面是当前 `v3.0.16` 相对 `v3.0.15 beta` 的主要可见变化：
 
-- 显式使用 `~auto` 和 `~loop` 时，运行时不再默认接受中途停下；主代理结束本轮前，必须先写出有效的结构化停下状态。
-- `waiting` 和 `blocked` 现在必须同时带 `reasonCategory` 和具体 `reason`，只有真实阻塞才能暂停流程，不再接受含糊的“下一步”式停顿。
-- stop hook 和 Codex 的 turn-complete 通知链路现在共用同一层门控，减少任务本应继续执行却表现得像在等批准的情况。
+- Codex 通知现在同时覆盖 Codex TUI 与 `codex exec` 的完成事件，turn-state 门控、交付检查和完成通知在不同入口下保持一致。
+- Windows 下的 Codex 受管通知命令改用命令 shim，减少直接脚本路径或 shell 解析差异导致的失败。
+- 运行时配置读取会优先复用当前会话缓存，减少重复读取 `~/.helloagents/helloagents.json`，同时保留显式刷新行为。
+- 持久 carrier 文件不再快照用户设置；运行时注入和最终输出格式在执行时解析当前配置。
+- 部分宿主安装成功后，安装追踪更严格，`helloagents update --all` 可以更可靠地保留每个 CLI 的检测模式或追踪模式。
+- UI 规则边界更清晰：共享 UI 基线是最低质量线；在全局模式、已激活项目或显式 UI 工作流中，`hello-ui` 补充具体设计、实现和视觉验收规则。
+- 一键安装脚本新增 `HELLOAGENTS_ACTION=cleanup`，可只清理宿主集成而不卸载包。
 
 ## 核心功能
 
@@ -109,8 +113,8 @@ HelloAGENTS 内置 14 个 `hello-*` 技能。技能只在当前阶段需要时
 | `hello-reflect` | 可复用经验和知识更新 |
 
 所有 UI 任务都会先受共享的 UI 质量基线约束。
-在已激活项目或明确的 UI 工作流里，`hello-ui` 会进一步补充设计契约执行、设计系统映射与视觉验收。
-当需要视觉证据时，HelloAGENTS 可以写入 `.helloagents/.ralph-visual.json`。
+在全局模式、已激活项目或明确的 UI 工作流里，`hello-ui` 会在该基线之上补充设计契约执行、设计系统映射与视觉验收。
+当需要视觉证据时，HelloAGENTS 会写入当前会话的 `artifacts/visual.json`。
 
 ### 2）面向不同工作方式的命令
 
@@ -205,11 +209,13 @@ HelloAGENTS 不把“命令通过”和“任务完成”简单画等号。交
 
 运行态证据文件包括：
 
-- `.helloagents/.ralph-review.json`
-- `.helloagents/.ralph-advisor.json`
-- `.helloagents/.ralph-visual.json`
-- `.helloagents/.ralph-closeout.json`
-- `.helloagents/loop-results.tsv`
+- `.helloagents/sessions/<branch>/<session>/capsule.json`
+- `.helloagents/sessions/<branch>/<session>/events.jsonl`
+- `.helloagents/sessions/<branch>/<session>/artifacts/review.json`
+- `.helloagents/sessions/<branch>/<session>/artifacts/advisor.json`
+- `.helloagents/sessions/<branch>/<session>/artifacts/visual.json`
+- `.helloagents/sessions/<branch>/<session>/artifacts/closeout.json`
+- `.helloagents/sessions/<branch>/<session>/artifacts/loop-results.tsv`
 
 ### 7）更安全的安装、更新、清理和诊断
 
@@ -235,7 +241,7 @@ npm install -g helloagents
 helloagents-js
 ```
 
-`postinstall` 只安装包命令并初始化 `~/.helloagents/helloagents.json`，不会自动部署到任何 AI CLI。
+默认情况下，`postinstall` 会安装包命令、初始化 `~/.helloagents/helloagents.json`，并把运行时文件同步到 `~/.helloagents/helloagents`。如果希望 npm 在安装或更新后直接部署，设置 `HELLOAGENTS=目标[:模式]`，例如 `HELLOAGENTS=codex:global`。
 
 ### 2）部署到目标 CLI
 
@@ -250,8 +256,11 @@ helloagents install --all --standby
 
 ```bash
 helloagents --global
+helloagents install --all --global
 ```
 
+重装、刷新或切换模式后，请重启对应 AI CLI 或新开会话；已运行会话不会自动重载注入规则。
+
 ### 3）在 AI CLI 里验证
 
 输入：
@@ -288,6 +297,8 @@ helloagents install --all --global
 helloagents update codex
 helloagents cleanup claude --global
 helloagents uninstall gemini
+helloagents switch-branch beta
+helloagents switch-branch beta claude --global
 helloagents doctor
 helloagents doctor codex --json
 ```
@@ -301,13 +312,129 @@ helloagents doctor codex --json
 
 省略 `--standby` 或 `--global` 时，HelloAGENTS 会先复用该 CLI 已记录或检测到的模式，再回退到 `standby`。
 
+### npm 和一键脚本入口
+
+当你不想依赖更新过程中的 `helloagents` 可执行文件时，用 npm 或一键脚本。`HELLOAGENTS=目标[:模式]` 中，目标支持 `all`、`claude`、`gemini`、`codex`；模式支持 `standby`、`global`，省略时默认 `standby`。
+
+宿主配置使用稳定的 `helloagents-js` 入口和运行根目录 `~/.helloagents/helloagents`，Node 全局包路径变化不会破坏受管 hooks 或 Codex `notify`。
+
+#### npm 命令
+
+macOS / Linux：
+
+```bash
+# 安装到 Codex，标准模式
+HELLOAGENTS=codex npm install -g helloagents
+
+# 安装到 Codex，全局模式
+HELLOAGENTS=codex:global npm install -g helloagents
+
+# 更新并同步 Claude，标准模式
+HELLOAGENTS=claude:standby npm update -g helloagents
+
+# 切换到 beta 分支并同步全部 CLI，标准模式
+HELLOAGENTS=all:standby npm install -g github:hellowind777/helloagents#beta
+
+# 卸载包前清理 Gemini 集成
+npm explore -g helloagents -- npm run uninstall -- gemini --standby
+npm uninstall -g helloagents
+```
+
+Windows PowerShell：
+
+```powershell
+# 安装到 Codex，标准模式
+$env:HELLOAGENTS="codex"; npm install -g helloagents
+
+# 安装到 Codex，全局模式
+$env:HELLOAGENTS="codex:global"; npm install -g helloagents
+
+# 更新并同步 Claude，标准模式
+$env:HELLOAGENTS="claude:standby"; npm update -g helloagents
+
+# 切换到 beta 分支并同步全部 CLI，标准模式
+$env:HELLOAGENTS="all:standby"; npm install -g github:hellowind777/helloagents#beta
+
+# 卸载包前清理 Gemini 集成
+npm explore -g helloagents -- npm run uninstall -- gemini --standby
+npm uninstall -g helloagents
+```
+
+包已安装后，也可以直接调用包内 npm scripts：
+
+```bash
+npm explore -g helloagents -- npm run deploy:global
+npm explore -g helloagents -- npm run sync-hosts -- --all --standby
+npm explore -g helloagents -- npm run cleanup-hosts -- codex --standby
+npm explore -g helloagents -- npm run uninstall -- --all --standby
+```
+
+#### 一键脚本
+
+macOS / Linux：
+
+```bash
+# 安装
+HELLOAGENTS=codex curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh
+
+# 更新
+HELLOAGENTS=claude:standby HELLOAGENTS_ACTION=update curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh
+
+# 切换分支
+HELLOAGENTS=all:global HELLOAGENTS_ACTION=switch-branch HELLOAGENTS_BRANCH=beta curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh
+
+# 只清理宿主集成，不卸载包
+HELLOAGENTS=codex:standby HELLOAGENTS_ACTION=cleanup curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh
+
+# 卸载
+HELLOAGENTS=gemini HELLOAGENTS_ACTION=uninstall curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh
+```
+
+Windows PowerShell：
+
+```powershell
+# 安装
+$env:HELLOAGENTS="codex"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex
+
+# 更新
+$env:HELLOAGENTS="claude:standby"; $env:HELLOAGENTS_ACTION="update"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex
+
+# 切换分支
+$env:HELLOAGENTS="all:global"; $env:HELLOAGENTS_ACTION="switch-branch"; $env:HELLOAGENTS_BRANCH="beta"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex
+
+# 只清理宿主集成，不卸载包
+$env:HELLOAGENTS="codex:standby"; $env:HELLOAGENTS_ACTION="cleanup"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex
+
+# 卸载
+$env:HELLOAGENTS="gemini"; $env:HELLOAGENTS_ACTION="uninstall"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex
+```
+
+### 分支切换
+
+`switch-branch` 会先安装指定 npm/GitHub ref，再通过 npm 脚本同步宿主 CLI，避免依赖更新过程中的 `helloagents` 可执行文件：
+
+```bash
+helloagents switch-branch beta
+helloagents switch-branch beta claude --global
+helloagents branch github:hellowind777/helloagents#beta --all --standby
+```
+
+如果只想切换包本身，暂不同步宿主 CLI，可以直接使用 npm：
+
+```bash
+npm install -g github:hellowind777/helloagents#beta
+npm update -g helloagents
+npm explore -g helloagents -- npm run uninstall -- --all --standby
+npm uninstall -g helloagents
+```
+
 ### 标准模式文件
 
 | CLI | 写入或更新的文件 | 清理行为 |
 |-----|------------------|----------|
-| Claude Code | `~/.claude/CLAUDE.md`、`~/.claude/settings.json`、`~/.claude/helloagents -> <package-root>` | 删除受管标记块、HelloAGENTS hooks / 权限和符号链接 |
-| Gemini CLI | `~/.gemini/GEMINI.md`、`~/.gemini/settings.json`、`~/.gemini/helloagents -> <package-root>` | 删除受管标记块、HelloAGENTS hooks 和符号链接 |
-| Codex CLI | `~/.codex/AGENTS.md`、`~/.codex/config.toml`、`~/.codex/helloagents -> <package-root>`、受管备份 | 删除受管标记块、受管配置键、符号链接和最近一次受管备份 |
+| Claude Code | `~/.claude/CLAUDE.md`、`~/.claude/settings.json`、`~/.claude/helloagents -> ~/.helloagents/helloagents` | 删除受管标记块、HelloAGENTS hooks / 权限和符号链接 |
+| Gemini CLI | `~/.gemini/GEMINI.md`、`~/.gemini/settings.json`、`~/.gemini/helloagents -> ~/.helloagents/helloagents` | 删除受管标记块、HelloAGENTS hooks 和符号链接 |
+| Codex CLI | `~/.codex/AGENTS.md`、`~/.codex/config.toml`、`~/.codex/helloagents -> ~/.helloagents/helloagents`、受管备份 | 删除受管标记块、受管配置键、符号链接和最近一次受管备份 |
 
 ### 全局模式文件
 
@@ -315,15 +442,18 @@ helloagents doctor codex --json
 |-----|----------|----------|
 | Claude Code | 原生插件安装 | 由 Claude Code 插件系统管理 |
 | Gemini CLI | 原生扩展安装 | 由 Gemini 扩展系统管理 |
-| Codex CLI | 原生本地插件链路 | `~/.agents/plugins/marketplace.json`、`~/plugins/helloagents/`、`~/.codex/plugins/cache/local-plugins/helloagents/local/`、`~/.codex/config.toml`、`~/.codex/helloagents -> ~/plugins/helloagents` |
+| Codex CLI | 原生本地插件流程 | `~/.agents/plugins/marketplace.json`、`~/plugins/helloagents/`、`~/.codex/plugins/cache/local-plugins/helloagents/local/`、`~/.codex/config.toml`、`~/.codex/helloagents -> ~/plugins/helloagents` |
 
-Claude Code 和 Gemini CLI 的全局模式仍需要宿主原生命令：
+全局模式下，HelloAGENTS 会自动尝试宿主原生命令。若宿主命令不可用，再手动执行：
 
 ```text
 /plugin marketplace add hellowind777/helloagents
+/plugin install helloagents@helloagents
 gemini extensions install https://github.com/hellowind777/helloagents
 ```
 
+Claude Code 会自动尝试等价的 `claude plugin marketplace add ...` 和 `claude plugin install ...` 命令。marketplace 名称和插件名称都是 `helloagents`，所以安装目标是 `helloagents@helloagents`。全局安装后需要重启宿主 CLI。
+
 Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 
 ## 对话命令
@@ -377,8 +507,20 @@ Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 运行态文件仍保留在当前项目本地：
 
 - `state_path`
-- `.ralph-*.json`
-- `loop-results.tsv`
+- `.helloagents/sessions/<branch>/<session>/capsule.json`
+- `.helloagents/sessions/<branch>/<session>/events.jsonl`
+- `.helloagents/sessions/<branch>/<session>/artifacts/*.json`
+- `.helloagents/sessions/<branch>/<session>/artifacts/loop-results.tsv`
+
+### 未激活或临时会话
+
+如果当前目录及其父级没有项目激活目录 `.helloagents/`，HelloAGENTS 不会自动写入项目目录。临时运行态写到用户级目录：
+
+```text
+~/.helloagents/runtime/<scope-key>/
+```
+
+这里仅保存短期的 `capsule.json`、`events.jsonl` 和 `artifacts/`，不作为项目知识库。过期临时会话会按 TTL 清理。
 
 ### 知识创建规则
 
@@ -424,15 +566,14 @@ UI 任务遵循以下优先级：
 
 1. 当前 `plan.md` 或 PRD 中的 UI 决策
 2. `.helloagents/DESIGN.md`
-3. 共享 UI 质量基线
-4. `hello-ui` 的实现和验收规则
+3. `hello-ui` 的实现和验收规则，与共享 UI 质量基线共同生效
 
 更重的 UI 任务可以通过 `contract.json` 要求：
 
 - `ui.styleAdvisor.required`
 - `ui.visualValidation.required`
 
-这些要求分别通过 `.helloagents/.ralph-advisor.json` 和 `.helloagents/.ralph-visual.json` 收尾。
+这些要求分别通过当前会话的 `artifacts/advisor.json` 和 `artifacts/visual.json` 收尾。
 
 ### 验证命令来源
 
@@ -452,7 +593,7 @@ UI 任务遵循以下优先级：
 ~/.helloagents/helloagents.json
 ```
 
-默认结构：
+默认结构。`host_install_modes` 会在需要记录单个 CLI 模式时写入：
 
 ```json
 {
@@ -464,21 +605,23 @@ UI 任务遵循以下优先级：
   "kb_create_mode": 1,
   "project_store_mode": "local",
   "commit_attribution": "",
-  "install_mode": "standby"
+  "install_mode": "standby",
+  "host_install_modes": {}
 }
 ```
 
 | 键 | 默认值 | 含义 |
 |----|--------|------|
 | `output_language` | `""` | 默认跟随用户语言 |
-| `output_format` | `true` | 只有主代理最终收尾消息可以使用 HelloAGENTS 格式 |
+| `output_format` | `true` | 主代理最终收尾必须使用 HelloAGENTS 格式；中间输出和子代理输出保持自然 |
 | `notify_level` | `0` | `0` 关闭，`1` 桌面通知，`2` 声音，`3` 两者 |
-| `ralph_loop_enabled` | `true` | 任务完成后运行验证 |
+| `ralph_loop_enabled` | `true` | 显式 `~verify` / `~loop` 或收尾要求时运行验证 |
 | `guard_enabled` | `true` | 拦截危险命令 |
 | `kb_create_mode` | `1` | 控制知识库自动更新 |
 | `project_store_mode` | `"local"` | `local` 或 `repo-shared` |
 | `commit_attribution` | `""` | 提交信息附加署名 |
 | `install_mode` | `"standby"` | 当前默认安装模式 |
+| `host_install_modes` | `{}` | 受管的单 CLI 模式记录，如 `{ "codex": "standby" }`；优先于 `install_mode` |
 
 ## 各 CLI 集成方式
 
@@ -486,14 +629,14 @@ UI 任务遵循以下优先级：
 
 - 标准模式写入 `~/.claude/CLAUDE.md`
 - 标准模式在 `~/.claude/settings.json` 中写入受管 hooks 和权限
-- 标准模式创建 `~/.claude/helloagents -> <package-root>`
+- 标准模式创建 `~/.claude/helloagents -> ~/.helloagents/helloagents`
 - 全局模式使用 Claude Code 插件系统
 
 ### Gemini CLI
 
 - 标准模式写入 `~/.gemini/GEMINI.md`
 - 标准模式在 `~/.gemini/settings.json` 中写入受管 hooks
-- 标准模式创建 `~/.gemini/helloagents -> <package-root>`
+- 标准模式创建 `~/.gemini/helloagents -> ~/.helloagents/helloagents`
 - 全局模式使用 Gemini 扩展系统
 
 ### Codex CLI
@@ -501,10 +644,10 @@ UI 任务遵循以下优先级：
 Codex 默认走规则文件驱动。
 
 - 标准模式写入 `~/.codex/AGENTS.md`
-- 标准模式写入受管 `model_instructions_file` 指向该文件
-- 标准模式写入受管 `notify` 命令用于收尾通知
-- 标准模式创建 `~/.codex/helloagents -> <package-root>`
-- 全局模式安装原生本地插件链路
+- 标准模式写入受管 `model_instructions_file = "~/.codex/AGENTS.md"`
+- 标准模式写入受管 `notify = ["helloagents-js", "codex-notify"]` 命令用于收尾通知
+- 标准模式创建 `~/.codex/helloagents -> ~/.helloagents/helloagents`
+- 全局模式安装原生本地插件流程
 - HelloAGENTS 默认不启用 Codex hooks
 
 ## 验证
@@ -522,12 +665,16 @@ npm test
 - Codex 受管 `model_instructions_file`、`notify`、本地插件、marketplace 和缓存行为
 - `helloagents doctor`
 - 项目存储和 `repo-shared`
-- 会话级 `state_path`
+- 会话级 `state_path`、运行态信号和证据
 - 运行时选路、Guard、验证、视觉证据和交付门控
 - README 与 skill 契约一致性
 
 ## FAQ
 
+### `docs/` 的作用是什么？
+
+`docs/` 只作为用户和 AI 理解项目的参考材料，可能滞后于实现。运行时行为以源码、bootstrap 文件、skills、templates 和测试为准。
+
 ### 这是 CLI 工具还是提示词框架？
 
 两者都是。
@@ -562,7 +709,7 @@ npm test
 
 ### `npm uninstall -g helloagents` 会删除项目知识库吗？
 
-不会。卸载包只移除包本身。项目 `.helloagents/` 文件和 `~/.helloagents/helloagents.json` 会保留，除非你手动删除。
+不会。卸载包前运行 `npm explore -g helloagents -- npm run uninstall -- --all --standby`，会清理宿主集成和稳定运行副本。项目 `.helloagents/` 文件和 `~/.helloagents/helloagents.json` 会保留，除非你手动删除。
 
 ## 故障排除
 

package/bootstrap-lite.md

@@ -4,10 +4,10 @@
 
 ## 配置
 配置文件: ~/.helloagents/helloagents.json
-如果当前上下文中已包含"当前用户设置"，视为配置已完成读取，本轮直接复用。
-否则，当本轮首次遇到受配置影响的行为时，再读取一次配置文件并复用本轮结果；不要为了展示、确认或同一结论重复读取。
-同一轮内对同一配置文件、模块、SKILL、模板只读取一次，后续直接复用已得结论，不要重复探测或重复读取同一路径。
-在受限 CLI（如工作区限制导致家目录不可读）中，确需读取但失败时必须明确说明，并按默认值或当前已知设置执行；禁止静默回退或假装读取成功。
+`output_language` 非空时，所有用户可见文本使用该语言；为空则跟随用户当前语言。
+会话级缓存优先：当前上下文已有"当前用户设置"、原始 JSON 或读取摘要，且覆盖所需配置项时，直接复用。
+仅在缺少所需项、用户要求刷新，或本轮修改后需要核验时读取；输出格式只在缺少 `output_format` 已知值时触发读取。
+同一会话内，同一路径的配置文件、模块、SKILL、模板只读一次并跨轮复用；读取失败必须明示，并按默认值或已知设置执行。
 
 ## 编码原则
 - 代码是唯一判断依据，文档与代码不一致时以代码为准
@@ -54,8 +54,8 @@
 - 项目已有技术栈、设计系统或方案包时必须遵循既有决策
 
 ### UI 质量基线（涉及视觉/交互任务时，全阶段生效）
-任务涉及界面视觉、交互体验、页面结构、组件外观、信息呈现或设计需求时，统一遵循以下基线；适用于标准模式、标准模式+已激活项目与全局模式。
-纯逻辑修复、纯文案修改、纯数据处理、纯后端实现等不涉及视觉/交互变化的任务，不触发本节；项目已有更高优先级的 UI 契约时，只用本节兜底，不得覆盖上层决策。
+任务涉及界面视觉、交互体验、页面结构、组件外观、信息呈现或设计需求时，统一遵循以下基线；适用于标准模式未激活项目、标准模式已激活项目与全局模式。
+纯逻辑修复、纯文案修改、纯数据处理、纯后端实现等不涉及视觉/交互变化的任务，不触发本节。本基线是最低质量线；已有 `plan.md` / PRD、`DESIGN.md` 或 `hello-ui` 约束时，与其共同生效，不覆盖上层决策。
 
 - 先判断本次视觉变更是延续既有风格、演进式优化还是探索性方案，再形成简短但明确的内部设计简报：界面目的、目标用户与场景、主要视口、情绪方向、记忆点；不得直接滑入泛化风格标签或模型默认审美
 - 已有项目优先复用现有组件、token、品牌资产、内容语气与交互模式；先建立最小设计系统：至少明确背景/表面/正文/弱化/强调/语义色，以及 display/headline/body/caption 等排版角色；缺少关键设计上下文时明确说明，不凭空发明视觉语言
@@ -97,7 +97,7 @@
 
 ## 输出格式
 适用条件：
-- 当 `helloagents.json` 的 `output_format` 为 `true` 时，主代理仅可在本轮最后一条、且确认**不再继续调用工具、不再继续执行**的**收尾消息**中使用输出格式。
+- 当 `helloagents.json` 的 `output_format` 为 `true` 时，主代理必须在本轮最后一条、且确认**不再继续调用工具、不再继续执行**的**收尾消息**中使用输出格式。
 - 若某个 skill 在本轮明确要求输出停顿、确认或总结，也仅当该消息同时是**本轮最终收尾消息**时，才可使用输出格式。
 
 排除条件：
@@ -116,16 +116,18 @@
 图标：💡直接响应 | ⚡快速执行 | 🔵规划流程 | ✅完成 | ❓等待输入 | ⚠️警告 | ❌错误
 
 使用约束：
-- 状态图标与收尾内容必须一致。等待用户输入、确认、授权或补充信息时，只能使用 `❓等待输入`；仅在本轮执行已完成且不再等待用户输入时，才能使用 `✅完成`。
-- `🔄 下一步` 必须填写当前最合适的下一步动作。若存在自然后续动作，直接给出明确引导；若当前任务已完整结束且确无合理后续，可填写“当前任务已完成；无后续动作。”
-- `🔄 下一步` 只写真实下一步，不改写成条件式能力表述或询问句。
+- 状态图标与收尾内容必须一致。正文仍在等待用户输入、确认、授权或补充信息（含确认是否执行已给出的方案）时，只能使用 `❓等待输入`；仅在本轮执行已完成且不存在待确认动作时，才能使用 `✅完成`。
+- `🔄 下一步` 必须写真实下一步，不改写成条件式能力表述或空泛询问。若正在等待确认，写清待确认动作；若存在自然后续动作，直接给出明确引导；若当前任务已完整结束且确无合理后续，可填写“当前任务已完成；无后续动作。”
 
 ### 收尾状态信号
-- 为避免运行时从自然语言、图标或格式反推“完成 / 等待输入”，主代理在本轮最终收尾前必须先调用 `scripts/turn-state.mjs write`
-- 本轮已完成且不再等待用户输入 → 写 `kind=complete`、`role=main`
-- 因阻塞判定等待用户输入、确认、授权或补充信息 → 写 `kind=waiting`、`role=main`，并同时写 `reasonCategory` 与 `reason`
+- `turn-state` 只在运行时必须识别本轮“完成 / 等待输入 / 阻塞”时写入；普通问候、普通问答、T0 只读分析和一次性解释不调用
+- 必须调用场景：显式 `~auto` / `~loop`；非只读任务完成验证并进入收尾；需要 delivery gate / Ralph Loop / closeout evidence；需要等待或阻塞且运行时必须识别状态；已进入项目连续流程或方案包闭环
+- 首选参数式调用，保证一次完成：`helloagents-turn-state write --kind complete --role main`；也可用 stdin JSON。不要查找、读取或拼接 `turn-state.mjs` 源码路径
+- 本轮已完成且不再等待用户输入 → `helloagents-turn-state write --kind complete --role main`
+- 因阻塞判定等待用户输入、确认、授权或补充信息（含未授权的外部副作用确认） → 写 `kind=waiting`、`role=main`，并同时写 `reasonCategory` 与 `reason`
 - 因错误、缺少前置条件或外部依赖而本轮停下 → 写 `kind=blocked`、`role=main`，并同时写 `reasonCategory` 与 `reason`
 - `reasonCategory` 只允许：`ambiguity`、`missing-input`、`missing-file`、`missing-credential`、`unauthorized-side-effect`、`high-risk-confirmation`、`external-dependency`、`error`
+- 显式 `~auto` / `~loop` 下，`waiting` / `blocked` 还必须写入 `blocker.target`、`blocker.evidence`、`blocker.requiredAction`；阶段汇报、单轮 probe 完成、内部路线调整或“下一步建议”不构成停下理由
 - 子代理不得写 turn-state；子代理结束只直接返回结果，不为主代理代写完成态
 
 ## 交互规则
@@ -163,7 +165,7 @@
 以下情况才构成中途停下并请求用户输入的正当理由：
 - 需求存在影响执行结果的真实歧义
 - 缺少继续执行所必需的信息、文件、路径或凭据
-- 将产生外部副作用，但本轮尚未获得对应授权
+- 将产生外部副作用，但本轮尚未获得对应授权（含等待确认是否实施已给方案）
 - 操作属于高风险或不可逆，按安全规则必须确认
 除上述情况外，默认继续执行，不以“建议下一步”替代实际推进。
 
@@ -186,22 +188,26 @@
 - 未激活项目且未进入方案包 / `contract.json` / 证据文件时，声称完成前必须完成与任务类型匹配的必要检查；无法执行的检查必须明确说明，不得直接宣称完成
 - 当前项目已激活，或已存在方案包 / `contract.json` / 证据文件时，以完整流程、对应 skill 与运行时交付约束为准，不得降级为本节
 - 只读分析、创意探索、方案比较、中间进度和阻塞汇报不适用本节
+- 本地版本检查点：非只读任务完成验证且产生工作区变更时，最终收尾前自动执行本地提交。先检查 `git status --short`；若不是 git 仓库或无变更则跳过。若发现 `.env`、密钥、凭据、明显不应提交的大文件或二进制产物，停止提交并说明风险；否则执行 `git add -A`，使用当前回复语言生成简洁 conventional commit message 后执行 `git commit`。不自动远程 `git push`，除非用户明确要求
 
 ## 路由
 - `~do` 是 `~build` 的兼容别名；`~design` 是 `~plan` 的兼容别名；`~review` 是 `~verify` 的兼容别名
 - `~test` — 为指定模块或最近变更编写测试
-- 路径定义：`{HELLOAGENTS_READ_ROOT}` = 本轮已确定的 HelloAGENTS 读取根目录
+- 路径定义：`{HELLOAGENTS_READ_ROOT}` = 本轮已确定的 HelloAGENTS 读取根目录，统一用于读取 `skills/` 与 `templates/`
 - `~command` 路由：用户输入 `~xxx` 时，立即读取对应的 SKILL.md 并按其流程执行，不要自行探索或猜测。若当前上下文已解析出具体命令技能文件路径，直接使用它；否则先确定当前技能根目录：
   - 优先使用当前上下文中已注入的“本轮 HelloAGENTS 读取根目录”
-  - 若当前上下文未注入，则将当前宿主 home 目录下的 `helloagents/` 链接作为 `{HELLOAGENTS_READ_ROOT}`
+  - 若当前上下文未注入，则使用稳定运行根目录 `~/.helloagents/helloagents`
+  - 宿主固定链接（Codex `~/.codex/helloagents`、Claude `~/.claude/helloagents`、Gemini `~/.gemini/helloagents`）只作为兼容别名，不作为优先探测路径
+  - 仍无法确定时，明确说明缺少 HelloAGENTS 读取根目录；不要递归扫描 `$HOME`、`Downloads`、项目目录或旧版本目录
   确定根目录后读取其中的 `skills/commands/{name}/SKILL.md`；标准模式下即使项目目录存在本地 HelloAGENTS skills，也不要读取项目路径。不要扫描整个目录，也不要对同一命令重复探测多个路径。
+包内脚本优先使用稳定命令入口；需要写收尾状态时优先调用 `helloagents-turn-state write --kind complete --role main`，不要拼接 `turn-state.mjs` 路径。
 
 ## .helloagents/ 目录
 路径: {CWD}/.helloagents/
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
 说明：
-- `.helloagents/` 表示项目级存储路径，也是 standby 模式的激活信号
-- `state_path` 指向的状态文件、`.ralph-*.json`、`loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/`
+- `.helloagents/` 表示项目级存储路径，也是标准模式的项目激活信号
+- `state_path` 指向的状态文件、当前会话 `capsule.json`、`events.jsonl`、`artifacts/*.json`、`artifacts/loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/sessions/{branch}/{session}/`
 - `state_path` 是状态文件的唯一位置。宿主提供会话标识时，写入 `.helloagents/sessions/{branch}/{session}/STATE.md`；没有稳定会话标识时，写入 `.helloagents/sessions/{branch}/default/STATE.md`
 - 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定这些文件一定实际位于当前工作树中
 templates/ 查找路径（按优先级；首次确定模板根目录后，本轮复用）：
@@ -227,7 +233,7 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
   - “关键上下文”只保留恢复所需的信息，已不再相关的决策和变更移除
 - DESIGN.md — 项目级稳定 UI 契约（仅 UI 项目），`~plan` / `~auto` / `~prd` 创建或更新；不存在且当前任务涉及 UI → 按 templates/DESIGN.md 创建；不替代单次需求的 `plan.md`
 - plans/{feature}/ — 活跃方案包。`~plan` / `~auto` 生成：`requirements.md` + `plan.md` + `tasks.md` + `contract.json`；`~prd` 生成：`prd/` 目录（多维度文档）+ `tasks.md` + `decisions.md` + `contract.json`
-- .ralph-advisor.json — 可选 advisor 证据；仅当 `contract.json` 明确要求独立 advisor 时写入，记录 reason / focus / consultedSources / outcome
+- artifacts/advisor.json — 当前会话的可选 advisor 证据；仅当 `contract.json` 明确要求独立 advisor 时写入，记录 reason / focus / consultedSources / outcome
 - archive/YYYY-MM/ — 已归档的方案包（整个 plans/{feature}/ 目录移入）
 - archive/_index.md — 归档索引
 
@@ -239,11 +245,11 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 - modules/*.md — 模块文档和经验
 
 ### 临时文件（流程产物，~clean 时清理）
-- loop-results.tsv — ~loop 迭代记录
-- .ralph-breaker.json — hello-verify 断路器状态
-- .ralph-verify.json — 最近一次成功验证的证据快照
-- .ralph-review.json — 最近一次成功审查的证据快照
-- .ralph-closeout.json — 最近一次成功收尾的交付证据快照
+- artifacts/loop-results.tsv — 当前会话的 ~loop 迭代记录
+- artifacts/loop-breaker.json — 当前会话的 hello-verify 断路器状态，仅在 `~loop` 或自动验证触发时写入
+- artifacts/verify.json — 当前会话最近一次成功验证的证据快照
+- artifacts/review.json — 当前会话最近一次成功审查的证据快照
+- artifacts/closeout.json — 当前会话最近一次成功收尾的交付证据快照
 
 ## 项目上下文
 
@@ -256,11 +262,11 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 ### .helloagents/ 文件读取优先级
 以下文件在任务需要时按需读取，按优先级分层：
 说明：
-- Tier 1 始终读取当前 `state_path`
+- Tier 1 在恢复、压缩、连续流程或活跃方案包场景读取当前 `state_path`；普通问答和一次性只读任务不强制读取
 - Tier 2 / Tier 3 中的 `.helloagents/...` 路径默认按项目级存储路径解析；`project_store_mode=repo-shared` 时按共享知识/方案目录解析
 
 Tier 1 — 恢复当前任务时优先读取：
-- 当前状态文件（`state_path`）→ 先确认当前消息仍是同一任务，再用它找回最近进度
+- 当前状态文件（`state_path`）→ 仅在恢复、压缩、连续流程或活跃方案包场景读取；先确认当前消息仍是同一任务，再用它找回最近进度
 
 Tier 2 — 理解项目时读取：
 - .helloagents/context.md → 项目架构、技术栈、目录结构、模块索引