helloagents 3.0.29 → 3.0.31

package/skills/commands/verify/SKILL.md

@@ -12,13 +12,13 @@ Trigger: ~verify [scope]
    - 若当前上下文中已注入“当前工作流约束”或“当前推荐下一命令”，先服从它
    - 即使命令通过，也不能越过当前方案包边界：不完整方案包不能视为可信交付记录，未闭合方案包不能被整体报告为已完成
    - 当推荐路径已进入 `~verify` / 收尾时，优先把本命令用于审查、验真和交付收尾
-   - 若当前存在活跃方案包，先读取 `requirements.md`、`plan.md`、`tasks.md`、`contract.json`，把它们当作本轮验证契约；不要只看命令结果
-   - 若本轮运行在 Codex active goal 下，按 active goal 关联方案包和 `state_path` 复核范围；`/goal` 只负责续跑，不改变验证契约
-   - 若 `contract.json` 声明 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，则本轮还必须补齐当前会话 `artifacts/advisor.json`；advisor / style advisor 都是可选能力，不是默认常驻步骤
-   - 若 `contract.json` 声明 `ui.visualValidation.required=true`，则本轮还必须补齐当前会话 `artifacts/visual.json`；视觉验收优先用截图/浏览器工具，没有工具时才降级为结构化代码级自检
+   - 若当前存在活跃方案包，先读取 `requirements.md`、`plan.md`、`tasks.md`、`contract.json`，把它们当作当前验证契约；不要只看命令结果
+   - 若当前运行在 Codex active goal 下，按 active goal 关联方案包和 `state_path` 复核范围；`/goal` 只负责续跑，不改变验证契约
+   - 若 `contract.json` 声明 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，则本次验证还必须补齐当前会话 `artifacts/advisor.json`；advisor / style advisor 都是可选能力，不是默认常驻步骤
+   - 若 `contract.json` 声明 `ui.visualValidation.required=true`，则本次验证还必须补齐当前会话 `artifacts/visual.json`；视觉验收优先用截图/浏览器工具，没有工具时才降级为结构化代码级自检
 1. 先决定验证分流：
    - 若当前上下文中已注入“验证分流”，先按该分流执行
-   - 用户显式使用 `~review` 时，即使本轮没有注入分流，也按审查优先起步
+   - 用户显式使用 `~review` 时，即使当前没有注入分流，也按审查优先起步
    - 若没有注入分流、也不是 `~review`，默认先做全量验证；执行中一旦发现高风险流程、关键权限/配置/迁移/发布边界或明显未覆盖的风险点，立即补做 `hello-review`
 2. 审查优先模式：
    - 获取变更范围：无参数默认未提交变更；`staged` 代表暂存区；指定文件/目录则只审查对应范围

package/skills/commands/wiki/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ~wiki
-description: 初始化或同步项目知识库（仅 `.helloagents/`）
+description: 初始化或同步项目知识库（与 ~init 同义）
 policy:
   allow_implicit_invocation: false
 ---

package/skills/hello-review/SKILL.md

@@ -32,7 +32,7 @@ description: 审查代码变更、检查 PR、review 代码质量，或用户要
 - 审查结束时必须单独给出一行“审查结论：...”
 - 若发现阻塞问题，结论中明确写出存在问题，并在正文中为每个问题附文件定位
 - 若未发现阻塞问题，明确写“审查结论：未发现阻塞问题。”
-- 若当前项目已激活，且本轮审查结果需要进入后续交付检查或收尾，审查结论确定后立即调用 `scripts/review-state.mjs write` 写当前会话 `artifacts/review.json`
+- 若当前项目已初始化，或当前审查结果需要进入后续交付检查或收尾，审查结论确定后立即调用 `scripts/review-state.mjs write` 写当前会话 `artifacts/review.json`
 - `artifacts/review.json` 必须使用结构化字段记录：`outcome`（`clean` / `findings`）、`conclusion`、`findings`、`fileReferences`
 - 不要依赖“审查结论：...”这行让运行时再从自然语言里猜机器结论；这行只服务于人类阅读
 

package/skills/hello-subagent/SKILL.md

@@ -18,7 +18,7 @@ description: 使用子代理执行任务、并行开发、分派工作时使用
 
 ## 协调规范
 - 使用子代理时，主代理作为控制器跟踪进度
