helloagents 3.0.32 → 3.0.35

package/skills/commands/verify/SKILL.md

@@ -1,46 +0,0 @@
----
-name: ~verify
-description: 验证总入口 — 审查、lint、typecheck、test、build 与修复循环（~verify 命令）
-policy:
-  allow_implicit_invocation: false
----
-Trigger: ~verify [scope]
-
-## 流程
-
-0. 先对齐当前工作流状态：
-   - 若当前上下文中已注入“当前工作流约束”或“当前推荐下一命令”，先服从它
-   - 即使命令通过，也不能越过当前方案包边界：不完整方案包不能视为可信交付记录，未闭合方案包不能被整体报告为已完成
-   - 当推荐路径已进入 `~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`；视觉验收优先用截图/浏览器工具，没有工具时才降级为结构化代码级自检
-1. 先决定验证分流：
-   - 若当前上下文中已注入“验证分流”，先按该分流执行
-   - 用户显式使用 `~review` 时，即使当前没有注入分流，也按审查优先起步
-   - 若没有注入分流、也不是 `~review`，默认先做全量验证；执行中一旦发现高风险流程、关键权限/配置/迁移/发布边界或明显未覆盖的风险点，立即补做 `hello-review`
-2. 审查优先模式：
-   - 获取变更范围：无参数默认未提交变更；`staged` 代表暂存区；指定文件/目录则只审查对应范围
-   - 按 hello-* 技能查找路径读取 `hello-review` SKILL.md，执行逐文件审查
-   - 高风险流程除显式范围外，还要主动补查相关配置、迁移、权限、部署或安全边界文件，不能只盯住单个功能文件
-   - 审查结论确定后，立即调用 `scripts/review-state.mjs write` 写当前会话 `artifacts/review.json`；用结构化字段记录 `outcome`、`conclusion`、`findings`、`fileReferences`，不要让后续检查脚本再从自然语言消息里猜结论
-3. 全量验证模式或审查后继续验证：
-   - 读取 `hello-verify` SKILL.md
-   - 按其“验证命令来源”优先级检测命令
-   - 逐个运行所有检测到的命令
-   - 收集每个命令的输出和退出码
-   - 对照当前契约逐项核对：requirements 是否覆盖、tasks 中每项“完成标准”是否满足、`plan.md` 中风险与设计约束是否被验证、`contract.json` 中声明的 `verifyMode` / reviewer / tester 关注边界是否已被覆盖
-   - 若 Codex active goal 存在，还要确认 `tasks.md` 的 AFK/HITL 边界：仍有可执行 AFK 项时，不进入 complete；只在目标、任务、验证和收尾都闭合后标记 goal complete
-   - 若 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，在进入收尾前调用 `scripts/advisor-state.mjs write` 写当前会话 `artifacts/advisor.json`；记录触发原因、focus、consultedSources、结论与建议，禁止只在自然语言里留一段 advisor 意见
-   - 若 `ui.visualValidation.required=true`，在进入收尾前调用 `scripts/visual-state.mjs write` 写当前会话 `artifacts/visual.json`；记录 `reason`、`tooling`、`screensChecked`、`statesChecked`、`status`、`summary`、`findings` 与 `recommendations`
-4. 汇总报告：
-   - ✅ 通过的审查项 / 命令
-   - ❌ 失败的审查项 / 命令 + 错误详情
-   - 合同核对结论：哪些需求 / 任务完成标准已满足，哪些仍未满足
-   - 修复建议
-   - 高风险流程额外说明：不能把“命令通过”直接等同于“风险已解除”；若仍存在未验证的风险边界、待授权操作或不可逆步骤，必须明确列出并停下
-
-## 失败处理
-- 有失败 → 逐个修复，修复后重新运行对应审查或验证
-- 全部通过 → 按当前已加载的 HelloAGENTS 规则进入 CONSOLIDATE 收尾；若 Codex active goal 的目标也已满足，再标记 goal complete，并按交付边界报告完成

package/skills/commands/wiki/SKILL.md

