helloagents 2.3.8 → 3.0.1-beta.1

package/templates/plans/decisions.md

@@ -0,0 +1,10 @@
+# {项目/功能名称} — 决策日志
+
+决策记录贯穿 PRD 全程，记录每个维度讨论中的关键决策。
+
+## 决策列表
+- [YYYY-MM-DD] D-001: [决策标题]
+  - 背景：[为什么需要做这个决策]
+  - 选项：[考虑过的方案]
+  - 结论：[最终选择]
+  - 理由：[选择理由]

package/templates/plans/design.md

@@ -0,0 +1,14 @@
+# {项目/功能名称} — 方案设计
+
+## 架构决策
+[关键决策及理由]
+
+## 文件结构
+[涉及的文件和目录规划]
+
+## 视觉设计
+[涉及 UI 时填写：美学方向/配色/字体/布局/记忆点/动效/约束定义/内容策略]
+
+## 决策记录
+[设计过程中的关键决策，供回溯]
+- [YYYY-MM-DD] 决策内容及理由

package/templates/plans/prd/00-overview.md

@@ -0,0 +1,23 @@
+# {项目/功能名称} — 产品概述
+
+## 产品愿景与定位
+[一句话描述产品的核心价值主张]
+
+## 目标用户画像
+[用户角色、背景、技术水平、使用场景]
+- Persona 1: [角色名] — [描述]
+- Persona 2: [角色名] — [描述]
+
+## 用户痛点与机会
+[当前用户面临的问题，以及本产品如何解决]
+
+## 成功指标
+[可量化的 KPI / OKR]
+- [ ] 指标1：[描述] — 目标值：[值]
+- [ ] 指标2：[描述] — 目标值：[值]
+
+## 项目范围
+[必须包含的核心功能]
+
+## 非目标
+[明确不做什么——防止范围蔓延]

package/templates/plans/prd/01-user-stories.md

@@ -0,0 +1,19 @@
+# {项目/功能名称} — 用户故事与场景
+
+## 核心用户旅程
+[从用户首次接触到完成核心任务的完整路径]
+1. [步骤1] → [步骤2] → ... → [目标达成]
+
+## 用户故事列表
+[按优先级排列]
+- US-001: 作为[角色]，我想要[功能]，以便[价值] — 优先级：[P0/P1/P2]
+- US-002: ...
+
+## 边缘场景与异常流
+[非正常路径：网络断开、数据异常、并发冲突等]
+- EC-001: [场景描述] → 预期行为：[描述]
+
+## 验收标准
+[每个核心故事的 Acceptance Criteria]
+- US-001:
+  - [ ] Given [前置条件], When [操作], Then [预期结果]

package/templates/plans/prd/02-functional.md

@@ -0,0 +1,30 @@
+# {项目/功能名称} — 功能需求
+
+## 功能清单
+[按 MoSCoW 优先级分类]
+
+### Must Have（必须）
+- F-001: [功能名] — [描述]
+- F-002: ...
+
+### Should Have（应该）
+- F-010: ...
+
+### Could Have（可以）
+- F-020: ...
+
+### Won't Have（不做）
+- F-030: ...
+
+## 业务规则与逻辑
+[核心业务规则，如权限、状态流转、计算公式]
+- BR-001: [规则描述]
+
+## 数据模型与实体关系
+[核心实体、字段、关系]
+
+## API 契约
+[关键接口的输入/输出/错误码]
+
+## 状态机与流程图
+[核心业务流程的状态流转]

package/templates/plans/prd/03-ui-design.md

@@ -0,0 +1,31 @@
+# {项目/功能名称} — UI/UX 设计规范
+
+## 设计风格与美学方向
+[整体视觉风格、情感基调、参考案例]
+
+## 设计 Token
+[变量体系]
+- 颜色：背景色、表面色、主色、强调色、语义色
+- 字体：展示字体、正文字体、等宽字体
+- 间距：基础单位、间距比例
+- 圆角：组件圆角规范
+- 阴影：层级阴影体系
+
+## 布局与响应式策略
+[各视口的布局方式、网格系统、断点定义]
+- Mobile: [策略]
+- Tablet: [策略]
+- Desktop: [策略]
+
+## 组件规范与交互模式
+[核心组件的设计规范和交互行为]
+
+## 动效与过渡策略
+[入场动画、交互反馈、状态过渡]
+- 尊重 prefers-reduced-motion
+
+## 暗色模式 / 主题切换
+[是否支持、切换策略、Token 映射]
+
+## 设计约束
+[字体数量上限、强调色数量、CTA 数量等]

