helloagents 3.0.7 → 3.0.8-beta.1

package/skills/hello-ui/SKILL.md

@@ -1,28 +1,28 @@
 ---
 name: hello-ui
-description: 已进入显式 UI 工作流、已激活项目的视觉变更、设计系统改造或需要视觉验收时使用；在通用 UI 内核之上补充项目契约消费、设计系统映射与视觉验证。
+description: 已进入显式 UI 工作流、已激活项目的视觉变更、设计系统改造或需要视觉验收时使用；在通用 UI 基线之上补充项目契约消费、设计系统映射与视觉验证。
 ---
 
-本 skill 不是 UI 质量的唯一来源。当前已加载 bootstrap 中的 UI 质量内核负责所有 UI 任务的基础水准；本 skill 在显式 UI 工作流和深度 UI 任务中，补充更强的契约执行、实现映射与视觉验收。
-`.helloagents/` 在本 skill 中表示逻辑项目空间：`.ralph-*.json` 等运行态证据保持项目本地；若 `project_store_mode=repo-shared`，`DESIGN.md` 与方案包按当前会话注入的项目知识/方案目录解析。
+本 skill 不是 UI 质量的唯一来源。当前已加载 bootstrap 中的 UI 质量基线负责所有 UI 任务的基础水准；本 skill 在显式 UI 工作流和深度 UI 任务中，补充更强的契约执行、实现映射与视觉验收。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`.ralph-*.json` 等运行态证据保持项目本地；若 `project_store_mode=repo-shared`，`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 适用边界
 已进入显式 UI 规划/实现/验证路径，或当前项目已激活且任务涉及整页新建、跨多个组件的视觉重做、设计系统改造、需要截图验收的界面任务时，读取本 skill。
-标准模式未激活项目中的普通 UI 请求，仍只受当前 bootstrap 的 UI 内核约束；修复 bug、调整文案、改业务逻辑等不涉及视觉变更的任务，不读取本 skill。在已有设计系统中工作时，保留已建立的模式、结构和视觉语言。
+标准模式未激活项目中的普通 UI 请求，仍只受当前 bootstrap 的 UI 质量基线约束；修复 bug、调整文案、改业务逻辑等不涉及视觉变更的任务，不读取本 skill。在已有设计系统中工作时，保留已建立的模式、结构和视觉语言。
 
 ## 设计契约优先级
 进入 UI 相关的规划、实现、验证时，按以下顺序做设计决策：
 1. 当前活跃方案包 `plan.md` 或 PRD 中已确认的 UI 决策
-2. 逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析）
+2. `.helloagents/DESIGN.md`（按当前项目存储模式解析）
 3. 本 skill 的通用规则
-缺少上层 artifact 时，才直接依赖下层规则；不得用通用审美覆盖已确认的项目契约。
+缺少上层产物时，才直接依赖下层规则；不得用通用审美覆盖已确认的项目契约。
 
 ## 深层职责
 - 消费上游契约：把 `plan.md` / PRD / `DESIGN.md` 中已确认的 UI 决策视为强约束，而不是建议
-- 消费可选 UI contract：若 `contract.json` 启用 `ui.styleAdvisor`，复用 `.helloagents/.ralph-advisor.json` 留下设计方向复查证据；若启用 `ui.visualValidation`，用 `.helloagents/.ralph-visual.json` 留下视觉验收证据
+- 消费可选 UI 契约：若 `contract.json` 启用 `ui.styleAdvisor`，复用 `.helloagents/.ralph-advisor.json` 留下设计方向复查证据；若启用 `ui.visualValidation`，用 `.helloagents/.ralph-visual.json` 留下视觉验收证据
 - 映射到代码结构：明确 token 放在哪里、组件边界如何划分、状态组件如何组织、动效与主题如何落地
 - 做视觉验收闭环：优先使用截图/浏览器工具做桌面与移动端检查；没有工具时也要完成结构化视觉自检
-- 回写稳定决策：只把跨 feature 稳定成立的设计系统规则同步回逻辑 `.helloagents/DESIGN.md`，不要把一次性页面细节全部写成项目级契约
+- 回写稳定决策：只把跨 feature 稳定成立的设计系统规则同步回 `.helloagents/DESIGN.md`（按当前项目存储模式解析），不要把一次性页面细节全部写成项目级契约
 
 ## 深层设计 brief（编码前必须落定）
 
@@ -37,9 +37,9 @@ description: 已进入显式 UI 工作流、已激活项目的视觉变更、设
 7. 真实内容：使用真实文案、产品信息、项目上下文，不使用 Lorem ipsum 或泛化占位符。真实内容帮助做出更贴合上下文的设计决策。
 
 执行顺序要求：
-- 已激活项目且存在逻辑 `.helloagents/DESIGN.md` 时，进入真实 UI 任务先读取它，再展开方案或实现
+- 已激活项目且存在 `.helloagents/DESIGN.md`（按当前项目存储模式解析）时，进入真实 UI 任务先读取它，再展开方案或实现
 - 已通过方案包或 PRD 确认设计方向的，按确认方向执行，并以 `plan.md` / PRD 中的 UI 决策为最高优先级
-- 已激活项目且当前任务属于整页新建、设计系统改造、或跨多个组件的视觉重做，但逻辑 `.helloagents/DESIGN.md` 不存在时，先按 `templates/DESIGN.md` 创建最小设计契约（至少覆盖产品表面、设计 token、组件与模式、状态覆盖、无障碍要求、禁止事项），再继续大规模实现
+- 已激活项目且当前任务属于整页新建、设计系统改造、或跨多个组件的视觉重做，但 `.helloagents/DESIGN.md`（按当前项目存储模式解析）不存在时，先按 `templates/DESIGN.md` 创建最小设计契约（至少覆盖产品表面、设计 token、组件与模式、状态覆盖、无障碍要求、禁止事项），再继续大规模实现
 - 未经方案包且无 `DESIGN.md` 的任务，基于以上规则，结合任务需求和项目上下文做出设计决策并执行
 
 ## 实现映射（进入编码前必须明确）
@@ -218,8 +218,8 @@ Hero 区域：
 1. 截图渲染结果（桌面 + 移动端视口）
 2. 对照设计原则审查截图：构图是否完整？品牌感是否到位？配色是否一致？
 3. 发现问题 → 修复 → 再截图验证
-4. 若当前 contract 要求 `ui.visualValidation.required=true`，调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`，记录 `reason`、`tooling`、`screensChecked`、`statesChecked`、`status` 与 `summary`
+4. 若当前契约要求 `ui.visualValidation.required=true`，调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`，记录 `reason`、`tooling`、`screensChecked`、`statesChecked`、`status` 与 `summary`
 5. 确认截图与设计意图一致后才能报告完成
 
 无浏览器工具时，仔细审查生成的代码，确认样式、布局、动效的实现与设计意图一致。
-若当前 contract 要求 `ui.visualValidation.required=true`，仍需用结构化结论调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`，并明确标记所用 tooling 与已检查的 screens / states。
+若当前契约要求 `ui.visualValidation.required=true`，仍需用结构化结论调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`，并明确标记所用 tooling 与已检查的 screens / states。

package/skills/hello-verify/SKILL.md

@@ -4,7 +4,7 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 ---
 
 声称完成之前，必须有验证证据。
-`.helloagents/` 在本 skill 中表示逻辑项目空间：`.ralph-review.json`、`.ralph-visual.json`、`.ralph-closeout.json` 等交付证据保持项目本地；若 `project_store_mode=repo-shared`，`verify.yaml`、方案包与 `DESIGN.md` 按当前会话注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`.ralph-review.json`、`.ralph-visual.json`、`.ralph-closeout.json` 等交付证据保持项目本地；若 `project_store_mode=repo-shared`，`verify.yaml`、方案包与 `DESIGN.md` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 
@@ -65,7 +65,7 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 - package.json 中的 lint/test/typecheck 脚本
 - pyproject.toml 中的 ruff/mypy/pytest
 
-## 交付检查清单门控
+## 交付检查清单把关
 
 验证命令全部通过后，还需要：
 这些标记只用于交付检查清单、验收记录和验证结果，不用于普通说明、方案解释或进度汇报。
@@ -75,7 +75,8 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 4. 有未通过项 → 修复 → 重新运行验证循环
 5. 若当前存在方案包并准备最终收尾，优先调用 `scripts/closeout-state.mjs write` 写 `.helloagents/.ralph-closeout.json`，记录 `requirementsCoverage` 与 `deliveryChecklist` 两项结论；两项都必须包含 `status`（`PASS` / `BLOCKED`）和 `summary`
 6. 若当前方案包要求 `review-first`，必须先确认 `.helloagents/.ralph-review.json` 已通过 `scripts/review-state.mjs write` 写成最新结构化证据；不要把审查自然语言消息直接当成交付证据
-7. 若 `contract.json` 中 `ui.visualValidation.required=true`，必须确认 `.helloagents/.ralph-visual.json` 已通过 `scripts/visual-state.mjs write` 写成最新结构化证据；若没有视觉 evidence，不得把本轮视为 UI 可交付
+7. 若 `contract.json` 中 `ui.visualValidation.required=true`，必须确认 `.helloagents/.ralph-visual.json` 已通过 `scripts/visual-state.mjs write` 写成最新结构化证据；若没有视觉验收证据，不得把本轮视为 UI 可交付
+8. 准备以本轮最终收尾消息报告完成时，先调用 `scripts/turn-state.mjs write` 写 `kind=complete`、`role=main`；若因阻塞判定等待输入或因前置条件缺失而停下，写 `kind=waiting` 或 `kind=blocked`，不要让运行时从自然语言消息里猜状态
 
 ## 需求追踪验证
 
@@ -85,8 +86,8 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 3. 确认非目标章节列出的内容确实没有被实现（防止范围蔓延）
 4. 若 tasks.md 中定义了“完成标准”，逐项确认每个任务的完成标准确实成立，不能只因为代码存在或命令通过就视为完成
 5. 若存在 `contract.json`，逐项确认其中的 `verifyMode`、reviewer / tester 关注边界都已被本轮验证覆盖
-6. 若 `contract.json` 中 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，额外确认 `.helloagents/.ralph-advisor.json` 已存在且结论为 clean；若没有 advisor artifact，不得把本轮视为可交付
-7. 若 `contract.json` 中 `ui.visualValidation.required=true`，额外确认 `.helloagents/.ralph-visual.json` 已存在、覆盖要求的关键 screens / states，且结论为 `PASS`；若没有 visual artifact，不得把本轮视为 UI 可交付
+6. 若 `contract.json` 中 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，额外确认 `.helloagents/.ralph-advisor.json` 已存在且结论为 clean；若没有 advisor 证据，不得把本轮视为可交付
+7. 若 `contract.json` 中 `ui.visualValidation.required=true`，额外确认 `.helloagents/.ralph-visual.json` 已存在、覆盖要求的关键 screens / states，且结论为 `PASS`；若没有视觉验收证据，不得把本轮视为 UI 可交付
 8. 发现遗漏 → 补充实现 → 重新验证
 
 ## 反代理目标漂移 (APGD)

package/skills/helloagents/SKILL.md

@@ -5,10 +5,11 @@ description: 每次对话开始时使用 — 建立质量驱动工作流，通
 
 # HelloAGENTS
 
-主代理触发或读取任意 skill 时，只有在该条消息是本轮最终收尾消息时，才按当前已加载 bootstrap 规则包装 HelloAGENTS 外层输出格式；任何 skill 若在当前轮明确要求输出停顿、确认或总结，对应消息也必须同时满足相同条件。
+主代理触发或读取任意 skill 时，只有在该条消息是本轮最终收尾消息时，才按当前已加载 bootstrap 规则包装 HelloAGENTS 外层输出格式；任何 skill 若在本轮明确要求输出停顿、确认或总结，对应消息也必须同时满足相同条件。
 子代理只豁免路由与收尾要求，直接执行任务；安全、质量、验证和失败处理规则仍持续生效，且不得包装 HelloAGENTS 外层输出格式。所有流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都不得触发外层格式。
+主代理在本轮最终收尾前，如要报告“已完成 / 等待输入 / 本轮阻塞”，必须先调用 `scripts/turn-state.mjs write` 写机器可读的 turn-state；不要让运行时再从自然语言或图标反推状态。子代理不得写 turn-state。
 
-`.helloagents/` 在所有 skill 中都先视为逻辑项目空间：项目本地 `.helloagents/` 继续承担激活信号、`STATE.md` 与 `.ralph-*.json` 等运行态文件；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 改按当前会话注入的“当前项目存储”/“项目知识/方案目录”解析，不要假定它们一定物理存在于工作树内。
+`.helloagents/` 在所有 skill 中都统一按项目级存储路径理解：项目本地 `.helloagents/` 继续承担激活信号、`STATE.md` 与 `.ralph-*.json` 等运行态文件；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析，不要假定这些文件一定实际位于当前工作树中。
 
 ## 三重质量保障
 
@@ -22,23 +23,23 @@ description: 每次对话开始时使用 — 建立质量驱动工作流，通
 ### 流程纪律（执行时）
 - 执行 command skill 时，公共阶段边界以当前已加载 bootstrap 为准；command skill 只补充该命令的专属动作和边界
 - 统一执行流程的六个阶段（ROUTE/TIER→SPEC→PLAN→BUILD→VERIFY→CONSOLIDATE）不可跳过
-- 所有 UI 任务先受当前 bootstrap 的 UI 质量内核约束；已激活项目或显式 UI 工作流中的设计约束优先级固定为：当前 `plan.md` / PRD UI 决策 → 逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析） → `hello-ui` 深层规则
-- 方案包存在 `contract.json` 时，验证分流、reviewer / tester 关注边界、可选 style advisor / visual validation 与交付门控优先按它执行，不再从自然语言总结里回推
+- 所有 UI 任务先受当前 bootstrap 的 UI 质量基线约束；已激活项目或显式 UI 工作流中的设计约束优先级固定为：当前 `plan.md` / PRD UI 决策 → `.helloagents/DESIGN.md`（按当前项目存储模式解析） → `hello-ui` 深层规则
+- 方案包存在 `contract.json` 时，验证分流、reviewer / tester 关注边界、可选 style advisor / visual validation 与交付检查优先按它执行，不再从自然语言总结里回推
 - 因阻塞判定而必须等待用户输入时，遵循当前 bootstrap 的等待输入规则，不得把等待输入包装成完成态
 - ~plan 的需求澄清与方案收敛不可跳过，不可一个问题就出方案
 - ~prd 的维度探索不可跳过，每个激活维度必须经过讨论或用户明确跳过
 - ~auto 的复杂度判断不可省略
 - hello-verify 的验证铁律：没有运行验证 = 不能说完成
 
-### 检查清单门控（完成时）
-任务完成后，必须执行以下门控流程（详见 hello-verify）：
+### 检查清单把关（完成时）
+任务完成后，必须执行以下检查流程（详见 hello-verify）：
 1. 运行验证命令（lint/test/build）→ 循环直到通过
 2. 收集所有已激活技能的交付检查清单
 3. 逐项验证。仅在交付检查清单、验收记录和验证结果中使用 [√] / [-] 标记，并附带证据；普通说明、方案解释、状态汇报不用这些标记
 4. 有未通过项 → 修复后重新检查
 5. 全部通过 → 才能报告完成
 
-未经门控就报告完成 = 违反 HelloAGENTS 核心规则。
+未经过完整检查就报告完成 = 违反 HelloAGENTS 核心规则。
 
 ## 技能加载规则（渐进式披露）
 
@@ -63,14 +64,18 @@ Layer 3 — 资源文件（技能内引用时读取）：
 
 读取其他技能时，按以下路径查找，找到即停，不自行猜测或遍历其他路径。
 
+路径定义：`{HELLOAGENTS_READ_ROOT}` = 本轮已确定的 HelloAGENTS 读取根目录
+先确定当前技能根目录：
+- 优先使用当前上下文中已注入的“本轮 HelloAGENTS 读取根目录”
+- 若当前上下文未注入，则将当前宿主 home 目录下的 `helloagents/` 链接作为 `{HELLOAGENTS_READ_ROOT}`
+- 已激活项目或全局模式下，技能是否需要使用由当前已加载 AGENTS 规则决定；不要因此额外探测项目目录里的 HelloAGENTS skills 路径
+
 ### hello-* 技能
-1. `{CWD}/skills/helloagents/skills/{技能名}/SKILL.md`
-2. 当前已加载 HelloAGENTS 包根目录下的 `skills/{技能名}/SKILL.md`
+读取 `{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.md`
 
 ### ~command 命令技能
-1. `{CWD}/skills/helloagents/skills/commands/{name}/SKILL.md`
-2. 当前已加载 HelloAGENTS 包根目录下的 `skills/commands/{name}/SKILL.md`
-命中路径后立即停止，不要重复读取同一命令 skill。
+若当前上下文已解析出具体命令技能文件路径，直接使用它；否则读取 `{HELLOAGENTS_READ_ROOT}/skills/commands/{name}/SKILL.md`
+确定路径后立即停止，不要重复读取同一命令 skill。
 
 ## 技能索引（仅元数据）