@@ -1,57 +0,0 @@
----
-name: ~wiki
-description: 初始化或同步项目知识库（与 ~init 同义）
-policy:
-  allow_implicit_invocation: false
----
-Trigger: ~wiki
-
-`~wiki` 是用户显式命令，仅创建、补全或同步项目知识库。
-
-`~wiki` 是显式知识库命令，不受 `kb_create_mode` 限制。
-执行 `~wiki` 时，`.helloagents/` 目录结构、模板格式和状态文件重写规则按当前已加载的 HelloAGENTS 规则执行；不写入项目级规则文件，也不创建项目级 HelloAGENTS 包根链接。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`verify.yaml`、`CHANGELOG.md`、`DESIGN.md`、`modules/` 改按当前上下文中已注入的项目知识目录写入。
-
-## 流程
-
-### 阶段 1：基础准备（必做）
-
-1. 创建 `.helloagents/` 目录 + `state_path`（按 templates/STATE.md 格式）；初始“主线目标”只写当前知识库初始化 / 同步目标，不把它写成长期项目总目标
-2. 追加 `.gitignore`（如果对应行不存在）：
-   ```
-   .helloagents/
-   ```
-3. 明确不执行以下操作：
-   - 不创建或更新项目级规则文件（`AGENTS.md`、`CLAUDE.md`、`.gemini/GEMINI.md`）
-   - 不创建项目级 HelloAGENTS 包根链接
-
-### 阶段 2：知识库创建或补全（条件性）
-
-检查项目是否有实际代码文件（非空项目）：
-- 有代码文件 → 执行完整知识库创建/补全（下方流程）
-- 空项目 → 保留 `.helloagents/` 和 `state_path`，告知用户“项目为空，其余知识文件将在后续开发或首次编码任务中补全”
-
-知识库创建/补全流程（统一写入 `.helloagents/` 对应的项目级存储路径；`project_store_mode=repo-shared` 时实际落在共享知识目录）：
-1. 按 templates/ 目录的模板格式，分析项目代码库后创建或补全：
-   - context.md — 按 templates/context.md 格式，填入项目概述、技术栈、架构、目录结构、模块链接
-   - guidelines.md — 按 templates/guidelines.md 格式，从现有代码推断编码约定
-   - verify.yaml — 验证命令（从 package.json/pyproject.toml 检测）
-   - CHANGELOG.md — 按 templates/CHANGELOG.md 格式创建或更新
-   - DESIGN.md — 如果项目包含 UI 代码，按 templates/DESIGN.md 格式提取或补全项目级设计契约（产品表面、设计 token、组件与模式、状态覆盖、无障碍要求、禁止事项等）
-2. 创建或补全 modules/ 目录，按 templates/modules/module.md 格式为主要模块生成文档
-3. 已存在的文件按模板格式增量更新，不自由改写结构；无新增信息时保持原样
-
-## verify.yaml 格式
-```yaml
-commands:
-  - npm run lint
-  - npm run test
-```
-
-## 幂等性
-重复执行 `~wiki` 是安全的：
-- `.helloagents/` 缺失时创建，已存在时复用
-- `state_path` 按当前任务状态重写，不追加历史；它只记录当前知识库任务，不承担项目的长期记忆
-- 知识库文件缺失时补全，已存在时按模板增量更新
-- `.gitignore` 只追加缺失行
-- 永不写入项目级规则文件，也不创建任何项目级 HelloAGENTS 包根链接

package/skills/hello-review/SKILL.md