-- 主代理只有在本轮最终收尾时才可使用 HelloAGENTS 外层输出格式。
+- 主代理只有在当前对话的最终回复中才可使用 HelloAGENTS 外层输出格式。
 - 团队协作中的进度与状态汇报都属于中间输出，不得包装 HelloAGENTS 外层输出格式。
 - 子代理不得调用 `helloagents-turn-state write` 代替主代理写完成态或等待态；需要运行时状态信号时只由主代理写入
 - 子代理完成后执行双阶段审查：

package/skills/hello-ui/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: hello-ui
-description: 已进入显式 UI 工作流、全局模式中的 UI 任务、已激活项目的视觉变更、设计系统改造或需要视觉验收时使用；在通用 UI 基线之上补充项目契约执行、设计系统映射与视觉验证。
+description: 已进入显式 UI 工作流、全局模式中的 UI 任务、已初始化项目的视觉变更、设计系统改造或需要视觉验收时使用；在通用 UI 基线之上补充项目契约执行、设计系统映射与视觉验证。
 ---
 
 本 skill 不是 UI 质量的唯一来源。当前已加载的 HelloAGENTS UI 质量基线负责所有 UI 任务的基础水准；本 skill 在显式 UI 工作流和复杂 UI 任务中，补充更明确的契约执行、实现映射与视觉验收。
 `.helloagents/` 在本 skill 中统一按项目级存储路径理解：会话证据使用当前 `state_path` 所在目录下的 `artifacts/*.json`；若 `project_store_mode=repo-shared`，`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 适用边界
-已进入显式 UI 规划/实现/验证路径、全局模式中的 UI 任务，或当前项目已激活且任务涉及整页新建、跨多个组件的视觉重做、设计系统改造、需要截图验收的界面任务时，读取本 skill。
-标准模式未激活项目中的普通 UI 请求，仍只受当前已加载的 HelloAGENTS UI 质量基线约束；修复 bug、调整文案、改业务逻辑等不涉及视觉变更的任务，不读取本 skill。在已有设计系统中工作时，保留已建立的模式、结构和视觉语言。
+已进入显式 UI 规划/实现/验证路径、全局模式中的 UI 任务，或当前已初始化项目且任务涉及整页新建、跨多个组件的视觉重做、设计系统改造、需要截图验收的界面任务时，读取本 skill。
+标准模式、且项目未初始化时的普通 UI 请求，仍只受当前已加载的 HelloAGENTS UI 质量基线约束；修复 bug、调整文案、改业务逻辑等不涉及视觉变更的任务，不读取本 skill。在已有设计系统中工作时，保留已建立的模式、结构和视觉语言。
 
 ## 设计契约优先级
 进入 UI 相关的规划、实现、验证时，按以下顺序做设计决策：
@@ -37,9 +37,9 @@ description: 已进入显式 UI 工作流、全局模式中的 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` 的任务，基于以上规则，结合任务需求和项目上下文做出设计决策并执行
 
 ## 实现映射（进入编码前必须明确）
@@ -47,7 +47,7 @@ description: 已进入显式 UI 工作流、全局模式中的 UI 任务、已
 - 组件边界：哪些能力做成复用组件，哪些只保留在当前页面；避免把一次性布局抽成错误的“通用组件”
 - 状态矩阵：当前界面涉及的加载、空、错误、成功、禁用、危险态分别如何呈现
 - 主题与适配：深浅色、响应式断点或平台尺寸、安全区、最小窗口/最小视口如何处理
-- 验收证据：本轮需要检查的关键视口、关键状态和关键截图点是什么
+- 验收证据：本次需要检查的关键视口、关键状态和关键截图点是什么
 
 ## 结构性规则
 

package/skills/hello-verify/SKILL.md

@@ -75,11 +75,11 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 2. 逐项确认每个检查项，标记 [√] 并附带证据（如：`src/api.ts:42` 使用了参数化查询）
 3. 不适用的项标记 [-] 并说明原因
 4. 有未通过项 → 修复 → 重新运行验证循环
-5. 若当前存在方案包并准备最终收尾，优先调用 `scripts/closeout-state.mjs write` 写当前会话 `artifacts/closeout.json`，记录 `requirementsCoverage` 与 `deliveryChecklist` 两项结论；两项都必须包含 `status`（`PASS` / `BLOCKED`）和 `summary`
+5. 若当前存在方案包并准备最终回复，优先调用 `scripts/closeout-state.mjs write` 写当前会话 `artifacts/closeout.json`，记录 `requirementsCoverage` 与 `deliveryChecklist` 两项结论；两项都必须包含 `status`（`PASS` / `BLOCKED`）和 `summary`
 6. 若当前方案包要求 `review-first`，必须先确认当前会话 `artifacts/review.json` 已通过 `scripts/review-state.mjs write` 写成最新结构化证据；不要把审查自然语言消息直接当成交付证据