package/templates/plans/prd/04-technical.md

@@ -0,0 +1,25 @@
+# {项目/功能名称} — 技术架构
+
+## 技术选型与理由
+[语言/框架/数据库/第三方服务及选择理由]
+| 层级 | 选型 | 理由 |
+|------|------|------|
+| 前端 | | |
+| 后端 | | |
+| 数据库 | | |
+| 部署 | | |
+
+## 系统架构图
+[组件关系、数据流向、外部依赖]
+
+## 文件/模块结构
+[目录规划和模块划分]
+
+## 依赖关系与第三方服务
+[外部 API、SDK、SaaS 服务]
+
+## 数据库设计
+[表结构、索引策略、迁移方案]
+
+## 架构决策记录
+- [YYYY-MM-DD] ADR-001: [决策] — 背景：[背景] | 选项：[A/B/C] | 结论：[选项X] | 理由：[理由]

package/templates/plans/prd/05-nonfunctional.md

@@ -0,0 +1,28 @@
+# {项目/功能名称} — 非功能需求
+
+## 性能要求
+- 页面加载时间：[目标值]
+- API 响应时间：[P50/P95/P99 目标]
+- 并发用户数：[目标值]
+- 吞吐量：[目标值]
+
+## 安全需求
+- 认证方式：[JWT/Session/OAuth/...]
+- 授权模型：[RBAC/ABAC/...]
+- 数据加密：[传输层/存储层]
+- OWASP Top 10 防护：[具体措施]
+
+## 可用性与容灾
+- SLA 目标：[99.9%/99.99%/...]
+- 备份策略：[频率/保留期]
+- 降级方案：[核心功能降级策略]
+
+## 可扩展性
+- 水平扩展：[策略]
+- 垂直扩展：[策略]
+- 瓶颈预判：[已知瓶颈及应对]
+
+## 监控与可观测性
+- 日志：[级别/格式/存储]
+- 指标：[关键指标/采集方式]
+- 告警：[告警规则/通知渠道]

package/templates/plans/prd/06-i18n-l10n.md

@@ -0,0 +1,23 @@
+# {项目/功能名称} — 国际化与本地化
+
+## 支持语言列表
+[按优先级排列]
+| 语言 | 区域 | 优先级 | 备注 |
+|------|------|--------|------|
+| | | P0 | 默认语言 |
+| | | P1 | |
+
+## 文本外部化策略
+[i18n 框架选型、key 命名规范、翻译文件格式]
+
+## RTL 布局支持
+[是否需要、实现策略]
+
+## 日期/时间/货币/数字格式
+[各区域的格式化规则]
+
+## 文化适配
+[图标/颜色/图片/内容的文化差异处理]
+
+## 翻译工作流
+[翻译流程、工具、质量保证]

package/templates/plans/prd/07-accessibility.md

@@ -0,0 +1,20 @@
+# {项目/功能名称} — 无障碍
+
+## 目标合规级别
+[WCAG 2.2 AA / AAA，或其他标准]
+
+## 键盘导航方案
+[Tab 顺序、快捷键、焦点管理]
+
+## 屏幕阅读器支持
+[ARIA 标签策略、语义化 HTML、动态内容通知]
+
+## 色彩对比度要求
+[正文/大文本/图标的最低对比度比值]
+
+## 动效减弱
+[prefers-reduced-motion 响应策略]
+
+## 测试计划
+- 自动化：[axe-core / Lighthouse / ...]
+- 手动：[辅助技术测试矩阵]

package/templates/plans/prd/08-content.md