@@ -1,42 +0,0 @@
----
-name: hello-review
-description: 审查代码变更、检查 PR、review 代码质量，或用户要求看看代码、检查代码时使用。
----
-
-代码审查必须遵循以下规范。
-
-## 审查维度
-
-逐文件检查以下维度：
-- 逻辑正确性：Bug、边界条件、空值处理、竞态条件
-- 安全漏洞：注入、XSS、硬编码密钥、权限绕过
-- 性能问题：N+1 查询、内存泄漏、不必要的重渲染、大循环
-- 可维护性：命名清晰、职责单一、重复代码、过度抽象
-- 错误处理：异常是否被正确捕获和处理
-
-## 严重度分类
-
-- 🔴 严重：必须修复（Bug、安全漏洞、数据丢失风险）
-- 🟡 建议：应该修复（性能问题、可维护性、代码风格）
-- 🟢 良好：值得肯定的好实践
-
-## 审查原则
-
-- 指出问题时给出具体修复建议和代码示例
-- 不只挑毛病，也肯定好的实践
-- 关注变更本身，不扩大审查范围到未修改的代码
-- 严重问题优先，建议性问题其次
-
-## 输出要求
-
-- 审查结束时必须单独给出一行“审查结论：...”
-- 若发现阻塞问题，结论中明确写出存在问题，并在正文中为每个问题附文件定位
-- 若未发现阻塞问题，明确写“审查结论：未发现阻塞问题。”
-- 若当前项目已初始化，或当前审查结果需要进入后续交付检查或收尾，审查结论确定后立即调用 `scripts/review-state.mjs write` 写当前会话 `artifacts/review.json`
-- `artifacts/review.json` 必须使用结构化字段记录：`outcome`（`clean` / `findings`）、`conclusion`、`findings`、`fileReferences`
-- 不要依赖“审查结论：...”这行让运行时再从自然语言里猜机器结论；这行只服务于人类阅读
-
-## 交付检查
-- [ ] 每个文件都已审查
-- [ ] 严重问题都有修复建议
-- [ ] 按严重度分类输出

package/skills/hello-verify/SKILL.md