-7. 若 `contract.json` 中 `ui.visualValidation.required=true`，必须确认当前会话 `artifacts/visual.json` 已通过 `scripts/visual-state.mjs write` 写成最新结构化证据；若没有视觉验收证据，不得把本轮视为 UI 可交付
-8. 本地版本检查点：非只读任务完成验证且产生工作区变更时，若 `auto_commit_enabled=true`，最终收尾前自动执行本地提交；若 `auto_commit_enabled=false`，跳过这一步。先检查 `git status --short`；若不是 git 仓库或无变更则跳过。若发现 `.env`、密钥、凭据、明显不应提交的大文件或二进制产物，停止提交并说明风险；否则执行 `git add -A`，使用当前回复语言生成简洁 conventional commit message 后执行 `git commit`。显式 `~commit` 不受这个开关影响。不自动远程 `git push`，除非用户明确要求
-9. 若本轮需要运行时识别验证收尾状态，优先调用 `helloagents-turn-state write --kind complete --role main`；若因阻塞判定等待输入或因前置条件缺失而停下，写 `kind=waiting` 或 `kind=blocked`，并同时写 `reasonCategory` 与 `reason`；显式 `~auto` / `~loop` 下还要写 `blocker.target`、`blocker.evidence`、`blocker.requiredAction`，不要让运行时从自然语言消息里猜状态
+7. 若 `contract.json` 中 `ui.visualValidation.required=true`，必须确认当前会话 `artifacts/visual.json` 已通过 `scripts/visual-state.mjs write` 写成最新结构化证据；若没有视觉验收证据，不得把当前结果视为 UI 可交付
+8. 本地版本检查点：非只读任务完成验证且产生工作区变更时，若 `auto_commit_enabled=true`，最终回复前自动执行本地提交；若 `auto_commit_enabled=false`，跳过这一步。先检查 `git status --short`；若不是 git 仓库或无变更则跳过。若发现 `.env`、密钥、凭据、明显不应提交的大文件或二进制产物，停止提交并说明风险；否则执行 `git add -A`，使用当前回复语言生成简洁 conventional commit message 后执行 `git commit`。显式 `~commit` 不受这个开关影响。不自动远程 `git push`，除非用户明确要求
+9. 若当前对话需要运行时识别验证收尾状态，优先调用 `helloagents-turn-state write --kind complete --role main`；若因阻塞判定等待输入或因前置条件缺失而停下，写 `kind=waiting` 或 `kind=blocked`，并同时写 `reasonCategory` 与 `reason`；显式 `~auto` / `~loop` 下还要写 `blocker.target`、`blocker.evidence`、`blocker.requiredAction`，不要让运行时从自然语言消息里猜状态
 
 ## 需求追踪验证
 
@@ -88,9 +88,9 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 2. 确认每条需求都有对应的任务实现，没有被静默丢弃
 3. 确认非目标章节列出的内容确实没有被实现（防止范围蔓延）
 4. 若 tasks.md 中定义了“完成标准”，逐项确认每个任务的完成标准确实成立，不能只因为代码存在或命令通过就视为完成
-5. 若存在 `contract.json`，逐项确认其中的 `verifyMode`、reviewer / tester 关注边界都已被本轮验证覆盖
-6. 若 `contract.json` 中 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，额外确认当前会话 `artifacts/advisor.json` 已存在且结论为 clean；若没有 advisor 证据，不得把本轮视为可交付
-7. 若 `contract.json` 中 `ui.visualValidation.required=true`，额外确认当前会话 `artifacts/visual.json` 已存在、覆盖要求的关键 screens / states，且结论为 `PASS`；若没有视觉验收证据，不得把本轮视为 UI 可交付
+5. 若存在 `contract.json`，逐项确认其中的 `verifyMode`、reviewer / tester 关注边界都已被本次验证覆盖
+6. 若 `contract.json` 中 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，额外确认当前会话 `artifacts/advisor.json` 已存在且结论为 clean；若没有 advisor 证据，不得把当前结果视为可交付
+7. 若 `contract.json` 中 `ui.visualValidation.required=true`，额外确认当前会话 `artifacts/visual.json` 已存在、覆盖要求的关键 screens / states，且结论为 `PASS`；若没有视觉验收证据，不得把当前结果视为 UI 可交付
 8. 发现遗漏 → 补充实现 → 重新验证
 
 ## 目标偏移检查