@@ -0,0 +1,20 @@
+# {项目/功能名称} — 内容策略
+
+## 文案风格指南
+[Tone & Voice：正式/友好/专业/幽默/...]
+- 品牌语调：[描述]
+- 用词规范：[术语表/禁用词]
+
+## 错误信息规范
+[错误信息的结构和语气]
+- 格式：[发生了什么] + [为什么] + [怎么解决]
+- 语气：[不责怪用户、提供明确行动]
+
+## 空状态与引导文案
+[各空状态场景的文案和引导]
+
+## 帮助文档与 Tooltip
+[帮助内容的层级和触发方式]
+
+## SEO 策略
+[如适用：关键词、元数据、结构化数据]

package/templates/plans/prd/09-testing.md

@@ -0,0 +1,22 @@
+# {项目/功能名称} — 测试策略
+
+## 测试金字塔
+[单元/集成/E2E 的比例和覆盖目标]
+- 单元测试：[覆盖率目标] — [框架]
+- 集成测试：[覆盖范围] — [框架]
+- E2E 测试：[关键路径] — [框架]
+
+## 关键测试场景
+[必须覆盖的核心业务场景]
+- TC-001: [场景描述] — 预期结果：[描述]
+
+## 性能测试计划
+[负载测试/压力测试/基准测试]
+
+## 兼容性矩阵
+| 平台 | 版本 | 优先级 |
+|------|------|--------|
+| | | |
+
+## 验收测试标准
+[上线前必须通过的测试清单]

package/templates/plans/prd/10-deployment.md

@@ -0,0 +1,23 @@
+# {项目/功能名称} — 部署与运维
+
+## 环境规划
+| 环境 | 用途 | 配置差异 |
+|------|------|----------|
+| dev | 开发调试 | |
+| staging | 预发布验证 | |
+| prod | 生产环境 | |
+
+## CI/CD 流水线
+[构建/测试/部署的自动化流程]
+
+## 发布策略
+[蓝绿部署/金丝雀发布/灰度发布/滚动更新]
+
+## 回滚方案
+[回滚触发条件、回滚步骤、数据回滚策略]
+
+## 配置管理
+[环境变量/配置文件/密钥管理]
+
+## 数据迁移计划
+[数据库迁移策略、数据兼容性、回滚脚本]

package/templates/plans/prd/11-legal-privacy.md

@@ -0,0 +1,18 @@
+# {项目/功能名称} — 法律与隐私
+
+## 数据收集与处理
+[收集哪些数据、处理目的、法律依据]
+- GDPR 合规：[适用/不适用] — [措施]
+- CCPA 合规：[适用/不适用] — [措施]
+
+## 用户同意机制
+[Cookie 同意、隐私政策、数据处理同意]
+
+## 数据保留与删除策略
+[各类数据的保留期限、删除机制、用户删除请求处理]
+
+## 第三方数据共享
+[与哪些第三方共享数据、共享目的、数据处理协议]
+
+## 许可证合规
+[开源依赖的许可证审查、商业许可证需求]

package/templates/plans/prd/12-timeline.md

@@ -0,0 +1,21 @@
+# {项目/功能名称} — 里程碑与排期
+
+## 阶段划分
+| 阶段 | 范围 | 目标 |
+|------|------|------|
+| MVP | [最小可行产品范围] | [验证核心假设] |
+| V1 | [完整功能集] | [正式发布] |
+| V2 | [增强功能] | [规模化] |
+
+## 里程碑与交付物
+- M1: [里程碑名] — 交付物：[描述] — 预计：[日期]
+- M2: ...
+
+## 依赖关系与风险
+[外部依赖、技术风险、人员风险]
+| 风险 | 影响 | 概率 | 缓解措施 |
+|------|------|------|----------|
+| | | | |
+
+## 资源需求
+[人员/技术/预算需求]

package/templates/plans/requirements.md

@@ -0,0 +1,18 @@
+# {项目/功能名称} — 需求
+
+确认后冻结，执行阶段不可修改。如需变更必须回到设计阶段重新确认。
+
+## 核心目标
+[解决什么问题？给谁用？]
+
+## 功能边界
+[必须有什么？不需要什么？]
+
+## 非目标
+[明确不做什么——防止范围蔓延和 AI 自作主张]
+
+## 技术约束
+[平台/语言/框架/依赖/不可修改的文件或 API]
+
+## 质量要求
+[测试/安全/可访问性/性能要求]

package/templates/plans/tasks.md

