helloagents 3.0.12 → 3.0.15-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.15-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.12 的真实变化](#相对-v3012-的真实变化)
 - [核心功能](#核心功能)
 - [快速开始](#快速开始)
 - [CLI 管理](#cli-管理)
@@ -77,13 +77,20 @@ HelloAGENTS 叠加在 Claude Code、Gemini CLI 和 Codex CLI 之上，帮助模
 | 完成态模糊 | 自然语言说“完成” | 按状态、证据和验证结果交付 |
 | 配置容易漂移 | CLI 文件可能不一致 | 安装、更新、清理和 doctor 会检查受管文件 |
 
-## 相对 v3.0.11 的真实变化
+## 相对 v3.0.12 的真实变化
 
-下面是当前 `v3.0.12` 相对 `v3.0.11` 的主要运行时变化：
+下面是当前 `v3.0.15` 相对 `v3.0.12` 的主要可见变化：
 
-- 显式使用 `~auto` 和 `~loop` 时，运行时不再默认接受中途停下；主代理结束本轮前，必须先写出有效的结构化停下状态。
-- `waiting` 和 `blocked` 现在必须同时带 `reasonCategory` 和具体 `reason`，只有真实阻塞才能暂停流程，不再接受含糊的“下一步”式停顿。
-- stop hook 和 Codex 的 turn-complete 通知链路现在共用同一层门控，减少任务本应继续执行却表现得像在等批准的情况。
+- 安装、更新、卸载和切换分支支持通过 npm scripts 与一键脚本完成，更新过程中不再依赖可能已经失效的旧 `helloagents` 可执行文件。
+- 标准模式统一读取稳定运行根目录 `~/.helloagents/helloagents`，受管 hooks 使用 `helloagents-js` 入口，skills、templates 和运行时脚本不再指向带 Node 版本号的全局包路径。
+- 全局模式会自动尝试安装 Claude Code 插件和 Gemini 扩展；Codex 继续使用受管本地插件链路，并刷新 marketplace 与缓存副本。
+- `~auto` 和 `~loop` 的结构化停顿门控更严格；流程确需暂停时，必须写明具体阻塞证据。
+- 运行态状态收敛到 `.helloagents/sessions/<branch>/<session>/` 下的会话胶囊，分别记录 turn-state、事件和交付证据，兼容多 CLI 窗口与多 worktree。
+- 仅在工作流需要运行时状态时，通过稳定入口 `helloagents-turn-state write --kind complete --role main` 写入，不再解析或拼接包内脚本路径。
+- Codex 标准模式刷新和清理会保留用户自有配置，同时更新受管 carrier、本地插件文件、marketplace 条目和 doctor 检查。
+- 输出格式配置在 carrier 与运行时注入中保持一致，减少收尾格式偶发不生效的问题。
+- 调试、测试、验证和规划流程补充反馈循环、垂直切片 TDD、领域语言和 AFK/HITL 任务标记，仍复用现有 skills 与模板体系。
+- 运行时提示统一为更自然的中文表述，并明确重装、刷新或切换模式后需要重启 AI CLI 或新开会话。
 
 ## 核心功能
 
@@ -110,7 +117,7 @@ HelloAGENTS 内置 14 个 `hello-*` 技能。技能只在当前阶段需要时
 
 所有 UI 任务都会先受共享的 UI 质量基线约束。
 在已激活项目或明确的 UI 工作流里，`hello-ui` 会进一步补充设计契约执行、设计系统映射与视觉验收。
-当需要视觉证据时，HelloAGENTS 可以写入 `.helloagents/.ralph-visual.json`。
+当需要视觉证据时，HelloAGENTS 会写入当前会话的 `artifacts/visual.json`。
 
 ### 2）面向不同工作方式的命令
 
@@ -205,11 +212,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 +244,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 +259,11 @@ helloagents install --all --standby
 
 ```bash
 helloagents --global
+helloagents install --all --global
 ```
 
+重装、刷新或切换模式后，请重启对应 AI CLI 或新开会话；已运行会话不会自动重载注入规则。
+
 ### 3）在 AI CLI 里验证
 
 输入：
@@ -288,6 +300,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 +315,123 @@ 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=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="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`、受管备份 | 删除受管标记块、受管配置键、符号链接和最近一次受管备份 |
 
 ### 全局模式文件
 
@@ -317,13 +441,16 @@ helloagents doctor codex --json
 | 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` |
 
-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 +504,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 清理。
 
 ### 知识创建规则
 
@@ -432,7 +571,7 @@ UI 任务遵循以下优先级：
 - `ui.styleAdvisor.required`
 - `ui.visualValidation.required`
 
-这些要求分别通过 `.helloagents/.ralph-advisor.json` 和 `.helloagents/.ralph-visual.json` 收尾。
+这些要求分别通过当前会话的 `artifacts/advisor.json` 和 `artifacts/visual.json` 收尾。
 
 ### 验证命令来源
 
@@ -471,9 +610,9 @@ UI 任务遵循以下优先级：
 | 键 | 默认值 | 含义 |
 |----|--------|------|
 | `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` |
@@ -486,14 +625,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,9 +640,9 @@ 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,7 +661,7 @@ npm test
 - Codex 受管 `model_instructions_file`、`notify`、本地插件、marketplace 和缓存行为
 - `helloagents doctor`
 - 项目存储和 `repo-shared`
-- 会话级 `state_path`
+- 会话级 `state_path`、运行态信号和证据
 - 运行时选路、Guard、验证、视觉证据和交付门控
 - README 与 skill 契约一致性
 
@@ -562,7 +701,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,8 +4,9 @@
 
 ## 配置
 配置文件: ~/.helloagents/helloagents.json
-如果当前上下文中已包含"当前用户设置"，视为配置已完成读取，本轮直接复用。
+如果当前上下文中已包含"当前用户设置"且包含本轮所需配置项，视为配置已完成读取，本轮直接复用。
 否则，当本轮首次遇到受配置影响的行为时，再读取一次配置文件并复用本轮结果；不要为了展示、确认或同一结论重复读取。
+输出格式判定属于受配置影响的行为；上下文没有"当前用户设置"时，最终收尾前必须读取一次该配置。
 同一轮内对同一配置文件、模块、SKILL、模板只读取一次，后续直接复用已得结论，不要重复探测或重复读取同一路径。
 在受限 CLI（如工作区限制导致家目录不可读）中，确需读取但失败时必须明确说明，并按默认值或当前已知设置执行；禁止静默回退或假装读取成功。
 
@@ -97,7 +98,7 @@
 
 ## 输出格式
 适用条件：
-- 当 `helloagents.json` 的 `output_format` 为 `true` 时，主代理仅可在本轮最后一条、且确认**不再继续调用工具、不再继续执行**的**收尾消息**中使用输出格式。
+- 当 `helloagents.json` 的 `output_format` 为 `true` 时，主代理必须在本轮最后一条、且确认**不再继续调用工具、不再继续执行**的**收尾消息**中使用输出格式。
 - 若某个 skill 在本轮明确要求输出停顿、确认或总结，也仅当该消息同时是**本轮最终收尾消息**时，才可使用输出格式。
 
 排除条件：
@@ -116,16 +117,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 +166,7 @@
 以下情况才构成中途停下并请求用户输入的正当理由：
 - 需求存在影响执行结果的真实歧义
 - 缺少继续执行所必需的信息、文件、路径或凭据
-- 将产生外部副作用，但本轮尚未获得对应授权
+- 将产生外部副作用，但本轮尚未获得对应授权（含等待确认是否实施已给方案）
 - 操作属于高风险或不可逆，按安全规则必须确认
 除上述情况外，默认继续执行，不以“建议下一步”替代实际推进。
 
@@ -186,22 +189,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/`
+- `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 +234,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 +246,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 +263,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 → 项目架构、技术栈、目录结构、模块索引

package/bootstrap.md

@@ -4,8 +4,9 @@
 
 ## 配置
 配置文件: ~/.helloagents/helloagents.json
-如果当前上下文中已包含"当前用户设置"，视为配置已完成读取，本轮直接复用。
+如果当前上下文中已包含"当前用户设置"且包含本轮所需配置项，视为配置已完成读取，本轮直接复用。
 否则，当本轮首次遇到受配置影响的行为时，再读取一次配置文件并复用本轮结果；不要为了展示、确认或同一结论重复读取。
+输出格式判定属于受配置影响的行为；上下文没有"当前用户设置"时，最终收尾前必须读取一次该配置。
 同一轮内对同一配置文件、模块、SKILL、模板只读取一次，后续直接复用已得结论，不要重复探测或重复读取同一路径。
 在受限 CLI（如工作区限制导致家目录不可读）中，确需读取但失败时必须明确说明，并按默认值或当前已知设置执行；禁止静默回退或假装读取成功。
 
@@ -97,7 +98,7 @@
 
 ## 输出格式
 适用条件：
-- 当 `helloagents.json` 的 `output_format` 为 `true` 时，主代理仅可在本轮最后一条、且确认**不再继续调用工具、不再继续执行**的**收尾消息**中使用输出格式。
+- 当 `helloagents.json` 的 `output_format` 为 `true` 时，主代理必须在本轮最后一条、且确认**不再继续调用工具、不再继续执行**的**收尾消息**中使用输出格式。
 - 若某个 skill 在本轮明确要求输出停顿、确认或总结，也仅当该消息同时是**本轮最终收尾消息**时，才可使用输出格式。
 
 排除条件：
@@ -116,16 +117,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 +166,7 @@
 以下情况才构成中途停下并请求用户输入的正当理由：
 - 需求存在影响执行结果的真实歧义
 - 缺少继续执行所必需的信息、文件、路径或凭据
-- 将产生外部副作用，但本轮尚未获得对应授权
+- 将产生外部副作用，但本轮尚未获得对应授权（含等待确认是否实施已给方案）
 - 操作属于高风险或不可逆，按安全规则必须确认
 除上述情况外，默认继续执行，不以“建议下一步”替代实际推进。
 
@@ -205,13 +208,16 @@
 
 ### 3. PLAN — 规划与上下文准备
 根据 skills/ 目录下各 hello-* 技能的 SKILL.md frontmatter（name + description），标记本次任务可能需要的技能（不读取文件内容，仅记录名称）。
-路径定义：`{HELLOAGENTS_READ_ROOT}` = 本轮已确定的 HelloAGENTS 读取根目录
+路径定义：`{HELLOAGENTS_READ_ROOT}` = 本轮已确定的 HelloAGENTS 读取根目录，统一用于读取 `skills/` 与 `templates/`
 先确定当前技能根目录：
 - 优先使用当前上下文中已注入的“本轮 HelloAGENTS 读取根目录”
-- 若当前上下文未注入，则将当前宿主 home 目录下的 `helloagents/` 链接作为 `{HELLOAGENTS_READ_ROOT}`
+- 若当前上下文未注入，则使用稳定运行根目录 `~/.helloagents/helloagents`
+- 宿主固定链接（Codex `~/.codex/helloagents`、Claude `~/.claude/helloagents`、Gemini `~/.gemini/helloagents`）只作为兼容别名，不作为优先探测路径
+- 仍无法确定时，明确说明缺少 HelloAGENTS 读取根目录；不要递归扫描 `$HOME`、`Downloads`、项目目录或旧版本目录
 - 已激活项目或全局模式下，技能是否需要使用由当前已加载 AGENTS 规则决定；不要因此额外探测项目目录里的 HelloAGENTS skills 路径
 路径确定一次即可，不预读、不扫描整个目录，也不重复探测同一路径。
 hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.md`
+包内脚本优先使用稳定命令入口；需要写收尾状态时优先调用 `helloagents-turn-state write --kind complete --role main`，不要拼接 `turn-state.mjs` 路径。
 
 命令职责：
 - `~plan` 生成 `requirements.md`、`plan.md`、`tasks.md`、`contract.json`
@@ -235,7 +241,7 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 ### 5. VERIFY — 审查与验证
 编码任务：
 - 读取 `skills/hello-verify/SKILL.md`，执行完整验证循环（Ralph Loop）→ 失败则修复 → 循环直到通过
-- 审查优先或显式使用 `~review` 时，先读取 `skills/hello-review/SKILL.md` 做范围审查；审查完成后调用 `scripts/review-state.mjs write` 写 `.helloagents/.ralph-review.json`，再进入验证
+- 审查优先或显式使用 `~review` 时，先读取 `skills/hello-review/SKILL.md` 做范围审查；审查完成后调用 `scripts/review-state.mjs write` 写当前会话 `artifacts/review.json`，再进入验证
 - 通过后收集已读取技能的交付检查清单，逐项附带证据确认，并确认用户目标已达成
 
 非编码任务（文档 / 方案 / 审查等）：
@@ -243,14 +249,15 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 
 ### 6. CONSOLIDATE — 状态、资料与归档
 所有任务：
-- 有方案包且准备报告完成 → 优先调用 `scripts/closeout-state.mjs write` 写 `.helloagents/.ralph-closeout.json`，记录“需求覆盖”和“交付清单”；每项写明 `PASS` / `BLOCKED` 与简要摘要，再进入最终交付
+- 有方案包且准备报告完成 → 优先调用 `scripts/closeout-state.mjs write` 写当前会话 `artifacts/closeout.json`，记录“需求覆盖”和“交付清单”；每项写明 `PASS` / `BLOCKED` 与简要摘要，再进入最终交付
 - 状态文件维护：按上文“流程状态”中的适用范围执行。属于“强制创建并持续更新”范围时，重写 `state_path` 指向的文件（“正在做什么”更新为已完成，清空关键上下文 / 下一步 / 阻塞项）；属于“已有则更新”范围时，仅在文件已存在时重写；属于“不创建”范围时不生成此文件
-- 有方案包且任务已完成 → 将整个 `plans/{feature}/` 目录归档到 `.helloagents/archive/YYYY-MM/`，并更新 `archive/_index.md`。清理临时文件（`loop-results.tsv`、`.ralph-breaker.json`、`.ralph-verify.json`、`.ralph-review.json`、`.ralph-closeout.json`）
+- 有方案包且任务已完成 → 将整个 `plans/{feature}/` 目录归档到 `.helloagents/archive/YYYY-MM/`，并更新 `archive/_index.md`。清理当前会话临时文件（`artifacts/loop-results.tsv`、`capsule.json`、`events.jsonl`、`artifacts/loop-breaker.json`、`artifacts/verify.json`、`artifacts/review.json`、`artifacts/closeout.json`）
 - 按 `kb_create_mode` 同步知识库（0=关闭 / 1=已激活项目或全局模式中编码自动 / 2=已激活项目或全局模式中始终）：
   - `.helloagents/` 不存在则按 templates/ 创建知识库文件（`context.md`、`guidelines.md`、`verify.yaml`、`CHANGELOG.md`、`modules/`）
   - 已存在但不完整（缺少上述核心文件）→ 按 templates/ 补全缺失文件，不覆盖已有文件
   - 已存在且完整则按模板格式更新 `CHANGELOG.md`、相关 `modules/*.md`、增量经验 delta 追加
 - 符合条件时触发 `hello-reflect`（详见 `hello-reflect` SKILL.md）
+- 本地版本检查点：非只读任务完成验证且产生工作区变更时，最终收尾前自动执行本地提交。先检查 `git status --short`；若不是 git 仓库或无变更则跳过。若发现 `.env`、密钥、凭据、明显不应提交的大文件或二进制产物，停止提交并说明风险；否则执行 `git add -A`，使用当前回复语言生成简洁 conventional commit message 后执行 `git commit`。不自动远程 `git push`，除非用户明确要求
 
 ## 完成约束
 - 未进入 VERIFY / CONSOLIDATE 的路径，声称完成前必须完成与任务类型匹配的必要检查；无法执行的检查必须明确说明，不得直接宣称完成
@@ -270,7 +277,7 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
 说明：
 - `.helloagents/` 表示项目级存储路径，也是 standby 模式的激活信号
-- `state_path` 指向的状态文件、`.ralph-*.json`、`loop-results.tsv` 等运行态文件始终保留在项目本地 `.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/ 查找路径（按优先级；首次确定模板根目录后，本轮复用）：
@@ -296,7 +303,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 — 归档索引
 
@@ -308,11 +315,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 — 当前会话最近一次成功收尾的交付证据快照
 
 ## 项目上下文
 
@@ -325,11 +332,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 → 项目架构、技术栈、目录结构、模块索引