package/skills/helloagents/SKILL.md

@@ -5,12 +5,12 @@ description: 按任务类型适用 — 建立质量驱动工作流，通过技
 
 # HelloAGENTS
 
-主代理触发或读取任意 skill 时，只有本轮最终收尾消息才按通用输出格式包装；流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都保持自然输出。最终收尾中的 `🔄 下一步` 写真实动作，不写当前状态；等待用户授权时使用等待输入态收尾，已获授权且可继续执行时不得收尾。同一条最终收尾消息只包装一次；若需要分段，在同一个外层块内展开，不在正文里再次输出 `【HelloAGENTS】` 或第二个 `🔄 下一步`。
+主代理触发或读取任意 skill 时，只有当前对话的最终回复才按通用输出格式包装；流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都保持自然输出。最终回复中的 `🔄 下一步` 写真实动作，不写当前状态；等待用户授权时使用等待输入态收尾，已获授权且可继续执行时不得收尾。同一条最终回复只包装一次；若需要分段，在同一个外层块内展开，不在正文里再次输出 `【HelloAGENTS】` 或第二个 `🔄 下一步`。
 子代理只豁免输出格式、交互确认与停顿、统一执行流程、任务分层、完成判定、命令路由和流程状态，直接执行任务；安全、质量、验证和失败处理规则仍持续生效，且不得包装 HelloAGENTS 外层输出格式。
-只有运行时必须识别本轮“完成 / 等待输入 / 阻塞”时，主代理才写 turn-state；普通问候、普通问答、T0 只读分析和一次性解释不调用。必须调用场景：显式 `~auto` / `~loop`、非只读任务完成验证并进入收尾、需要让运行时识别本轮已完成、等待输入或已阻塞时、已进入项目连续流程或方案包闭环。首选 `helloagents-turn-state write --kind complete --role main`；等待或阻塞时写 `kind=waiting` / `kind=blocked`，并同时写 `reasonCategory` 与 `reason`。显式 `~auto` / `~loop` 下，还必须写入 `blocker.target`、`blocker.evidence`、`blocker.requiredAction`。不要查找、读取或拼接 `turn-state.mjs` 源码路径。子代理不得写 turn-state。
+只有运行时必须识别当前对话“完成 / 等待输入 / 阻塞”时，主代理才写 turn-state；普通问候、普通问答、T0 只读分析和一次性解释不调用。必须调用场景：显式 `~auto` / `~loop`、非只读任务完成验证并进入收尾、需要让运行时识别当前对话已完成、等待输入或已阻塞时、已进入项目连续流程或方案包闭环。首选 `helloagents-turn-state write --kind complete --role main`；等待或阻塞时写 `kind=waiting` / `kind=blocked`，并同时写 `reasonCategory` 与 `reason`。显式 `~auto` / `~loop` 下，还必须写入 `blocker.target`、`blocker.evidence`、`blocker.requiredAction`。不要查找、读取或拼接 `turn-state.mjs` 源码路径。子代理不得写 turn-state。
 普通问答、解释、分析、改写、邮件回复和其他一次性交付虽然不进入完整实现、验证或收尾流程，但仍属于交付：默认只交付与当前请求直接对应的一版最终结果；请求已满足时直接结束，不主动追加无执行价值的延伸、派生版本、不同写法、第二版或邀约式收尾，除非用户明确要求。
 
-`.helloagents/` 在所有 skill 中都统一按项目级存储路径理解：项目本地 `.helloagents/` 继续承担激活信号和会话运行态；状态文件只使用 `state_path`（实际位于 `sessions/{workspace}/{session}/STATE.md`）；会话证据使用当前 `state_path` 所在目录下的 `artifacts/*.json`；`sessions/active.json` 只作为当前活跃会话索引；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析，不要假定这些文件一定实际位于当前工作树中。
+`.helloagents/` 在所有 skill 中都统一按项目级存储路径理解：项目本地 `.helloagents/` 负责知识、方案和会话运行态，不作为项目是否已初始化的判定信号；状态文件只使用 `state_path`（实际位于 `sessions/{workspace}/{session}/STATE.md`）；会话证据使用当前 `state_path` 所在目录下的 `artifacts/*.json`；`sessions/active.json` 只作为当前活跃会话索引；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析，不要假定这些文件一定实际位于当前工作树中。
 
 ## 三重质量保障
 
