{"_id":"@ai-suite-team/suite-cli","name":"@ai-suite-team/suite-cli","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.1":{"name":"@ai-suite-team/suite-cli","version":"1.0.1","description":"Local workflow handoff and evidence tracking for your existing agent","type":"module","bin":{"suite":"src/cli.js"},"scripts":{"test":"node --test","prepare:scenarios":"node scripts/bundle-scenarios.js","prepack":"npm run prepare:scenarios","check:bundle":"node scripts/bundle-scenarios.js --check","smoke:package":"node scripts/smoke-package.js"},"engines":{"node":">=22"},"dependencies":{"yaml":"^2.8.1"},"license":"Apache-2.0","_id":"@ai-suite-team/suite-cli@1.0.1","gitHead":"fea9e65d653da6a3a5493efdc4d2efb1e024cb9a","_nodeVersion":"23.11.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-iao+llCKElNwJuwGRvU7DCUB+2vq4cU2IAu8geqlYSs4TXT4dEzahrd3HN1hFNAUu8LqfXsPF8ZL6FTTe8gPyg==","shasum":"e858e9a91f4e7b9e122764cc32bd9b17dc9b515d","tarball":"https://registry.npmjs.org/@ai-suite-team/suite-cli/-/suite-cli-1.0.1.tgz","fileCount":57,"unpackedSize":506393,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIET3yWY4qIk9BEpBx1my11raDVoy92kVQgOWTjN+RAvzAiBHa+q8iI1OI/BoN0hX8sH2b2m/we/bJ5zm+dOHPi7LAQ=="}]},"_npmUser":{"name":"suite-team","email":"634386352zpy@gmail.com"},"directories":{},"maintainers":[{"name":"suite-team","email":"634386352zpy@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/suite-cli_1.0.1_1789213387794_0.6345605174857345"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-12T11:43:07.646Z","1.0.1":"2026-09-12T11:43:07.924Z","modified":"2026-09-12T11:43:08.119Z"},"maintainers":[{"name":"suite-team","email":"634386352zpy@gmail.com"}],"description":"Local workflow handoff and evidence tracking for your existing agent","license":"Apache-2.0","readme":"# Suite CLI — 用户 Agent 驱动的能力编排\n\n本仓库独立维护 Suite CLI 与 Web，尚未发布到 npm。主 Agent 是用户当前使用的会话；它调用宿主原生 subagent 执行节点。Suite 保存依赖、进度、产物与验收证据，不启动另一主 Agent。\n\n需要 Node.js 22+。编排与 Web 无 Python 依赖；命令节点和具体 Skill 可能需要 Python、设备 SDK 或其他工具。\n\n## 本地试用\n\n```sh\nnpm install --ignore-scripts\nnode src/cli.js --help\nnpm pack\n# 将生成的 tgz 安装到仓库外，再使用其 suite 命令\n```\n\n以下命令假定 `suite` 已在 PATH：\n\n```sh\nsuite init\nsuite skill add /absolute/path/to/installed/skills\nsuite host register --type codex --name '当前工作会话' --session ACTUAL_SESSION_ID\n# 在本调用环境中绑定 register 返回的宿主 ID：\nexport SUITE_HOST_ID=HOST_ID\n# 主 Agent 实际验证能力后，将证据 JSON 上报：\nsuite host report HOST_ID --evidence /absolute/path/to/capabilities.json\nsuite scenario list\nsuite task create --scenario dfx-jscrash --source /path/to/logs --target /path/to/report --input custom_prompt='分析指定的 JS Crash 日志'\nsuite task next TASK_ID\nsuite node start TASK_ID jscrash\n```\n\n能力证据格式与接管步骤见 `suite instructions`；不要把示例或未执行的探测上报成 verified。`SUITE_HOST_ID` 仅影响当前调用环境，不写全局默认宿主；也可每次显式传 `--host HOST_ID`。\n\n将 start 返回的 prompt、loadedSkill、输入和输出交给当前宿主的原生 subagent。主 Agent 保留 attemptId。subagent 必须写入声明的产物路径。\n\n```sh\nsuite node progress TASK_ID jscrash --attempt ATTEMPT_ID --phase analysis --message '已完成日志定位'\nsuite node submit TASK_ID jscrash --attempt ATTEMPT_ID --summary '报告已生成，包含证据与建议'\n# 主 Agent 阅读产物并验收后：\nsuite node review TASK_ID jscrash --attempt ATTEMPT_ID --accept --feedback '已核对日志与报告中的证据'\nsuite web TASK_ID\n```\n\n`suite web` 启动后自动用系统默认浏览器打开，并输出本地 URL；`suite web TASK_ID` 直接打开对应任务。无桌面环境或仅需 URL 时使用 `suite web --no-open`。自动打开失败时服务仍保持运行，可手动访问 URL。无任务 ID 时显示任务列表。配置页展示外部环境状态，允许保存本工作区的非秘密工具路径。仅绑定 `127.0.0.1`，关闭查看器不停止宿主 subagent。\n\n## 暂停、对话介入和恢复\n\n```sh\nsuite task pause TASK_ID\n# 用户要停止时，主 Agent 先请求宿主取消正在执行的 subagent：\nsuite task interrupt TASK_ID\n# 原会话或新会话中，确认旧 worker 停止后：\nsuite task status TASK_ID\nsuite task resume TASK_ID\nsuite task next TASK_ID\n```\n\n暂停只停止后续派发；中断使旧轮次报告失效，不等于宿主 worker 已停止。重跑前确认旧 worker 不再写目标工程。已完成的节点按产物证据校验后复用。\n\n默认数据保存在当前目录 `.suite`。换工作目录或会话时使用 `--root /absolute/project/.suite`。所有命令输出结构化 JSON，`--json` 可显式标识机器调用；`instructions` 输出 Markdown 宿主协议。\n\n## 首版范围\n\n- 默认展示 13 个场景，按转码（3）、DFX（8）、D2C（2）分组；另 14 个旧场景仅保留显式 ID 兼容入口；也可 `--scenario /absolute/scenario.yaml` 加载外部静态流程。\n- agent/command 节点均交接给宿主；没有自动探测或替换主 Agent。\n- Skill 由 `skill add` 注册的目录提供，节点启动前加载；未安装能力明确报错。当前不自动下载任何 Skill。\n- 本地任务 Web、产物纯文本预览、进度及基础配置；Trace 专用查看器后续扩展。\n- 支持静态 DAG、返工回边、文件/glob 门禁、显式模型验收和伴随 Agent 交接；未知 gate/协议仍明确拒绝。\n- 与旧平台任务存储分离，旧 `./suite` 仍启动 Python CLI；本包安装出的 `suite` 才是宿主执行路径。\n\n完整宿主交接指令：`suite instructions`。不支持原生 subagent 的宿主不能自动执行此模式。\n\n## 多节点工作台演示\n\n```sh\nsuite demo\nsuite web <返回的-taskId>\n```\n\n`demo` 会创建两个 **8 节点合成任务**，仅用于检查状态展示，不会启动真实 Agent：\n\n- 范围确认 → 工程分析 → 页面实现 / 业务逻辑 / 测试设计（三条并行分支）。\n- 页面和逻辑验收后汇合到构建，再结合测试设计进行验收，最后汇总交付。\n- 第二个任务模拟页面分支失败，显示下游被阻止而独立分支继续。\n\n任务页面用依赖图展示整个流程，选择节点后查看进度、产物、门禁和验收记录。演示产物均标记为 synthetic，不表示真实工程已执行。\n\n## 循环与返工\n\n`suite demo --loop` 创建两个合成示例：验证反馈后正在执行第 2/3 轮，以及达到三轮上限后停止。用 `suite web <taskId>` 查看虚线回边，点击回边查看判定历史；节点的执行记录可预览历史轮次产物。\n\n静态 YAML 的 `remediation` 定义判定节点、`back_to`、`max_rounds` 和 verdict 映射，示例见 `examples/loop-review.yaml`。主 Agent 验收判定证据后，Suite 根据 verdict 放行下游或重开返工区域。上限包含首次执行；中断恢复保留次数与反馈，终止判定不能通过 resume 清零。首版拒绝重叠循环区域。\n\nSkill 内部循环仍在单节点内执行，可用 `suite node progress TASK NODE --attempt ATTEMPT --round 2 --phase build --message '第二次构建'` 上报；此 round 仅表示 Skill 迭代，不消耗跨节点返工预算。\n\n## 全部场景与执行依赖\n\n```sh\nsuite scenario list\nsuite scenario show full-migration-android-to-kmp\nsuite scenario check full-migration-android-to-kmp --source /path/android --target /path/kmp\nsuite scenario check --all\nsuite skill add /absolute/path/to/skills\nsuite task create --scenario full-migration-android-to-kmp --source /path/android --target /path/kmp\n```\n\n覆盖 D2C、DFX 稳定性、DFX 性能、完整迁移、增量迁移、增量开发、E2E 与工程评估。场景清单和默认 Skill 来自原工程 YAML，打包时检查重复 ID 并保留流程内容；不是重新维护一套场景定义。\n\n场景可发现不等于运行环境已齐备。35 种默认 Skill 由用户注册的目录提供，不随 CLI 下载；CLI 不下载 SDK、设备工具或凭证。`scenario check` 列出 Skill、必填输入和宿主能力，具体 Skill 的设备权限及内部工具仍由宿主核查。自定义输入通过 `--input key=value` 提供。\n\n带 `companion_agents` 的节点会加载 Skill 的 `companion-agents.json` 和命名 Agent 文件，由宿主按原生方式派发。主 Agent 确認具备该能力后在 `node start` 传 `--host-capability companion_agents`；缺少定义或确认时节点不会启动。\n\n模型门禁在文件检查后要求独立验收证据：按任务包 `review.modelGate.prompt` 检查产物，保存 `{ \"passed\": true, \"evidence\": \"具体发现和依据\", \"reviewer\": \"validation_subagent\" }` 到本地 JSON，再执行 `node review ... --accept --model-evidence /path/review.json`。缺少证据或模型验收失败都不能放行下游。\n\n全部场景的测试使用合成产物验证编排契约；不表示已经对 27 个业务场景完成真实工程、设备或外部服务端到端验证。\n\n查看独立 Skill 包清单：`suite skill packages`。例如只安装 KMP 能力：\n\n```sh\nnpm install --prefix ~/.suite-skills --ignore-scripts harmony-skills-android-to-kmp\nsuite skill add ~/.suite-skills/node_modules\n```\n\nCLI 随包提供命令节点所需的轻量脚本，`platform_root` 默认指向包内 runtime，Python 从 PATH 发现，也可通过 `--input python_executable=/absolute/python3` 指定。Fidelity 的算法及资源由 `harmony-skills-figma-to-arkui` 提供，注册 Skill 目录后，节点任务包自动包含 `SUITE_FIDELITY_ROOT` 路径，宿主执行命令时需要应用 `packet.environment`。\n\n冷启动场景使用的 `hypersnap-stage2` 需要在执行前注册；可通过 `--input cold-start_skill=<已安装的兼容Skill>` 显式选择替代能力。实际安装情况以当前宿主的 `scenario check` 结果为准；CLI 不会默认降级或假报执行成功。\n\n## Web 场景与环境\n\n打开 `suite web` 后选择左侧「场景」，可搜索当前 13 个场景，并按转码、DFX、D2C 分组浏览，查看介绍、执行依赖、返工轮次与预期产物。「环境与能力状态」按宿主会话展示 CLI 保存的检查记录与缺口。配置变更及重新检查由主 Agent 通过 CLI 完成。MCP 连接与多模态能力保持「待宿主验证」，当前不会自动修改宿主 MCP 配置、安装工具或切换模型。\n\n## 多宿主与只读 Web\n\nCLI 面向主 Agent；Web 只展示场景、任务和 Agent 上报的能力状态，不再写配置或发起环境检查。\n\n- 使用 `host register --type codex --name NAME --session SESSION_ID` 登记具体会话；同类型的不同会话保持独立。\n- 主 Agent 实测后用 `host report HOST_ID --evidence FILE` 上报能力。`verified` 是 Agent 提供证据的声明，不是 Suite 自动认证；证据一小时过期。\n- `--host HOST_ID`（或该调用进程的 `SUITE_HOST_ID`）绑定任务与所有推进操作。不能将另一会话的能力或验收报告混入任务。\n- `scenario check SCENARIO --host HOST_ID` 保存当前会话的检查记录，Web 按宿主显示检查机器、工作区、时间和缺口。\n- 切换 Web 观察对象不会接管任务。接管通过 CLI 显式执行，必须停止旧 worker，保留节点历史与已验收证据。\n- 这属于本机单用户的执行归属与证据记录，不是账户鉴权。尚未实现自动安装/改写宿主 MCP 配置或自动切换模型。\n\n## Agent 执行，Web 观察\n\n主 Agent 在首次调用时登记自己的会话（同类型不同会话各自登记），将返回的 ID 设置到本次调用环境 `SUITE_HOST_ID`，后续创建和推进任务自动读取它：\n\n```sh\nsuite host register --type codex --name \"Codex · 当前工程\" --session <当前会话标识>\nexport SUITE_HOST_ID=<返回的hostId>\nsuite host report \"$SUITE_HOST_ID\" --evidence /absolute/capabilities.json\nsuite scenario check e2e-test-design --source /path/android --target /path/output\nsuite task create --scenario e2e-test-design --source /path/android --target /path/output\nsuite web\n```\n\n`capabilities.json` 示例结构为 `{\"capabilities\":[{\"name\":\"subagents\",\"status\":\"verified\",\"evidence\":\"实际调用原生subagent的方式和返回证据\"}]}`。只有完成探测后才能填写 verified，不能把此示例当作探测结果。记录由 Agent 上报，Suite 标记来源，统一保存检查时间和一小时有效期。绑定任务派发节点前必须有新鲜的 subagent 能力记录；MCP 和图片能力不能从本机软件安装情况推断。\n\nWeb 展示宿主、场景检查历史、任务归属、产物和循环；不执行环境检查、不登记宿主、不修改配置。切换观察对象不会接管任务。配置和检查由 Agent 通过 CLI 完成。\n\n中途换主 Agent 时，先停止旧 worker，再 `suite task interrupt TASK --host OLD`，随后 `suite task handoff TASK --host OLD --to NEW --confirm-stopped`；新宿主补齐自己的能力证据后 `suite task resume TASK --host NEW`。旧宿主不能再提交该任务，已经验收的产物会保留。历史未绑定任务需显式 `suite task claim TASK --host ID`。\n\n\n## 独立仓库开发\n\n```sh\nnpm ci --ignore-scripts\nnpm test\nnpm run check:bundle\nnpm pack\nnpm run smoke:package -- ./harmony-ainative-suite-cli-1.0.1.tgz\n```\n\n- Node.js 22+；完整测试另需 Python 3.13（用于实际运行随包脚本）。\n- `scenarios/` 是本仓场景定义唯一来源，`runtime/` 是随包脚本唯一来源。\n- `packaging.json` 保存审核过的场景目录、资源清单和外部能力包约束；`runtime/manifest.json` 自动生成。\n- 版本唯一来源为根 `package.json`，修改后同步 npm lockfile 并运行 `npm run prepare:scenarios`。\n- 原项目不参与构建或测试。上游来源快照见 `docs/upstream-manifest.json`，仅作溯源。\n- `.suite` 格式保持兼容，可通过 `--root` 指向之前的数据目录；不用复制或迁移任务。\n- 场景接入不等于运行依赖齐全：AutoTest 仍需独立工具交付，MCP/设备/模型仍由宿主验证。\n- CI 配置覆盖 macOS/Linux 与 Node 22/24；Windows 完整运行尚未验证。配置 CI 不代表远端已执行。\n\n### 场景目录收敛\n\n- 转码：Android → ArkTS（HomeTrans）、Android → KMP（Lean Skills）、Android → Cangjie。\n- DFX：ArkTS OOM、C++ Crash、冷启动优化分析、内存峰值与归因、Native OOM、Trace → DB、JS Crash、AppFreeze。\n- D2C：Figma → ArkUI、Figma → Compose UI。\n\n不再按全量、增量、评测与测试变体重复展示入口。YAML 的 `category` / `group` / `catalog_order` 管理分组和顺序，`archived: true` 将旧场景移出 CLI 列表、批量环境检查和 Web 目录；旧 ID 仍可显式加载，已有任务仍使用保存的流程定义查看和续跑。隐藏场景的旧 Web 目录链接回到当前第一个场景；带任务 ID 的任务链接保持可用。此变更不会重写历史任务或宣称未验证的场景已经可执行。\n\n### Skill 内部工具依赖\n\n`packaging.json.skillDependencies` 保存人工核对过的 Skill 依赖及来源，由打包脚本写入 runtime manifest；Web 与 CLI 共用这些声明，不根据工具名称猜测协议，也不在运行时下载或扫描外部 Skill 内容来猜依赖。当前覆盖 HomeTrans 的 SPEC / 页面迁移 / UI 对齐，以及 Figma → ArkUI 的取稿、预览、构建、采集和评分。未知 Skill 显示待核对，覆盖范围不代表其所有递归依赖已经审计。\n\n例如 `hmos-spec-generate` 同时需要 `homegraph` CLI（索引管理）与 `mcp:homegraph`（源码查询）；`figma-fetch-react` 使用 `anchor-d2c-mcp` CLI 访问 Figma REST API。`scenario check` 检查标记为 PATH 探测的 CLI、必要环境变量是否存在，并要求宿主对具名 MCP 提供能力记录。SDK 内工具、按需设备、运行库及模型仍需执行宿主验证；只声明需求不会自动安装或注入 MCP。覆盖默认 Skill 时按实际选择的 Skill 查依赖，不继承被替换 Skill 的工具要求。\n\n### 能力与环境 / 自动配置\n\nWeb 的「能力与环境」页按场景、Agent 会话展示本机已安装、宿主已验证、缺失和待验证项。刷新只读取本机与宿主记录，不会安装软件；宿主证据过期后显示待重新验证。安装数量不代表场景可执行。\n\n环境页面聚焦本机工具路径和外部依赖状态。资源准备与配置记录由 Agent 通过 CLI 管理，Agent 使用以下命令生成和执行方案：\n\n```sh\nsuite setup plan full-migration-android-to-arkts --host HOST_ID\nsuite setup apply full-migration-android-to-arkts --host HOST_ID\nsuite setup apply d2c-figma-to-arkui --host HOST_ID --install-tools\n```\n\n默认自动配置只从本机 `~/.agents/skills`、`~/.codex/skills` 注册场景所需的已有 Skills；若会破坏已注册 Skill 的唯一性则保留待人工处理。`--install-tools` 才会下载 `packaging.json.setupTools` 审核清单内的固定版本 CLI；首版支持 HomeGraph 和 anchor-d2c-mcp，使用 npm 安装到当前工作区 `tooling/`，不执行依赖安装脚本、不改全局 npm。CLI 自动使用该目录的 `.bin`，并将 PATH 交给节点宿主；安装失败仍保留缺口。macOS/Linux 支持自动 npm 安装，Windows 需宿主执行安装步骤。\n\n配置记录保存在 `setup-runs/`；失败、需下载授权、仍需处理的项目分别记录，可重复执行，已有能力不重复配置。MCP 连接、模型、凭证、SDK 与设备由当前 Agent 按方案配置和实际验证，不由 Web 启动替代 Agent。具名 MCP 使用例如 `mcp:homegraph` 的能力名上报，必须提供实际调用证据。配置不会生成虚假的 verified 记录，也不会启动业务任务。\n\nSkill 属于 Suite 执行资源，不计入 Web 外部环境依赖统计。CLI 在 `suite node start` 时加载并返回 `loadedSkill`，由当前宿主传给节点；这不等于自动下载所有 Skill。页面单独展示资源是否就绪，缺失资源仍会阻止节点启动。MCP、CLI、SDK、模型与环境变量等继续作为环境依赖检查。\n\n### 统一工具路径\n\n「能力与环境 → 本机工具路径」支持 DevEco Studio、HarmonyOS SDK、hdc、adb、devecocli。目录填写安装位置，CLI 填写可执行文件的绝对路径（支持 `~/`）；留空恢复 PATH 默认查找。保存校验存在性、文件类型与执行权限，不运行工具。配置保存在当前 `--root` 的 `config.json.toolPaths`，所有场景共享，新节点包携带 `toolPaths` 与 `environment`（DEVECO_HOME、HARMONY_SDK_HOME、HDC_PATH、ADB_PATH、DEVECO_CLI_PATH 和 PATH），宿主必须传给执行节点。路径存在不代表设备连接或工具执行已验证。不修改全局 Shell 或其他 Agent 配置。\n","readmeFilename":"README.md","_rev":"1-5b67796f4e792642dd582487c3c2d790"}