@@ -0,0 +1,10 @@
+# {项目/功能名称} — 任务分解
+
+## 任务列表
+[按执行顺序排列，每个任务独立可验证]
+- [ ] 任务1：描述（涉及文件、验证方式）
+- [ ] 任务2：描述
+- [ ] 任务3：描述
+
+## 进度
+[执行过程中更新]

package/templates/verify.yaml

@@ -0,0 +1,9 @@
+# Verify commands for HelloAGENTS Ralph Loop
+# Auto-detected or manually configured
+# Format: simple list only (one command per line, no YAML advanced syntax)
+# Uncomment or add your project's verify commands below:
+
+commands:
+  # - npm run lint
+  # - npm run typecheck
+  # - npm run test

package/bin/cli.mjs

@@ -1,106 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * HelloAGENTS npm/npx bootstrap installer.
- *
- * This script is ONLY for first-time setup:
- *   npx helloagents                # install + interactive menu
- *   npx helloagents install codex  # install + specify target
- *
- * After installation, use the native `helloagents` command directly
- * for all subsequent operations (update, uninstall, status, etc.).
- */
-
-import { execSync, spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-
-const REPO = "https://github.com/hellowind777/helloagents";
-const MIN_PYTHON = [3, 10];
-
-function findPython() {
-  for (const cmd of ["python3", "python"]) {
-    try {
-      const out = execSync(`${cmd} --version`, {
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"],
-      }).trim();
-      const match = out.match(/Python (\d+)\.(\d+)/);
-      if (match) {
-        const major = parseInt(match[1], 10);
-        const minor = parseInt(match[2], 10);
-        if (major > MIN_PYTHON[0] || (major === MIN_PYTHON[0] && minor >= MIN_PYTHON[1])) {
-          return cmd;
-        }
-      }
-    } catch {}
-  }
-  return null;
-}
-
-function detectBranch() {
-  try {
-    const __dirname = dirname(fileURLToPath(import.meta.url));
-    const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
-    if (pkg.version && /beta/i.test(pkg.version)) return "beta";
-  } catch {}
-  return "main";
-}
-
-function pipInstall(python, branch) {
-  const suffix = branch && branch !== "main" ? `@${branch}` : "";
-  const url = `git+${REPO}.git${suffix}`;
-  console.log(`Installing helloagents Python package (${branch})...`);
-  const res = spawnSync(python, ["-m", "pip", "install", "--upgrade", url], {
-    stdio: "inherit",
-  });
-  if (res.status !== 0) {
-    console.error("Failed to install helloagents Python package.");
-    process.exit(1);
-  }
-}
-
-// --- Main ---
-const python = findPython();
-if (!python) {
-  console.error("Error: Python >= 3.10 not found.");
-  console.error("Please install Python first: https://www.python.org/downloads/");
-  process.exit(1);
-}
-
-const args = process.argv.slice(2);
-
-// Supported: no args (interactive menu) or "install [target]"
-if (args.length > 0 && args[0] !== "install") {
-  console.log("HelloAGENTS npx bootstrap installer");
-  console.log("");
-  console.log("Usage (first-time install only):");
-  console.log("  npx helloagents                # interactive menu");
-  console.log("  npx helloagents install codex   # specify target directly");
-  console.log("  npx helloagents install --all   # install to all detected CLIs");
-  console.log("");
-  console.log("After installation, use the native command directly:");
-  console.log("  helloagents update");
-  console.log("  helloagents uninstall <target>");
-  console.log("  helloagents status");
-  console.log("  helloagents version");
-  process.exit(0);
-}
-
-// Step 1: Install pip package
-pipInstall(python, detectBranch());
-
-// Step 2: Forward to native CLI (no args = interactive menu, install = direct install)
-const fwdArgs = args.length > 0 ? args : [];
-const res = spawnSync(python, ["-m", "helloagents", ...fwdArgs], { stdio: "inherit" });
-
-if (res.status === 0) {
-  console.log("");
-  console.log("Done! From now on, use the native command directly:");
-  console.log("  helloagents update          # update to latest version");
-  console.log("  helloagents uninstall codex # uninstall from a CLI");
-  console.log("  helloagents status          # check installation status");
-}
-
-process.exit(res.status ?? 1);