@@ -23,7 +23,7 @@ description: 按任务类型适用 — 建立质量驱动工作流，通过技
 ### 流程纪律（执行时）
 - 执行 command skill 时，公共阶段边界以当前已加载的 HelloAGENTS 规则为准；command skill 只补充该命令的专属动作和边界
 - 统一执行流程的六个阶段（ROUTE/TIER→SPEC→PLAN→BUILD→VERIFY→CONSOLIDATE）按当前 Delivery Tier 和实际任务推进；未进入的阶段不强行补齐，已进入的阶段不可跳过
-- 所有 UI 任务先受当前已加载的 HelloAGENTS UI 质量基线约束；已激活项目、全局模式或显式 UI 工作流中的设计约束优先级固定为：当前 `plan.md` / PRD UI 决策 → `.helloagents/DESIGN.md`（按当前项目存储模式解析） → 已读取的 `hello-ui` 具体规则
+- 所有 UI 任务先受当前已加载的 HelloAGENTS UI 质量基线约束；已初始化项目、全局模式或显式 UI 工作流中的设计约束优先级固定为：当前 `plan.md` / PRD UI 决策 → `.helloagents/DESIGN.md`（按当前项目存储模式解析） → 已读取的 `hello-ui` 具体规则
 - 方案包存在 `contract.json` 时，验证分流、reviewer / tester 关注边界、可选 style advisor / visual validation 与交付检查优先按它执行，不再从自然语言总结里回推
 - 因阻塞判定而必须等待用户输入时，按当前已加载的 HelloAGENTS 规则处理，不得把等待输入包装成完成态
 - ~plan 的需求澄清与方案确认不可跳过，不可一个问题就出方案
@@ -50,20 +50,20 @@ description: 按任务类型适用 — 建立质量驱动工作流，通过技
 禁止行为：
 - 禁止在 ROUTE / TIER / SPEC 阶段读取实现类技能（hello-ui/hello-test/hello-verify 等）
 - 禁止因为"可能用到"就提前读取技能文件——等到真正需要时再读
-- 同一会话内，同一路径的配置文件、模块、SKILL、模板只读一次并跨轮复用；缺少所需内容、读取失败、用户要求刷新或本轮修改后才重新读取
+- 同一会话内，同一路径的配置文件、模块、SKILL、模板只读一次并跨轮复用；缺少所需内容、读取失败、用户要求刷新或本次修改后才重新读取
 - ~command 命令只读取对应的 command SKILL.md，不连带读取其他技能
 
 ## 技能查找路径
 
 按以下路径查找，找到即停，不自行猜测或遍历其他路径。
 
-路径定义：`{HELLOAGENTS_READ_ROOT}` = 本轮已确定的 HelloAGENTS 读取根目录，统一用于读取 `skills/` 与 `templates/`
+路径定义：`{HELLOAGENTS_READ_ROOT}` = 当前对话已确定的 HelloAGENTS 读取根目录，统一用于读取 `skills/` 与 `templates/`
 先确定当前技能根目录：
-- 优先使用当前上下文中已注入的“本轮 HelloAGENTS 读取根目录”
+- 优先使用当前上下文中已注入的“当前对话 HelloAGENTS 读取根目录”
 - 若当前上下文未注入，则使用稳定运行根目录 `~/.helloagents/helloagents`
 - 宿主固定链接（Codex `~/.codex/helloagents`、Claude `~/.claude/helloagents`、Gemini `~/.gemini/helloagents`）只作为兼容别名，不作为优先探测路径
 - 仍无法确定时，明确说明缺少 HelloAGENTS 读取根目录；不要递归扫描 `$HOME`、`Downloads`、项目目录或旧版本目录
-- 已激活项目或全局模式下，技能是否需要使用由当前已加载 AGENTS 规则决定；不要因此额外探测项目目录里的 HelloAGENTS skills 路径
+- 全局模式或已初始化项目时，技能是否需要使用由当前已加载 AGENTS 规则决定；不要因此额外探测项目目录里的 HelloAGENTS skills 路径
 
 ### hello-* 技能
 读取 `{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.md`
@@ -106,6 +106,7 @@ description: 按任务类型适用 — 建立质量驱动工作流，通过技
 - `~build`
 - `~prd`
 - `~loop`
+- `~global`
 - `~wiki`
 - `~init`
 - `~test`