helloagents 3.0.3-beta.1 → 3.0.7

package/README_CN.md

@@ -8,7 +8,7 @@
 
 **质量驱动的 AI 编码 CLI 编排内核 — 14 个自动激活技能、流程纪律、检查清单门控。**
 
-[![Version](https://img.shields.io/badge/version-3.0.2-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.7-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)
@@ -33,6 +33,7 @@
 <summary><strong>点击展开</strong></summary>
 
 - [🎯 为什么选择 HelloAGENTS？](#-为什么选择-helloagents)
+- [🆚 相比 v2.3.8 的变化](#-相比-v238-的变化)
 - [✨ 核心特性](#-核心特性)
 - [🚀 快速开始](#-快速开始)
 - [🔄 安装链路与文件写入](#-安装链路与文件写入)
@@ -90,6 +91,25 @@ HelloAGENTS 就是为了解决这个问题。它是一个编排层，装在你
 - ❌ 简单的一次性问题（HelloAGENTS 会增加流程开销）
 - ❌ 非编码任务（针对软件工程优化）
 
+## 🆚 相比 v2.3.8 的变化
+
+如果你上一次认真使用 HelloAGENTS 还是 `v2.3.8`，这一代的变化不是“增量补丁”，而是整条产品线重构。
+
+| 维度 | v2.3.8 | 本地 `v3.0.7` |
+|------|--------|---------------|
+| **底层实现** | Python 包 + 大量脚本/规则混合 | 纯 Node.js + Markdown 运行时，围绕 `cli.mjs`、`bootstrap*.md`、`skills/`、`scripts/` 重建 |
+| **目标定位** | 更像多 CLI 管理工具 + 提示协议集合 | 更像 AI CLI 的质量编排内核，重点是路由、门控、验证和可恢复执行 |
+| **安装方式** | pip / uv / npx / 一键脚本并行存在 | npm 为主；安装包后再显式部署到 Claude / Gemini / Codex |
+| **CLI 支持策略** | 6 个目标，能力差异很大 | 聚焦 3 个主战场：Claude Code、Gemini CLI、Codex CLI |
+| **工作流模型** | R0/R1/R2 三层路由 + 老式 design/develop 语义 | ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE 六阶段内核 |
+| **命令体系** | 15 个命令，含 `~exec` / `~rollback` / `~rlm` / `~validatekb` | 12 个聚焦命令：`~idea` / `~plan` / `~build` / `~verify` / `~prd` / `~loop` / `~wiki` 等 |
+| **质量模型** | 规则较分散，更多依赖自然语言约束 | 14 个自动激活技能 + 检查清单门控 + Ralph Loop + 结构化 evidence |
+| **项目状态** | 知识库更多是附属能力 | `.helloagents/` 成为项目激活边界，`STATE.md` / 方案包 / `DESIGN.md` / `contract.json` 组成主流程事实链 |
+| **知识库存储** | 默认项目本地 | 默认项目本地，同时新增 `project_store_mode=repo-shared`，支持同一 git 仓库多个 worktree 共享稳定知识和方案资产 |
+| **Codex 集成** | 早期依赖更多兼容层和旧链路 | 标准模式使用注入规则 + 本地链接；全局模式使用原生本地插件链路，减少噪音与漂移 |
+
+一句话概括：`v2.3.8` 更像“给多个 CLI 加一层工作流外壳”，`v3.0.7` 更像“把质量协议、计划工件、验证证据和安装生命周期统一成一套真正可运转的编排内核”。
+
 ## ✨ 核心特性
 
 HelloAGENTS 通过三重机制协同保障质量：
@@ -136,10 +156,32 @@ L1 拦截破坏性命令（`rm -rf /`、`git push --force`、`DROP DATABASE`）
 
 **⚡ 结构化工作流**
 
-简单任务直接执行。复杂任务走完整的 ORIENT → CLARIFY → PLAN → EXECUTE → VALIDATE 五阶段流程，包含交互式设计、方案提议和计划包。
+简单任务保持快速。复杂任务走“路由前置”的内核工作流：ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE，并通过显式命令通道拆分脑暴、规划、实现与验证。
 
 **你的收益：** 按需投入 — 简单任务保持快速，复杂任务获得完整流程。
 
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+<img src="./readme_images/02-feature-icon-installer.svg" width="48" align="left">
+
+**🧠 结构化计划工件**
+
+复杂任务不再只靠一段自然语言方案，而是落成 `requirements.md`、`plan.md`、`tasks.md`、`contract.json`、`STATE.md`、`DESIGN.md` 等可追踪工件。
+
+**你的收益：** 路由、实现、验证、收尾都围绕同一组事实源推进，不容易中途漂移。
+
+</td>
+<td width="50%" valign="top">
+<img src="./readme_images/05-feature-icon-compat.svg" width="48" align="left">
+
+**🗂️ 本地 / 共享双存储**
+
+默认把知识库和方案包放在项目本地 `.helloagents/`；如果你有多个 worktree，可以切到 `project_store_mode=repo-shared`，把稳定项目知识共享到 `~/.helloagents/projects/<repo-key>/`。
+
+**你的收益：** 保留本地运行态隔离，同时避免在多个 worktree 间复制方案和知识库。
+
 </td>
 </tr>
 </table>
@@ -226,7 +268,7 @@ Codex CLI 无需手动执行插件命令。`helloagents --global` 会自动走
 ```
 💡【HelloAGENTS】- 帮助
 
-可用命令: ~auto, ~design, ~prd, ~loop, ~wiki, ~init, ~test, ~verify, ~review, ~commit, ~clean, ~help
+可用命令: ~idea, ~auto, ~plan, ~build, ~prd, ~loop, ~wiki, ~init, ~test, ~verify, ~commit, ~clean, ~help
 
 自动激活技能 (14): hello-ui, hello-api, hello-security, hello-test, hello-verify, hello-errors, hello-perf, hello-data, hello-arch, hello-debug, hello-subagent, hello-review, hello-write, hello-reflect
 ```
@@ -241,7 +283,7 @@ Codex CLI 无需手动执行插件命令。`helloagents --global` 会自动走
 ~auto "添加基于 JWT 的用户认证"
 
 # 想先看方案？
-~design "重构支付模块"
+~plan "重构支付模块"
 ```
 
 ## 🔄 安装链路与文件写入
@@ -280,8 +322,10 @@ HelloAGENTS 在不同模式下会写入不同文件，但写入/恢复/清理都
 
 | 命令 | 说明 |
 |------|------|
-| `~auto` | 全自动工作流 — AI 判断复杂度，自动规划并执行 |
-| `~design` | 深度交互式设计 — 需求挖掘 + 方案提议 + 计划包 |
+| `~idea` | 轻量点子探索 — 比较方向与方案，不写文件 |
+| `~auto` | 自动选路 — 在脑暴 / 规划 / 实现 / 验证 / PRD 间选择合适路径，并优先复用现有活跃方案包 |
+| `~plan` | 结构化规划 — 需求澄清 + 方案收敛 + 计划包 |
+| `~build` | 执行实现 — 基于当前需求或现有计划包完成实现 |
 | `~prd` | 完整 PRD — 13 维度头脑风暴式探索，生成产品需求文档 |
 | `~loop` | 自主迭代优化 — 设定目标和指标，AI 循环改进直到达标 |
 
@@ -290,8 +334,7 @@ HelloAGENTS 在不同模式下会写入不同文件，但写入/恢复/清理都
 | 命令 | 说明 |
 |------|------|
 | `~test` | 编写完整测试（TDD：Red → Green → Refactor） |
-| `~verify` | 运行所有验证命令（lint/test/build/typecheck） |
-| `~review` | 代码审查，按严重程度分类 |
+| `~verify` | 统一验证入口 — 审查、lint、typecheck、test、build 与修复循环 |
 
 **工具命令：**
 
@@ -303,6 +346,11 @@ HelloAGENTS 在不同模式下会写入不同文件，但写入/恢复/清理都
 | `~clean` | 归档已完成方案，清理临时文件 |
 | `~help` | 显示所有命令和当前配置 |
 
+兼容别名：
+- `~design` → `~plan`
+- `~do` → `~build`
+- `~review` → `~verify`（审查优先模式）
+
 ## 🔧 配置
 
 配置文件：`~/.helloagents/helloagents.json`（安装时自动创建）
@@ -317,6 +365,7 @@ HelloAGENTS 在不同模式下会写入不同文件，但写入/恢复/清理都
   "ralph_loop_enabled": true,
   "guard_enabled": true,
   "kb_create_mode": 1,
+  "project_store_mode": "local",
   "commit_attribution": "",
   "install_mode": "standby"
 }
@@ -330,6 +379,7 @@ HelloAGENTS 在不同模式下会写入不同文件，但写入/恢复/清理都
 | `ralph_loop_enabled` | `true` | 任务完成时自动运行验证 |
 | `guard_enabled` | `true` | 拦截危险命令 |
 | `kb_create_mode` | `1` | `0`=关闭，`1`=已激活项目或全局模式中的编码任务自动，`2`=已激活项目或全局模式中始终 |
+| `project_store_mode` | `"local"` | `"local"`=知识库/方案包保留在项目本地 `.helloagents/`；`"repo-shared"`=本地 `.helloagents/` 仅保留激活/STATE/运行态，知识库与方案包改写到 `~/.helloagents/projects/<repo-key>/` |
 | `commit_attribution` | `""` | 空=不添加，填写内容则追加到 commit message |
 | `install_mode` | `"standby"` | `"standby"`=按项目激活（精简规则），`"global"`=所有项目启用完整规则 |
 
@@ -356,6 +406,11 @@ helloagents --standby
 { "kb_create_mode": 0 }
 ```
 
+**多个 worktree 共享知识库和方案包：**
+```json
+{ "project_store_mode": "repo-shared" }
+```
+
 **开启桌面+声音通知：**
 ```json
 { "notify_level": 3 }
@@ -370,22 +425,33 @@ helloagents --standby
 
 ## ⚙️ 工作原理
 
-**简单说：** HelloAGENTS 根据任务复杂度选择执行深度。简单任务直接执行，复杂任务走完整五阶段流程，并在每一步验证；当需求和执行方向已明确时，优先直接完成，而不是重复确认。
+**简单说：** HelloAGENTS 根据任务类型、风险等级和项目状态选择执行深度。标准模式下，未激活项目只保留轻量规则：安全、完成约束、压缩版质量下限，以及显式 `~command` 通道；一旦项目通过 `.helloagents/` 激活，或启用全局模式，就切换到完整内核工作流，显式经过脑暴、规划、实现、验证与收尾阶段。
 
-**五阶段流程：**
+**六阶段内核：**
 
-1. **ORIENT** — 读取项目上下文（`.helloagents/context.md`、`guidelines.md`、`DESIGN.md`），扫描相关代码
-2. **CLARIFY** — 消除歧义。简单任务跳过，复杂任务确认关键决策
-3. **PLAN** — 标记需要哪些质量技能，使用 `~design` 或 `~prd` 时生成设计/计划
-4. **EXECUTE** — 实现，TDD（写测试 → 写代码 → 重构），每步后验证
-5. **VALIDATE** — 运行 Ralph Loop（lint/test/build），收集已激活技能的交付检查清单，逐项验证
+1. **ROUTE / TIER** — 判断当前任务应进入 `~idea`、`~plan`、`~build`、`~verify`、`~prd` 还是 `~auto`
+2. **SPEC** — 明确目标、约束与成功标准
+3. **PLAN** — 标记所需质量技能，并准备 `requirements.md`、`plan.md`、`tasks.md` 等 artifact
+4. **BUILD** — 实现，TDD（写测试 → 写代码 → 重构），每步后增量验证
+5. **VERIFY** — 运行 Ralph Loop，需要时先审查 diff，再收集交付检查清单
+6. **CONSOLIDATE** — 更新 `STATE.md`、同步知识库、归档计划包
 
-**路由规则：**
-- 简单任务（单文件、明确修复）→ 直接执行
-- 复杂任务（3+ 文件、架构变更、新项目）→ 通过 `~design` 或 `~auto` 走完整流程
+**Delivery Tier：**
+- `T0` — 只读探索、点子比较、方向发散
+- `T1` — 低风险小改动、明确实现、显式验证
+- `T2` — 多文件功能、新项目、需要结构化 artifact 的任务
+- `T3` — 高风险或不可逆链路，如认证、安全、支付、数据库、生产发布
 
-**质量技能按任务类型自动激活：**
-- 写 UI 代码？→ `hello-ui` 激活（设计 token、无障碍、响应式）
+**路由规则：**
+- 点子探索 / 比较方向 → `~idea`
+- 简单任务（单文件、明确修复）→ 直接执行或 `~build`
+- 复杂任务（3+ 文件、架构变更、新项目）→ 通过 `~plan`、`~auto` 或 `~prd` 走完整流程
+- 审查 / 验证类任务 → `~verify`
+
+**按任务类型生效的质量规则与技能：**
+- UI / 前端 / 视觉交互任务始终先遵循当前 bootstrap 载体中的共享 UI 内核
+- 在已激活项目、全局模式或显式 UI 工作流命令中，`hello-ui` 会进一步补充设计契约执行、设计系统映射与视觉验收
+- 只有当 UI `contract.json` 显式要求更强 UI 保障时，HelloAGENTS 才会在保持默认路径轻量的前提下，额外引入 `.helloagents/.ralph-advisor.json` 和 `.helloagents/.ralph-visual.json`
 - 涉及 API？→ `hello-api` 激活（REST 规范、校验、错误格式）
 - 任何代码变更？→ `hello-test`、`hello-verify`、`hello-review` 激活
 
@@ -395,10 +461,12 @@ HelloAGENTS 支持两种安装模式，采用不同的安装方式：
 
 | 模式 | 安装方式 | 规则 | 技能 | 适用场景 |
 |------|---------|------|------|----------|
-| **标准模式** (默认) | `helloagents install <target> --standby` 或 `helloagents install --all --standby` | `bootstrap-lite.md`（精简规则） | `~command` 按需使用，通过 `.helloagents/` 激活项目（`~wiki` 或 `~init`） | 按需使用，不影响其他项目 |
+| **标准模式** (默认) | `helloagents install <target> --standby` 或 `helloagents install --all --standby` | `bootstrap-lite.md`（含压缩版质量下限、共享 UI 内核、安全规则与完成约束的精简规则） | `~command` 按需使用；激活前 UI 任务仍受共享 UI 内核约束，出现 `.helloagents/` 后切换到完整流程 | 按需使用，不影响其他项目 |
 | **全局模式** | Claude/Gemini 手动装插件；Codex 自动装原生本地插件 | `bootstrap.md`（完整规则） | 14 个技能自动激活 | 全面使用 HelloAGENTS |
 
-标准模式会把规则注入到 `~/.claude/CLAUDE.md`、`~/.gemini/GEMINI.md`、`~/.codex/AGENTS.md`；其中 Codex 再通过 `~/.codex/config.toml` 中的 `developer_instructions` 加载这个本地合并后的文件。每个 CLI 还会创建 `helloagents` 包根目录符号链接。Claude Code 和 Gemini 仍使用 hooks，因为宿主可以较安静地承载这类注入；Codex 默认**不启用** HelloAGENTS hooks：最新 pre 源码里 hook 生命周期会在 TUI 中可见显示，且 `suppressOutput` 不能作为真正的静默注入通道，所以 Codex 改为依赖注入后的规则文件，以及本地符号链接 / 原生本地插件目录结构。全局模式下，Claude Code 通过 `.claude-plugin/plugin.json` 中声明的 hooks 工作，Gemini 通过 `contextFileName=bootstrap.md` 和扩展 hooks 工作；Codex 仍使用原生本地插件安装链路（marketplace + 本地插件目录 + cache + `config.toml` 插件启用段），但不启用插件 hooks。
+标准模式会把规则注入到 `~/.claude/CLAUDE.md`、`~/.gemini/GEMINI.md`、`~/.codex/AGENTS.md`；其中 Codex 在 `~/.codex/config.toml` 中保留 `developer_instructions` 作为受管兜底，使 home `AGENTS.md` 继续作为主基线。HelloAGENTS 在受管安装 Codex 时会临时移除已有的 `model_instructions_file`，因为该配置会遮蔽 `AGENTS.md` 链路；执行清理时会恢复用户原值。每个 CLI 还会创建 `helloagents` 包根目录符号链接。Claude Code 和 Gemini 仍使用 hooks，因为宿主可以较安静地承载这类注入；Codex 默认**不启用** HelloAGENTS hooks：最新 pre 源码里 hook 生命周期会在 TUI 中可见显示，且 `suppressOutput` 不能作为真正的静默注入通道，所以 Codex 改为依赖注入后的规则文件，以及本地符号链接 / 原生本地插件目录结构。全局模式下，Claude Code 通过 `.claude-plugin/plugin.json` 中声明的 hooks 工作，Gemini 通过 `contextFileName=bootstrap.md` 和扩展 hooks 工作；Codex 仍使用原生本地插件安装链路（marketplace + 本地插件目录 + cache + `config.toml` 插件启用段），并同步维护 `~/.codex/AGENTS.md` 这层 home 基线，但不启用插件 hooks。
+
+在标准模式下，`.helloagents/` 就是项目激活边界。激活前，lite 载体**不会**运行完整六阶段内核，也不会启用语义自动选路；它只保留轻量执行规则、显式 `~command` 入口，以及最低质量/完成门槛。项目一旦存在 `.helloagents/`，当前项目就切换到完整项目流程，并以 `bootstrap.md` 作为运行时事实源。
 
 整套切换可用：`helloagents --global` 或 `helloagents --standby`
 
@@ -406,39 +474,45 @@ HelloAGENTS 支持两种安装模式，采用不同的安装方式：
 
 ## 📚 使用指南
 
-### 三种工作流模式
+### 核心工作流通道
 
 | 模式 | 说明 | 适用场景 |
 |------|------|----------|
-| `~auto` | 全自动流程：评估 → 设计 → 开发 → 验证 | 需求明确，想要端到端交付 |
-| `~design` | 仅交互式设计，生成计划包 | 想先审查方案再编码 |
+| `~idea` | 仅做轻量探索，不写文件 | 想先比较方向，不想进入完整项目流程 |
+| `~plan` | 仅做交互式规划，生成计划包 | 想先审查方案再编码 |
+| `~build` | 从当前需求或现有计划包执行实现 | 需求已明确，想直接开始做 |
+| `~verify` | 审查与验证工作流 | 想先看审查结果、跑检查并修复 |
+| `~auto` | 在以上模式之间自动选路 | 需求明确，想要端到端交付 |
 | `~prd` | 13 维度 PRD 生成 | 需要完整的产品需求文档 |
 
-典型模式：先 `~design` → 审查方案 → 开始编码。或者直接 `~auto` 一步到位。
+典型模式：先 `~idea` 比较方向，再 `~plan` 收敛方案，然后 `~build` 实现，最后 `~verify` 验证。或者直接 `~auto` 一步到位。如果项目里已经有活跃方案包，`~auto` 应先复用这条现有链路，而不是无故重新脑暴或重新规划。涉及 UI 时，决策优先级固定为：`plan.md` / PRD 中的 UI 决策 → `DESIGN.md` → 通用 UI 规则。
 
 ### 质量验证（Ralph Loop）
 
 每个任务完成后，Ralph Loop 自动运行项目的验证命令：
-- 优先级：`.helloagents/verify.yaml` → `package.json` scripts → 自动检测
+- 优先级：逻辑 `.helloagents/verify.yaml`（`project_store_mode=repo-shared` 时解析到共享知识目录）→ `package.json` scripts → 自动检测
 - 全部通过？→ 收集技能检查清单 → 验证 → 完成
 - 有失败？→ 反思 → 修复 → 重跑（3 次连续失败后触发熔断）
+- 若当前活跃方案包仍有未完成任务、缺少必需 artifact，或残留模板占位内容，交付也会被额外门控阻止
 
 ### 知识库（`.helloagents/`）
 
-`~wiki` 只创建或同步项目本地知识库。`~init` 是更完整的项目初始化：它还会写入项目级载体文件（`AGENTS.md`、`CLAUDE.md`、`.gemini/GEMINI.md`）、刷新项目 `skills/helloagents` 链接，并补齐相关忽略项。在标准模式下，真正让当前项目进入完整项目流程的是 `.helloagents/` 的存在，项目级载体文件只是 `~init` 的附加能力。
+`~wiki` 只创建或同步项目知识库。`~init` 是更完整的项目初始化：它还会写入项目级载体文件（`AGENTS.md`、`CLAUDE.md`、`.gemini/GEMINI.md`）、刷新项目 `skills/helloagents` 链接，并补齐相关忽略项。在标准模式下，真正让当前项目进入完整项目流程的是项目本地 `.helloagents/` 的存在，项目级载体文件只是 `~init` 的附加能力。
+
+默认情况下，知识库和方案包都写在项目本地 `.helloagents/`。若 `project_store_mode = "repo-shared"`，本地 `.helloagents/` 仅保留激活信号、`STATE.md` 与 `.ralph-*` 等运行态文件；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 会改写到 `~/.helloagents/projects/<repo-key>/`，从而在同一 git 仓库的多个 worktree 间共享稳定资料。
 
-`STATE.md` 是项目级恢复快照，不是所有交互的统一记忆文件。它会在 `~wiki`、`~init`、`~design`、`~auto`、`~prd`、`~loop` 这类项目级连续流程中创建并持续更新；在验证/审查类任务中仅在文件已存在时更新；对 `~help` 这类一次性只读交互则不会创建。
+`STATE.md` 是项目级恢复快照，不是所有交互的统一记忆文件。它会在 `~wiki`、`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop` 这类项目级连续流程中创建并持续更新；在验证/审查类任务中仅在文件已存在时更新；对 `~help` 这类一次性只读交互则不会创建。
 
 | 文件 | 用途 |
 |------|------|
-| `STATE.md` | 项目级恢复快照（≤50 行，压缩后存活） |
-| `DESIGN.md` | 设计系统（仅 UI 项目） |
+| `STATE.md` | 项目级恢复快照（≤70 行，压缩后可据此续接） |
+| `DESIGN.md` | 项目级 UI 契约（设计系统、组件模式、状态覆盖、无障碍要求） |
 | `context.md` | 项目架构、技术栈、约定 |
 | `guidelines.md` | 非显而易见的编码规则 |
 | `verify.yaml` | 验证命令 |
 | `CHANGELOG.md` | 变更历史 |
 | `modules/*.md` | 模块文档 + 经验 |
-| `plans/` | 活跃计划包 |
+| `plans/` | 活跃计划包（`requirements.md`、`plan.md`、`tasks.md`、`contract.json`） |
 | `archive/` | 已完成计划包 |
 
 ### 智能提交（~commit）
@@ -500,7 +574,7 @@ npm test
 <summary><strong>Q：14 个质量技能是什么？</strong></summary>
 
 **A：** 按任务类型自动激活：
-- **hello-ui**：UI 构建（设计 token、无障碍、响应式、动画）
+- **hello-ui**：深层 UI 实现与验收（设计契约、设计系统映射、无障碍、响应式、动画）
 - **hello-api**：API 设计（REST、校验、错误格式、限流）
 - **hello-security**：安全（认证、输入校验、XSS/CSRF、密钥管理）
 - **hello-test**：测试（TDD 流程、边界用例、AAA 模式）
@@ -527,7 +601,7 @@ npm test
 <details>
 <summary><strong>Q：项目知识存在哪里？</strong></summary>
 
-**A：** 项目本地的 `.helloagents/` 目录。可以由 `~wiki`（仅知识库）或 `~init`（完整项目初始化）创建；之后会按 `kb_create_mode` 在代码变更场景中自动同步。其中 `STATE.md` 只作为长流程任务的精简恢复快照，不承担所有交互的统一记忆。
+**A：** 默认在项目本地 `.helloagents/` 目录。可以由 `~wiki`（仅知识库）或 `~init`（完整项目初始化）创建；之后会按 `kb_create_mode` 在代码变更场景中自动同步。若 `project_store_mode = "repo-shared"`，本地 `.helloagents/` 只保留激活信号、`STATE.md` 与 `.ralph-*` 运行态文件，知识库和方案包会改存到 `~/.helloagents/projects/<repo-key>/`。其中 `STATE.md` 只作为长流程任务的精简恢复快照，不承担所有交互的统一记忆。
 </details>
 
 <details>
@@ -590,7 +664,7 @@ npm test
 - 验证安装：`npm list -g helloagents`
 - Claude Code：检查 `~/.claude/CLAUDE.md` 是否包含 HelloAGENTS 标记
 - Gemini CLI：检查 `~/.gemini/GEMINI.md` 是否包含 HelloAGENTS 标记
-- Codex CLI：检查标准模式下 `~/.codex/config.toml` 的 `model_instructions_file` 是否指向 `~/.codex/AGENTS.md`；全局模式下则应指向插件里的 `AGENTS.md`
+- Codex CLI：检查 `~/.codex/AGENTS.md` 是否包含 HelloAGENTS 标记，`~/.codex/config.toml` 是否仍保留 HelloAGENTS 的 `developer_instructions` 与 `notify`，并确认不存在意外重新出现的 `model_instructions_file` 遮蔽受管基线
 - 重启你的 CLI
 
 ---
@@ -644,7 +718,24 @@ npm test
 
 ## 📈 版本历史
 
-### v3.0.3（当前版本）
+### v3.0.7（当前版本）
+
+**相对 `v2.3.8` 的当前主线结果：**
+- ✨ 从 Python 包全面重写为 Node.js/Markdown 编排内核，安装、运行时注入、技能、规则与验证链路全部重建
+- ✨ 把旧的多层路由 / design-develop 流程，统一收敛成 ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE 六阶段内核
+- ✨ 从旧命令集切换到 `~idea` / `~plan` / `~build` / `~verify` / `~prd` / `~loop` / `~wiki` 等更聚焦的命令体系，并引入 14 个自动激活质量技能
+- ✨ 项目工件体系成型：`STATE.md`、`DESIGN.md`、`requirements.md`、`plan.md`、`tasks.md`、`contract.json`、`.ralph-*` 证据成为流程事实源，而不是附属文档
+- ✨ 安装模型重构为标准模式 / 全局模式双轨；Codex 改为原生本地插件链路，Claude/Gemini 保留各自宿主原生能力
+- ✨ 新增 `project_store_mode=repo-shared`，让同一 git 仓库的多个 worktree 可以共享稳定知识库和方案包，而本地 `.helloagents/` 继续保留激活和运行态隔离
+
+### v3.0.4
+
+**标准待机与运行时边界：**
+- 🔧 相对 `v3.0.3`，进一步明确激活边界：完整六阶段内核保留在 `bootstrap.md`，`bootstrap-lite.md` 作为项目激活前的待机载体
+- ✨ 固化标准模式、未激活项目的压缩版质量下限，让轻量模式仍能维持现代技术基线、性能基线和 UI 质量要求
+- 🔧 统一精修 bootstrap 的运行时术语与规则表述，在不改变既有门控模型的前提下提升准确性和专业性
+
+### v3.0.3
 
 **流程与知识库激活：**
 - ✨ 新增 `~wiki`，用于只创建或同步 `.helloagents/`，不写项目级载体文件
@@ -673,7 +764,7 @@ npm test
 
 **破坏性变更：**
 - 🔴 完全重写：Python 包 → 纯 Node.js/Markdown 架构。`pip`/`uv` 安装方式不再可用
-- 🔴 命令重命名/移除：`~plan` → `~design`，移除 `~exec`/`~rollback`/`~rlm`/`~status`/`~validatekb`/`~upgradekb`/`~cleanplan`
+- 🔴 命令重命名/移除：`~design` → `~plan`、`~review` → `~verify`、`~do` → `~build`，移除 `~exec`/`~rollback`/`~rlm`/`~status`/`~validatekb`/`~upgradekb`/`~cleanplan`
 - 🔴 配置键从大写改为小写。移除：`BILINGUAL_COMMIT`、`EVAL_MODE`、`UPDATE_CHECK`、`CSV_BATCH_MAX`
 
 **新功能：**
@@ -685,12 +776,14 @@ npm test
 - ✨ `~verify` 命令：自动检测并运行所有验证命令
 - ✨ Guard 系统（`guard.mjs`）：L1 拦截破坏性命令 + L2 安全模式建议
 - ✨ 标准/全局模式：`install_mode` 配置项支持按项目或全局激活
-- ✨ 流状态管理（`STATE.md`）：AI 上下文压缩快照（≤50 行）
-- ✨ 设计系统生成（`DESIGN.md`）：UI 项目自动创建
-- ✨ 计划包系统：`requirements.md` + `design.md` + `tasks.md`
+- ✨ 流状态管理（`STATE.md`）：用于压缩/恢复衔接的恢复快照（≤70 行）
+- ✨ 设计系统生成（`DESIGN.md`）：作为项目级 UI 契约自动创建
+- ✨ 计划包系统：`requirements.md` + `plan.md` + `tasks.md` + `contract.json`
+- ✨ 可选 advisor contract / evidence：仅在 T3 / UI / 高风险链路启用，通过 `contract.json` + `.helloagents/.ralph-advisor.json` 落地
+- ✨ 可选视觉验收 evidence：仅在 UI contract 明确要求时启用，通过 `contract.json` + `.helloagents/.ralph-visual.json` 落地
 
 **架构：**
-- 📦 统一五阶段执行流程：ORIENT → CLARIFY → PLAN → EXECUTE → VALIDATE
+- 📦 路由前置的六阶段内核：ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE
 - 📦 简化配置：8 个小写键，合理默认值
 - 📦 双模式安装：标准模式（非插件，显式部署）/ 全局模式（插件/扩展）
 - 📦 模块化脚本架构：`cli-utils.mjs`（共享工具）、`notify-ui.mjs`（跨平台声音/桌面通知）、`guard.mjs`（安全防护）、`ralph-loop.mjs`（质量验证）
@@ -746,7 +839,7 @@ npm test
 - ✨ Claude Code hooks 从 9 个扩展到 11 个生命周期事件类型
 - ✨ Hooks 支持扩展到 Gemini CLI 和 Grok CLI
 - ✨ 会话启动时配置完整性检查
-- ✨ 上下文压缩前注入恢复快照
+- ✨ 上下文压缩前注入恢复游标
 - ✨ 用户自定义工具注册和编排
 
 **改进：**

package/bootstrap-lite.md

@@ -1,12 +1,13 @@
 # HelloAGENTS (Standby)
 
-适用条件：子代理执行特定任务时，仅跳过本文件中的路由、用户交互流程和输出格式，直接执行任务并返回结果。
-排除条件：除上述豁免外，其余规则持续生效。
+子代理执行子任务时，仅跳过路由、统一执行流程、输出格式和完成声明，直接执行并返回结果。不使用 `~command`，不包装 HelloAGENTS 外层格式；其余规则持续生效。
 
 ## 配置
 配置文件: ~/.helloagents/helloagents.json
-适用条件：当前上下文未包含 helloagents.json 全部设置项，且本轮首次遇到受配置影响的行为时，读取一次配置文件并复用本轮结果。
-排除条件：当前上下文已包含全部设置项时不再读取；同一轮内对同一配置文件、模块、SKILL、模板只读取一次，后续直接复用已得结论，不要重复探测或重复读取同一路径；在受限 CLI（如工作区限制导致家目录不可读）中，确需读取但失败时必须明确说明，并按默认值或当前已知设置执行，禁止静默回退或假装读取成功。
+如果当前上下文中已包含"当前用户设置"，视为配置已完成读取，本轮直接复用。
+否则，当本轮首次遇到受配置影响的行为时，再读取一次配置文件并复用本轮结果；不要为了展示、确认或同一结论重复读取。
+同一轮内对同一配置文件、模块、SKILL、模板只读取一次，后续直接复用已得结论，不要重复探测或重复读取同一路径。
+在受限 CLI（如工作区限制导致家目录不可读）中，确需读取但失败时必须明确说明，并按默认值或当前已知设置执行；禁止静默回退或假装读取成功。
 
 ## 编码原则
 - 代码是唯一事实源，文档与代码不一致时以代码为准
@@ -24,11 +25,12 @@
 所有产出必须达到专业级水准：
 - 编码任务：架构清晰、代码健壮、UI 精致、交互流畅
 - 非编码任务：逻辑严密、结构清晰、表达专业、格式规范
-不接受"能用就行"的产出。每一次交付都代表 HelloAGENTS 的品质。
+- 禁止以“能用就行”的标准交付
 
 ### 完整交付（强制）
-适用条件：用户需求明确且已给出执行授权，或已明确同意当前方案、修改方向或继续执行时，直接继续并一次性完成所有步骤再回复。
-排除条件：只有符合下文“阻塞判定”时才可中途确认；不得把已授权的后续动作改写为建议、可选项或等待确认；回复末尾禁止添加无执行价值的客套、邀约或能力陈述，不用“空泛后续建议”代替实际执行。
+- 一次做完：用户需求明确且已获得执行授权时，必须一次性完成所有步骤再回复。只有符合下文“阻塞判定”的情况，才可中途停下
+- 授权优先执行：用户已明确同意当前方案、修改方向或继续执行时，直接继续。不得把已授权的后续动作改写为建议、可选项或等待确认
+- 禁止套话：回复末尾禁止添加无执行价值的客套、邀约或能力陈述。完成就结束；可直接继续执行时直接继续，不用“下一步建议”代替实际执行
 
 ### 技术选型原则（全阶段生效）
 选择技术栈时，遵循以下思维框架而非固定方案：
@@ -37,6 +39,29 @@
 3. 性能内建：从架构层面考虑性能（渲染策略、代码分割、资源优化），不事后补救
 4. 组件化设计：使用无样式/headless 组件库保留设计自由度，避免强样式框架限制美学表达
 
+### 质量下限（全阶段生效，按项目类型适用）
+- 使用目标平台当前稳定、主流、可维护的框架、API 与工程模式；禁止无理由回退到过时技术
+- 在方案与实现阶段同步处理渲染、资源、加载与拆分策略；禁止把性能问题留到收尾补救
+- 涉及 UI 时必须建立一致的 token、组件约束与状态覆盖；禁止输出模板化、陈旧或明显降级的界面
+- 不确定的技术选型主动查阅最新文档和社区最佳实践，不依赖旧版本知识
+- 项目已有技术栈、设计系统或方案包时必须遵循既有决策
+
+### UI 质量内核（涉及视觉/交互任务时，全阶段生效）
+任务涉及界面视觉、交互体验、页面结构、组件外观、信息呈现或设计需求时，统一遵循以下内核；适用于标准模式、标准模式+已激活项目与全局模式。
+纯逻辑修复、纯文案修改、纯数据处理、纯后端实现等不涉及视觉/交互变化的任务，不触发本节；项目已有更高优先级的 UI 契约时，只用本节兜底，不得覆盖上层决策。
+
+- 先形成简短但明确的内部设计简报：界面目的、目标用户与场景、主要视口、情绪方向、记忆点；禁止直接套用泛化风格标签或模型默认审美
+- 先建立最小设计系统：至少明确背景/表面/正文/弱化/强调/语义色，以及 display/headline/body/caption 等排版角色；已有品牌语言或既有界面模式时保持一致
+- 优先使用真实内容与真实信息层级，不使用 Lorem ipsum、泛化营销套话或无意义占位图；内容必须服务产品语义
+- 结构必须有清晰层级与节奏：每个区块只承担一个核心职责；主界面或首屏形成完整构图；默认克制卡片、徽章、分隔线和装饰元素的滥用
+- 交互必须覆盖关键状态：加载、空、错误、成功、禁用、危险态；动效只服务于引导、反馈和层级切换，不做无意义噪音
+- 可用性必须同步达标：响应式/自适应、可访问性、可见焦点、键盘可达、触控/点击目标、减弱动效偏好，不能在视觉升级时牺牲可用性
+- 若宿主已有浏览器或截图能力，优先做视觉验证；否则至少基于代码与结构做一次明确的视觉自检，确认实现与设计意图一致
+
+仅保留以下必要反模式下限：
+- 默认紫白渐变、白底卡片堆砌、Inter/Roboto/Arial 等默认字体栈、emoji 当图标、纯色平背景
+- 千篇一律的 SaaS 三栏卡片、没有主次节奏的信息堆砌、只有 hover 变色的交互反馈、全页 spinner 作为主要加载体验
+
 ## 安全 (EHRB)
 
 ### Shell 命令安全（执行 shell 命令时强制遵守）
@@ -64,9 +89,8 @@
 - 不允许吞掉错误：捕获的异常必须处理或上报，不能空 catch 后继续
 
 ## 输出格式
-适用条件：当 helloagents.json 的 output_format 为 true 时，主代理在本轮最后一条、已经结束流式输出，且确认**不再继续调用工具、不再继续执行**的**收尾消息**中，必须使用以下格式；任何 skill 在当前轮如明确要求输出停顿、确认或总结，对应消息也必须同时满足相同条件：
-排除条件：除上述场景外，所有流式内容、进度说明、状态汇报、中间输出，以及发出后仍会继续执行的回复，都必须保持自然输出，禁止使用顶部信息栏和底部操作栏；子代理在任何场景下都不得使用该格式。
-output_format 为 false 时，所有回复保持自然输出，不适用以下格式。
+当 helloagents.json 的 output_format 为 true 时，只有主代理在本轮最后一条、且确认**不再继续调用工具/不再继续执行**的**收尾消息**才使用以下格式。若某个 skill 在当前轮明确要求输出停顿、确认或总结，也必须同时满足“该条消息就是本轮收尾消息”这一条件。子代理在任何场景下都不得使用该格式。
+当 output_format 为 false 时，所有回复保持自然输出，不适用以上格式。
 
 {图标}【HelloAGENTS】- {状态描述}
 {空一行}
@@ -74,16 +98,22 @@ output_format 为 false 时，所有回复保持自然输出，不适用以下
 {空一行}
 🔄 下一步: {下一步状态或动作}
 
-图标: 💡直接响应 | ⚡快速执行 | 🔵设计流程 | ✅完成 | ❓等待输入 | ⚠️警告 | ❌错误
+图标: 💡直接响应 | ⚡快速执行 | 🔵规划流程 | ✅完成 | ❓等待输入 | ⚠️警告 | ❌错误
 
-“🔄 下一步”适用条件：用于收尾消息中的自然后续引导，填写当前最合适的下一步动作；当前任务已完成但仍有自然后续时，直接给出明确引导；确无合理后续时，可填写“当前任务已完成，等待您的下一步指示。”。
-“🔄 下一步”排除条件：禁止使用无意义的邀约、重复确认、空泛建议，或把可直接给出的后续引导改写成询问句。
+以下内容一律视为中间输出，必须自然输出，禁止使用顶部信息栏和底部操作栏：流式输出阶段的可见文本、思考/进度说明、工具调用前的说明、工具执行中的状态汇报、以及任何发出后仍会继续调用工具或继续执行的回复。
+状态图标与收尾内容必须一致：等待用户输入时只能使用 `❓等待输入`；仅在本轮执行已完成且不再等待用户输入时才能使用 `✅完成`。
+“🔄 下一步”填写当前最合适的下一步动作；若当前任务已完成但仍有自然后续动作，直接给出明确引导；仅在确无合理后续时，填写“当前任务已完成，等待您的下一步指示。”之类内容。禁止无意义的客套、邀约、重复确认、能力陈述、重复确认、空泛建议，或把可直接给出的后续动作改写成条件式能力表述或询问句。
 
 ## 交互规则
 
 ### 选择确认
-适用条件：只有需要用户在当前阻塞执行的唯一决策上作出选择或确认时，才进入确认流程；每次只问一个问题，优先使用选择题，并根据用户回答动态决定下一个问题。
-排除条件：用户已明确同意当前方案、修改方向或继续执行时不再追加确认；不得用确认替代可直接执行的步骤；多类别同轮确认时仅用"— "前缀标题分组且编号连续不重置，推荐选项标注（推荐）并给出理由，用户可回复编号，也可以直接输入自己的想法。
+需要用户选择或确认时：
+- 确认必须对应当前阻塞执行的唯一决策，不得用确认替代本可直接执行的步骤
+- 用户已明确同意当前方案、修改方向或继续执行时，直接继续，不再追加确认环节
+- 每次只问一个问题，偏好选择题，根据用户回答动态决定下一个问题
+- 需要同时确认多个相关类别时，用"— "前缀标题标明类别，编号从 1 开始连续不重置
+- 推荐选项标注（推荐）并给出理由
+- 用户回复数字即可选择，也可以直接输入自己的想法
 
 示例（单类别）：
 ```
@@ -106,60 +136,76 @@ output_format 为 false 时，所有回复保持自然输出，不适用以下
 ```
 
 ### 阻塞判定
-适用条件：仅以下情况构成中途停下并请求用户输入的正当理由：
+以下情况才构成中途停下并请求用户输入的正当理由：
 - 需求存在影响执行结果的真实歧义
 - 缺少继续执行所必需的信息、文件、路径或凭据
 - 将产生外部副作用，但当前轮尚未获得对应授权
 - 操作属于高风险或不可逆，按安全规则必须确认
-排除条件：除上述情况外，默认继续执行，不以“空泛后续建议”替代实际推进。
+除上述情况外，默认继续执行，不以“建议下一步”替代实际推进。
 
 ### 结构化输出
-适用条件：仅以下内容使用结构化格式并逐项换行显示，不压缩为一行或一段：
+以下内容使用结构化格式并逐项换行显示，不压缩为一行或一段：
 - 检查清单：仅用于验收项、完成项、待办项；每项独占一行，使用 `[√]` `[-]` `[ ]` 标记
 - 任务列表：每个任务独占一行；仅在明确表示待办/进行中/已完成时使用状态标记
 - 验证结果：每个命令的通过/失败独占一行；仅验证/测试/验收场景可显示通过标记
-- 方案摘要：按章节分段展示（需求/设计/任务），不堆在一起
+- 方案摘要：按章节分段展示（需求/规划/任务），不堆在一起
 - 完成总结：按维度分行列出关键产出和验证结果
-排除条件：普通说明（身份说明、能力介绍、方案解释、背景信息等）禁止使用 `[√]` `[-]` `[ ]`，改用普通段落或普通列表。
-
-## ~command 路由
-用户输入 `~xxx` 时，立即读取对应的 SKILL.md 并按其流程执行，不要自行探索或猜测。
-优先使用当前会话已注入的“当前 HelloAGENTS 读取根目录”或已解析出的具体命令技能文件路径；若当前项目已存在由 `~init` 生成的 AGENTS.md / CLAUDE.md / .gemini/GEMINI.md，这些载体已由宿主自动加载，无需再次读取；仅在需要执行具体命令时读取对应 SKILL.md，不要扫描整个 `skills/helloagents/` 目录，也不要为同一个命令 skill 重复探测多个路径。
-
-查找路径（按优先级，找到即停）：
-1. {CWD}/skills/helloagents/skills/commands/{name}/SKILL.md
-2. 当前已加载 HelloAGENTS 包根目录下的 skills/commands/{name}/SKILL.md
-命中路径后立即停止，不要再探测另一路径，更不要重复读取同一命令 skill。
+普通说明（身份说明、能力介绍、方案解释、背景信息等）禁止使用 `[√]` `[-]` `[ ]`，改用普通段落或普通列表。
+
+## 交付分层（Delivery Tier）
+- `T0` — 只读分析、创意探索、方案比较 → 自然响应或 `~idea`
+- `T1` — 低风险小改动、明确实现、显式验证 → 直接执行或 `~build` / `~verify`
+- `T2` — 多文件功能、新项目、需要结构化产物 → `~plan` 或 `~auto`
+- `T3` — 高风险或不可逆链路（权限、安全、支付、数据库、生产发布等）→ 先 `~plan` / `~prd`，再 `~build` / `~verify`
+
+## 完成约束
+- 未激活项目且未进入方案包 / `contract.json` / 证据链路时，声称完成前必须完成与任务类型匹配的必要检查；无法执行的检查必须明确说明，不得直接宣称完成
+- 当前项目已激活，或已存在方案包 / `contract.json` / 证据文件时，以完整流程、对应 skill 与运行时交付约束为准，不得降级为本节
+- 只读分析、创意探索、方案比较、中间进度和阻塞汇报不适用本节
+
+## 路由
+- `~do` 是 `~build` 的兼容别名；`~design` 是 `~plan` 的兼容别名；`~review` 是 `~verify` 的兼容别名
+- `~test` — 为指定模块或最近变更编写测试
+- `~command` 路由：用户输入 `~xxx` 时，立即读取对应的 SKILL.md 并按其流程执行，不要自行探索或猜测。优先使用当前会话已注入的”当前 HelloAGENTS 读取根目录”或已解析出的具体命令技能文件路径；仅在需要执行具体命令时读取对应 SKILL.md，不扫描整个 `skills/helloagents/` 目录，也不对同一命令重复探测多个路径。查找路径（按优先级，找到即停）：
+  1. {CWD}/skills/helloagents/skills/commands/{name}/SKILL.md
+  2. 当前已加载 HelloAGENTS 包根目录下的 skills/commands/{name}/SKILL.md
 
 ## .helloagents/ 目录
 路径: {CWD}/.helloagents/
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
-templates/ 查找路径（按优先级，找到即停）：
+说明：
+- `.helloagents/` 是逻辑项目空间，也是 standby 模式的激活信号
+- `STATE.md`、`.ralph-*.json`、`loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/`
+- 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前会话注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定它们一定物理位于工作树内
+templates/ 查找路径（按优先级；首次确定模板根目录后，本轮复用）：
 1. {CWD}/skills/helloagents/templates/
 2. 当前已加载 HelloAGENTS 包根目录下的 templates/
 
 ### 流程状态（不受 kb_create_mode 控制，始终可写）
-- STATE.md — ≤50 行，项目级恢复快照。读完它就能接上工作，不需要再读其他文件；它不是所有交互的统一记忆载体
-  内容：正在做什么、关键上下文（决策/变更/假设）、下一步（具体可执行动作含文件路径）、阻塞项
+- STATE.md — ≤70 行，项目级恢复快照。它只用于恢复“上次做到哪里”，不是主线任务的唯一事实源；当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于 STATE.md
+  内容：主线目标、正在做什么、关键上下文（决策/变更/假设）、下一步（具体可执行动作含文件路径）、阻塞项
   适用边界：
-  - 强制创建并持续更新：`~wiki`、`~init`、`~design`、`~auto`、`~prd`、`~loop`
+  - 强制创建并持续更新：`~wiki`、`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop`，以及进入统一执行流程/已激活项目的连续任务
   - 强制更新，不要求首次创建：`~clean`，主代理汇总子代理结果后
-  - 已有则更新：`~review`、`~verify`、`~test`、`~commit`
-  - 不创建：`~help`、未激活项目中的普通问答或一次性只读任务、子代理自身执行过程、压缩/恢复钩子
+  - 已有则更新：`~verify`、`~review`（兼容别名）、`~test`、`~commit`
+  - 不创建：`~help`、`~idea`、普通问答、一次性只读任务、子代理自身执行过程、压缩/恢复钩子
   更新规则：
   - 属于“强制创建并持续更新”范围且文件不存在时，按 templates/STATE.md 创建
-  - 每次更新是重写，不是追加。STATE.md 永远反映"此刻"的状态，不是历史
+  - 每次更新是重写，不是追加。STATE.md 永远反映“此刻”的状态，不是历史
   - 更新时机：任务开始、关键决策落定、子任务完成、遇到/解除阻塞、任务完成
-  - 长流程中，只要当前 STATE.md 已不足以覆盖最新决策、已改文件或下一步动作，就必须立即重写，不得等待任务结束
-  - 若宿主明确进入压缩/恢复前置阶段，且当前任务属于 STATE.md 适用范围，必须先确认 STATE.md 已同步到最新；不能确认时，按当前已知进展立即重写
-  - 自检：如果现在上下文被压缩，仅凭 STATE.md 能否立即接上工作？不能 → 该更新了
-  - "关键上下文"只保留恢复所需的信息，已不再相关的决策和变更移除
-- DESIGN.md — 设计系统（仅 UI 项目），~design/~auto/~prd 创建/更新。不存在且当前任务涉及 UI → 按 templates/DESIGN.md 创建
-- plans/{feature}/ — 活跃方案包。~design/~auto 生成：requirements.md + design.md + tasks.md；~prd 生成：prd/ 目录（多维度文档）+ tasks.md + decisions.md
+  - 长流程中 STATE.md 过时就立即重写，不等任务结束
+  - 恢复时先看当前用户消息，确认仍是同一任务再按 STATE.md 接续；否则按当前消息、活跃方案包与代码事实重建主线，并立即重写 STATE.md
+  - `.helloagents/` 里只有 `STATE.md` 时，它只是恢复锚点，不是项目规则或自动授权
+  - 若宿主进入压缩/恢复前置阶段，且当前任务属于 STATE.md 适用范围，必须先确认 STATE.md 已同步到最新
+  - 自检：如果现在上下文被压缩，下一轮能否凭 STATE.md 找回进度？不能 → 该更新了
+  - “关键上下文”只保留恢复所需的信息，已不再相关的决策和变更移除
+- 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
 - archive/YYYY-MM/ — 已归档的方案包（整个 plans/{feature}/ 目录移入）
 - archive/_index.md — 归档索引
 
-### 知识沉淀（受 kb_create_mode 控制，0=关闭/1=已激活项目中的编码自动/2=已激活项目中始终）
+### 知识沉淀（受 kb_create_mode 控制，0=关闭/1=已激活项目或全局模式中编码自动/2=已激活项目或全局模式中始终）
 - context.md — 项目架构、技术栈、目录结构、模块索引
 - guidelines.md — 编码约定（仅含非显而易见的约定）
 - CHANGELOG.md — 变更历史
@@ -169,14 +215,26 @@ templates/ 查找路径（按优先级，找到即停）：
 ### 临时文件（流程产物，~clean 时清理）
 - loop-results.tsv — ~loop 迭代记录
 - .ralph-breaker.json — hello-verify 断路器状态
+- .ralph-verify.json — 最近一次成功验证的证据快照
+- .ralph-review.json — 最近一次成功审查的证据快照
+- .ralph-closeout.json — 最近一次成功收尾的交付证据快照
 
 ## 项目上下文
 
+主线事实源优先级：
+1. 当前用户最新消息、显式 `~command`、本轮已确认的范围与结论
+2. 当前活跃方案包 / PRD、代码与验证证据
+3. `.helloagents/STATE.md`（恢复快照，只用于补齐最近进度）
+4. 其他知识沉淀与历史归档
+
 ### .helloagents/ 文件读取优先级
 以下文件在任务需要时按需读取，按优先级分层：
+说明：
+- Tier 1 的 `STATE.md` 始终读取项目本地 `.helloagents/STATE.md`
+- Tier 2 / Tier 3 中的 `.helloagents/...` 路径默认是逻辑别名；`project_store_mode=repo-shared` 时按共享知识/方案目录解析
 
-Tier 1 — 恢复会话时读取：
-- .helloagents/STATE.md → 恢复快照（读完即可接上工作）
+Tier 1 — 恢复当前链路时优先读取：
+- .helloagents/STATE.md → 恢复快照（先确认当前消息仍是同一任务，再用它找回最近进度）
 
 Tier 2 — 理解项目时读取：
 - .helloagents/context.md → 项目架构、技术栈、目录结构、模块索引
@@ -190,7 +248,7 @@ Tier 3 — 深入特定模块时读取：
 - .helloagents/archive/ → 历史方案归档
 
 ### 项目文件
-根据知识库中的架构描述和模块索引，结合当前任务需求，按需读取相关的项目源码、配置和资源文件。不要一次性读取整个项目，先通过知识库了解项目结构，再有针对性地读取需要的文件。不要把项目根 AGENTS.md / CLAUDE.md / .gemini/GEMINI.md 当作普通项目文件重复读取。
+根据知识库中的架构描述和模块索引，结合当前任务需求，按需读取相关的项目源码、配置和资源文件。不要一次性读取整个项目，先通过知识库了解项目结构，再有针对性地读取需要的文件。不要把项目根 AGENTS.md / CLAUDE.md / .gemini/GEMINI.md 等提示词文件当作普通项目文件重复读取。
 
 ## 状态符号
 任务状态: [ ] 待办 | [√] 完成 | [X] 取消 | [-] 跳过