@@ -1,144 +0,0 @@
----
-name: hello-verify
-description: 声称工作完成前、提交代码前、创建 PR 前、报告任务完成前使用。确保验证命令已运行并检查输出后才能声称成功。
----
-
-声称完成之前，必须有验证证据。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：交付证据写入当前 `state_path` 所在目录下的 `artifacts/*.json`；若 `project_store_mode=repo-shared`，`verify.yaml`、方案包与 `DESIGN.md` 按当前上下文中已注入的项目知识/方案目录解析。
-
-## 铁律
-
-没有运行验证命令 = 不能说"完成"、"通过"、"已修复"。
-没有看到验证输出 = 不能声称结果。
-
-## 验证循环
-
-验证不是一次性操作，而是循环直到通过：
-
-```
-任务完成
-  ↓
-运行验证命令（lint/test/build/typecheck）
-  ↓
-全部通过？
-  ├─ 是 → 收集已激活技能的交付检查清单 → 逐项确认 → 报告完成
-  └─ 否 → 反思 → 修复 → 重新运行验证（回到循环开头）
-```
-
-这个循环没有上限。验证失败就修复，修复后再验证，直到全部通过。
-不允许在验证失败的状态下报告完成或询问用户是否跳过。
-
-## 反思（验证失败时必须执行）
-
-验证失败后，禁止跳过反思直接改代码。必须先回答：
-1. 失败的根本原因是什么？
-2. 之前的实现遗漏了什么？
-3. 修复方案是什么？会不会引入新问题？
-
-### 断路器
-连续 3 次以上验证失败 → 激活 hello-debug 的卡住升级机制。
-
-### 进展检测
-声称任务完成时，必须有实际文件变更。如果 git diff 为空（没有任何文件变更），不能声称完成了产出文件的任务。
-
-### 原子性自检
-提交前检查变更范围：
-- 如果单次变更涉及 >5 个文件 → 暂停，重新评估是否应该拆分为多个独立变更
-- 用一句话描述变更内容，如果需要用"和"连接不相关的操作 → 拆分为多次提交
-- 每次提交应该是一个原子操作：要么全部有意义，要么全部回滚
-
-### 代码体积检查
-变更涉及的文件必须符合 HelloAGENTS 编码原则中的体积控制规则：
-- 文件/类 >300 行 → 评估是否需要拆分
-- 文件/类 >400 行 → 必须按职责拆分（例外：生成代码、大型测试夹具、迁移脚本、协议常量表）
-- 函数/方法 >40 行 → 评估是否需要拆分
-- 函数/方法 >60 行 → 必须拆分
-
-### 回归守卫
-优化或新增功能不能破坏已有测试：
-- 修改代码后，先运行已有测试确认无回归
-- 如果新代码让指标改善但已有测试失败 → 修复回归（最多 2 次尝试），不修改已有测试
-- 已有测试是底线，不能为了新功能而降低底线
-- Bug 修复必须复跑最初的复现循环；如果没有自动化回归测试，必须记录替代验证和无法补测试的原因
-- 新增或修改测试时，确认测试验证公共接口和用户可观察行为，而不是实现细节
-
-## 验证命令来源
-- 逻辑 `.helloagents/verify.yaml` 中的 commands（优先；`project_store_mode=repo-shared` 时按共享知识目录解析）
-- package.json 中的 lint/test/typecheck 脚本
-- pyproject.toml 中的 ruff/mypy/pytest
-
-## 交付检查清单把关
-
-验证命令全部通过后，还需要：
-这些标记只用于交付检查清单、验收记录和验证结果，不用于普通说明、方案解释或进度汇报。
-1. 收集所有已激活 hello-* 技能的交付检查清单
-2. 逐项确认每个检查项，标记 [√] 并附带证据（如：`src/api.ts:42` 使用了参数化查询）
-3. 不适用的项标记 [-] 并说明原因
-4. 有未通过项 → 修复 → 重新运行验证循环
-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`，不要让运行时从自然语言消息里猜状态
-
-## 需求追踪验证
-
-如果有方案包（requirements.md），执行完成后必须交叉检查：
-1. 逐条读取 requirements.md 的需求（核心目标、功能边界、质量要求）
-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 可交付
-8. 发现遗漏 → 补充实现 → 重新验证
-
-## 目标偏移检查
-
-验证时必须区分真正目标和代理指标：
-- 真正目标：用户实际要解决的问题（功能正确、体验达标、需求满足）
-- 代理指标：测试通过、lint 干净、类型检查通过、diff 整洁
-
-代理指标全部通过 ≠ 真正目标达成。验证时必须回答：
-1. 用户的真正目标是什么？
-2. 代码是否真的实现了这个目标？（不是"测试说通过了"，而是"功能确实能用"）
-3. 是否存在测试通过但功能实际不工作的情况？（如：测试 mock 了关键依赖、测试只验证了 happy path）
-
-## 目标反向验证
-
-不要从"任务完成了吗"出发，而是从目标反向推导：
-1. 明确阶段目标（用户要什么结果？）
-2. 反向推导：要达成这个目标，哪些条件必须为真？
-3. 逐条验证每个条件，使用四级验证深度
-
-### 四级验证深度
-每个关键产出必须通过四级检查：
-1. 存在 — 文件/函数/组件确实存在
-2. 真实 — 包含真实实现（不是 stub、TODO、placeholder、空函数）
-3. 连接 — 被其他代码导入/调用/使用（不是孤立的死代码）
-4. 数据流 — 有真实数据流过（API 返回真实数据、UI 渲染真实内容、事件真实触发）
-
-未通过任何一级 → 视为未完成，必须修复。
-
-## 危险信号
-
-以下想法意味着你在合理化跳过验证：
-- "应该没问题了" → 运行验证
-- "我很有信心" → 信心 ≠ 证据
-- "linter 过了" → linter ≠ 测试 ≠ 构建
-- "代码改了应该修好了" → 运行验证确认
-- "就这一次跳过" → 没有例外
-- "问问用户要不要跳过" → 不允许，必须修复
-- "先写完再测" → 未经测试的代码是负债不是资产
-- "已经手动测过了" → 手动测试无记录、不可重复、不可回归
-- "太简单不需要测" → 简单代码在复杂系统中照样出错
-- "这次例外" → 每个例外都成为先例
-- "用户没要求测试" → 质量是底线不是选项
-
-## 五步证据链（每次声称完成前必须走完）
-
-1. 识别 — 确定哪个命令能证明你的声明
-2. 运行 — 完整执行该命令
-3. 阅读 — 审查完整输出和退出码
-4. 验证 — 确认输出确实支持你的声明
-5. 声明 — 附带证据报告结果