@h-ai/cli 1.0.0-beta.17 → 1.0.0-beta.18

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "1.0.0-beta.17",
+  "version": "1.0.0-beta.18",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -30,7 +30,7 @@
     "node": "^22.23.4 || ^24.22.1 || ^26.12.1"
   },
   "dependencies": {
-    "@h-ai/core": "1.0.0-beta.17",
+    "@h-ai/core": "1.0.0-beta.18",
     "cac": "^7.0.1",
     "chalk": "^6.0.1",
     "fast-wrap-ansi": "^0.2.2",
@@ -41,18 +41,18 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@h-ai/api-client": "1.0.0-beta.17",
-    "@h-ai/cache": "1.0.0-beta.17",
-    "@h-ai/crypto": "1.0.0-beta.17",
-    "@h-ai/deploy": "1.0.0-beta.17",
-    "@h-ai/feedback": "1.0.0-beta.17",
-    "@h-ai/iam": "1.0.0-beta.17",
-    "@h-ai/kit": "1.0.0-beta.17",
-    "@h-ai/payment": "1.0.0-beta.17",
-    "@h-ai/reach": "1.0.0-beta.17",
-    "@h-ai/reldb": "1.0.0-beta.17",
-    "@h-ai/storage": "1.0.0-beta.17",
-    "@h-ai/vecdb": "1.0.0-beta.17",
+    "@h-ai/api-client": "1.0.0-beta.18",
+    "@h-ai/cache": "1.0.0-beta.18",
+    "@h-ai/crypto": "1.0.0-beta.18",
+    "@h-ai/deploy": "1.0.0-beta.18",
+    "@h-ai/feedback": "1.0.0-beta.18",
+    "@h-ai/iam": "1.0.0-beta.18",
+    "@h-ai/kit": "1.0.0-beta.18",
+    "@h-ai/payment": "1.0.0-beta.18",
+    "@h-ai/reach": "1.0.0-beta.18",
+    "@h-ai/reldb": "1.0.0-beta.18",
+    "@h-ai/storage": "1.0.0-beta.18",
+    "@h-ai/vecdb": "1.0.0-beta.18",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^26.6.5",
     "@types/prompts": "^2.4.9",

package/templates/base/package.json.hbs

@@ -1,7 +1,7 @@
 {
   "engines": { "node": "^22.23.4 || ^24.22.1 || ^26.12.1" },
   "name": "{{projectName}}",
-  "version": "1.0.0-beta.17",
+  "version": "1.0.0-beta.18",
   "private": true,
   "packageManager": "pnpm@12.11.2",
   "description": "{{#if_eq appType 'admin'}}Enterprise management system built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'website'}}Enterprise website built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'h5'}}Mobile H5 app built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'api'}}REST API service built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'mobile-app'}}Mobile app built with hai Agent Framework{{/if_eq}}",

package/templates/skills/hai-ai/acp.md

@@ -68,7 +68,7 @@ async function run() {
     if (!workspace.success) return workspace
     const ready = await ai.acp.workspaces.prepare('project')
     if (!ready.success) return ready
-    const created = await ai.acp.sessions.create({ agentId: 'coder', workspaceId: 'project', newWorktree: true })
+    const created = await ai.acp.sessions.create({ agentId: 'coder', workspaceId: 'project', repositoryId: 'api', newWorktree: true })
     if (!created.success) return created
     const session = created.data
     const response = await session.prompt([{ type: 'text', text: '阅读工程并说明结构' }])
@@ -81,6 +81,8 @@ async function run() {
 
 `agents.initialize(id)` 检查模型绑定和原生配置能否生成；真正启动和握手用 `agents.check(id, { workspaceId })`。容器 Agent 的 `image` 必须与 workspace 的 image 一致。注册 volume 时固定实际选中的引擎；`auto` 优先就绪 Podman，再尝试 Docker，显式选定不可用引擎直接失败。
 
+`repositoryId` 选择已登记仓库的根目录，原生 Agent 从该目录启动和恢复，可发现仓库内的 `AGENTS.md` 和技能。省略时使用聚合目录。选择只影响工作目录，worktree 和发布仍覆盖全部登记仓库。远程 `custom-service` 使用对端可见的 `cwd`。
+
 生产环境先初始化共享数据库和网络向量库，或注入 shared AIStoreProvider。Agent/workspace/session 记录和 CAS 占用存入 AI Store，原生历史保存在隔离状态目录。不能把临时内存 Provider 当跨节点锁。
 
 ## 容器运行与模型复用
@@ -110,12 +112,16 @@ Podman 不自动继承远程服务的代理变量。需要代理时，使用 Age
 
 创建 session 默认共享 `main/` 路径，框架会阻止另一个共享 session 同时占用它。`newWorktree: true` 从每个工程当前已提交的本地主分支创建同名分支和 worktree，普通文件单独复制；可以指定 `branch`，默认 `acp/<sessionId>`。它不会自动拉远端，也不会导入主目录未提交修改。
 
+`session.info()` 返回的 `workspace` 提供聚合目录、各登记仓库的绝对路径和存储位置。可信预览进程可以直接使用本机目录。卷模式使用返回的实际引擎，把源码卷 `name` 挂到同一 `mountPath`，并以目标仓库的 `path` 为工作目录。关闭 Agent 后预览仍可继续读取。应用先停止预览并保存所需改动，再调用 `ai.acp.sessions.reclaimWorktree(id)`。它拒绝活动、脏或锁定的工作树，可按 ID 重试。开始回收后停止 resume/publish，完成后可删会话记录。分支、普通文件、状态及卷保留，旧记录缺少归属时由运维回收。完整卷和会话信息只交给已授权的可信执行器。
+
 - `session.updateMain()`：停止本 session 的执行环境，再 fetch 各工程的明确主分支并 ff-only 更新本地主目录；不把主分支合入 session，不自动 rebase。共享主目录被其他会话占用时返回 busy。
 - `session.publish({ mode: 'push-branch', message, author: { name, email } })`：提交隔离 session 修改并推送其同名分支。
 - `session.publish({ mode: 'merge-main', message, author })`：提交后检查、更新登记的主分支，再合并并推送。无 force push，不静默处理冲突。
 
 发布仅允许框架创建的隔离 session，避免将共享目录中别人的修改算入当前任务。操作前停止受管进程/容器，避免背景工具继续写入；要继续编码显式 `sessions.resume(id)`。原生 Agent 自己创建的 worktree 不自动纳入框架发布范围。
 
+私有仓库把 Git 凭据引用写入 workspace 的 `gitEnvironmentRefs`，把 Agent 专用变量写入 agent 的 `environmentRefs`。旧 workspace 的 `environmentRefs` 仍共用，迁移时移走其中的 Git 凭据。启用 Git 隔离后，远程克隆、拉取、推送只使用登记的远端地址和可信环境注入，在独立 Git 目录运行；需要的网络代理或 CA 设置也随 Git 引用配置。认证脚本和全局 Git 配置应由可信执行器提供。任务之间的访问权限仍由应用和运行环境隔离。
+
 多个工程不是原子事务。失败时返回 `ACP_PARTIAL_FAILURE`，`error.cause.reports` 列出每个工程 success、phase、commit 和 error；已完成工程不回滚，冲突保留现场。失败于 push 后，排除权限/网络问题可重试；远端结果不明时先核对实际分支。普通文件的修改留在 session 目录，不自动纳入 Git 发布。失败创建的 worktree 也保留，避免删除已有成果。
 
 ## 交互、事件和结果

package/templates/skills/hai-build/SKILL.md

@@ -40,6 +40,7 @@ description: "构建或排查 hai 应用的源码、静态网站、容器镜像
 - 默认容器面向 CPU 运行或远程 AI 服务，Dockerfile 设置 `ONNXRUNTIME_NODE_INSTALL_CUDA=skip`，跳过额外 CUDA/TensorRT 下载；使用宿主机 GPU 时定制镜像和运行参数，不修改本机 npm 或全局 AI/GPU 配置。
 - pnpm run deploy --build 显式串联构建、打包和发布；--bundle-only 只交付完整离线包与跨平台脚本；--services 以服务器成功状态为基线只更新选中服务。完整包自动包含自建中间件镜像，服务器禁止联网拉取。
 - `pnpm build` 默认仅编译源码（调用 compile）；`pnpm build --target image` 根据 hai.json.build.images 的 dockerfile 构建并导出 serv/web 镜像（可单独或组合），可用 --images web 只构建前端，默认最多两项并行，--concurrency 1可串行，auto 优先可达 Podman、其次 Docker，可用 --runtime 显式指定。
+- 自动化直接执行 `hai build --target image --json`，成功时 stdout 只有单行 JSON，进度和失败走 stderr。读取 `artifactDir` 作为本次部署输入，清单记录 Git 提交、dirty 状态、实际镜像 OS/架构、镜像引用和归档 SHA-256。发布 Worker 从固定提交的干净检出构建。
 - compile 交付源码编译结果，image 交付镜像归档，desktop 交付 Tauri 系统安装包，app 交付 Capacitor 原生制品；每次选择一个 target。hai.json 的 build.images[].dockerfile 指向独立镜像文件，build.desktop/build.app 声明原生工程目录，deploy 保存整个项目的部署配置；参数和平台前置以当前 CLI 类型与工程 scripts 为准。cap:sync 只同步工程，不能作为已打包或已安装的证据。
 - `--image-source` / `--npm-source` 分别选 official/cn/custom；首次交互保存到 hai.json.build.sources，参数仅覆盖本次，--yes 复用且未配置时走官方。cn 镜像用毫秒镜像覆盖 Docker Hub/GHCR，npm 用 npmmirror；保留版本和 lockfile 校验。旧 Dockerfile 缺参数时明确提示同步模板。自定义映射见 [下载源与代理](reference.md#下载源与代理)。
 - Docker/Podman 的构建代理用预定义参数传递；--proxy-mode 选 inherit/system/custom/none，--proxy-url 指定自定义地址，--proxy-bypass 覆盖绕过列表，--no-http-proxy 等价 none。Podman 默认网络保留原代理地址，显式 pasta 等隔离网络才改为宿主入口；Docker 非 host 网络使用宿主入口。首个下载步骤检查实际构建可达性，不能用 run 网络代替。镜像拉取端仍需 Docker daemon/Desktop 或 Podman Machine/API 自身代理，CLI 分别预检提示。不要把代理写成 Dockerfile ENV 或固化进运行镜像。

package/templates/skills/hai-framework-sync/SKILL.md

@@ -12,7 +12,7 @@ description: "升级应用的 hai-framework 到最新或指定发布版本：分
 | 能力 | 发现最新发布版本，比较当前到目标的累计差异，处理选择与阻塞，完成应用升级及 skills/AI 入口同步 |
 | 适用场景 | “升级 Hai-framework 到最新版本”、指定版本升级、版本差异审查、模板同步或 npm/本地联调漂移排查 |
 | 输入 | 当前应用、升级目标及已有约束；当前版本、registry、架构与本地覆盖从项目读取，不要求用户预先提供框架源目录 |
-| 输出 | 当前/目标版本及来源、差异与处理清单、迁移后的依赖/代码/配置/skills、验证结果；未完成时给出选择或阻塞及恢复步骤 |
+| 输出 | 当前/目标版本及来源、框架能力复用与冗余清理、差异与处理清单、迁移后的依赖/代码/配置/skills、验证结果。未完成时给出选择或阻塞及恢复步骤 |
 | 限制 | 仅操作授权项目，保留已有改动、架构和私有规则；以实际发布产物为准，未确认选择或未解除阻塞不得越过 |
 
 ## 任务入口
@@ -61,7 +61,9 @@ npm view @h-ai/cli dist-tags --json
 - 公开入口、API/类型/错误码、HaiResult 与流/抛错语义、初始化依赖和关闭行为。
 - 配置 schema、默认行为、环境覆盖、认证/安全策略、DB schema/迁移、外部服务与引擎要求。
 - 构建/运行/发布脚本、第三方 peer 依赖、原生/容器集成，以及版本绑定的补丁是否仍必要。
-- skills 及相邻资源、AGENTS/Claude/Copilot/OpenCode 路由；新能力是否可替换本次相关的自定义实现或配置。按 [能力选择规则](../hai-app-create/development.md) 判断适用性，不为升级强行安装无关模块或转换架构。
+- skills 及相邻资源、AGENTS/Claude/Copilot/OpenCode 路由。
+
+按应用实际需求逐项对照本次升级范围内的自定义实现与目标发布版的公开 API、配置和扩展点。优先采用能满足业务规则、权限边界、数据兼容和失败处理要求的框架能力。列明替换依据、需迁移的调用方、可清理的重复实现和仍需保留的业务逻辑。框架只覆盖部分需求时，记录具体缺口及验证证据。按 [能力选择规则](../hai-app-create/development.md) 核对模块与应用架构的适配性。
 
 先给出可追踪的差异清单，再执行迁移：
 
@@ -73,11 +75,13 @@ npm view @h-ai/cli dist-tags --json
 
 | 类别 | 处理方式 |
 | --- | --- |
-| 自动处理 | 目标明确、可保持现有行为的依赖更新、兼容性修正、无冲突的 skills 合并和验证，直接执行 |
-| 用户选择 | 存在多个有意义的方案且影响产品行为、架构、成本、Provider 或运维方式，展示证据、选项、推荐与取舍，等待回答 |
+| 自动处理 | 目标明确且保持现有行为的依赖更新、兼容性修正、等效框架能力替换与冗余清理、无冲突的 skills 合并和验证，直接执行 |
+| 用户选择 | 目标版本需依赖补丁、改变配置契约或关键流程行为，或有影响产品行为、架构、成本、Provider 或运维方式的取舍时，说明方案并等待用户明确决定 |
 | 阻塞 | 无法取得必要产物、依赖不兼容、无法无损合并、必要工具/服务/授权缺失等导致后续无法执行，先处理可自行解决的原因；仍无法推进时说明具体步骤。普通门禁失败先记录，继续独立检查，本轮汇总后集中修复；必要门禁未通过仍不能交付完成 |
 | 不适用 | 当前应用未使用且不影响其依赖/运行的变化，记录依据；不要求用户逐项确认 |
 
+- 框架能力不足且考虑使用补丁时，说明目标版本的缺口、拟改范围、兼容风险、后续维护成本和移除条件。给出经核实可行的选项，例如保留兼容的应用实现、采用目标版本的最小补丁或暂缓升级。用户明确选择补丁方案后再为目标版本新增、沿用或重建补丁。
+- 配置或关键流程有变动时，实施前提示用户，说明变更前后、受影响的环境与调用方、需配合的操作及验证和回退方式。覆盖配置项、环境变量、默认值、覆盖顺序，以及初始化、认证授权、数据读写和部署等关键流程。仅由版本升级触发的默认值变化也须列出。保持配置契约和关键流程行为的等效迁移在提示后实施。改变其中任一项时，即使只有一条可行路径也要等用户明确确认。
 - 尽量合并相互独立的选择，明确每个回答控制哪项改动；已给出的目标、授权和选择持续有效，不重复询问。
 - 提问时给出问题位置、事实、影响、可选路径及推荐。用户未回答时保持选择待定，可继续独立分析/验证；不能以等待超时替用户选择，也不能先安装一部分框架包造成混版本。
 - 阻塞报告包含失败命令、退出码、脱敏关键错误、受影响步骤、已尝试处理、用户最小操作和解除后的验证方式。不要求在聊天中粘贴密钥，不通过关闭检查、忽略 engines 或无依据覆盖依赖掩盖失败。
@@ -87,19 +91,19 @@ npm view @h-ai/cli dist-tags --json
 
 必要选择和安装阻塞解除后，按既有包管理方式更新所有已用框架包的精确版本，统一修改相关 package.json/catalogs/overrides。保留应用 workspace 协议及无关依赖；必要 peer 更新须来自目标契约，禁止无差别升级全部依赖。
 
-1. 按差异清单迁移调用方、类型、配置、环境变量说明、初始化和构建入口，保留应用行为与架构。新默认行为改变须显式核对；只对生命周期模块遵循 init → use → close，不给 core/serv/纯函数套用生命周期。
-2. 用目标版本回归核验已有补丁/本地覆盖：仍必要则针对目标重建并说明依据；只有上游已修复且回归通过时移除。npm 升级遇到本地联调映射时，明确恢复 npm 或继续本地验证的选择，不能只改版本号却继续运行旧源码。
+1. 按差异清单和用户决定迁移调用方、类型、配置、环境变量说明、初始化和构建入口。等效替换时先迁移全部相关调用，确认旧实现已被完全替代且无剩余引用后，删除重复代码、纯转发适配层及仅供旧实现使用的依赖和配置，保留项目特有的业务逻辑。生命周期模块遵循 init → use → close，core/serv/纯函数按各自契约使用。
+2. 用目标版本回归核验已有补丁与本地覆盖。按用户选择和项目包管理器的补丁机制为精确目标版本维护补丁，记录适用范围、验证与移除条件。上游已覆盖且回归通过后，按清单移除冗余补丁。npm 升级遇到本地联调映射时，明确恢复 npm 或继续本地验证的选择，不能只改版本号却继续运行旧源码。
 3. 使用当前包管理器安装并更新 lockfile，保留失败诊断；不手改 lockfile 的解析字段。安装后从**各消费 workspace**核对真实版本、公开 exports/类型及框架传递依赖，检查残留旧版/重复解析和本地路径。
 4. 按 [同步规则](sync.md) 合并目标 CLI 中适配本架构的完整 skill 目录及 AI 入口。对“旧发布模板、应用现有文件、新发布模板”比较，保留仍适用的私有规则/自定义技能；已明确的业务需求优先于模板默认值，仅未决冲突转为选择。没有旧模板时先辨识私有内容，不直接覆盖。同步版本必须与目标运行时一致。
-5. 同步受影响的 README、配置样例、skill 与测试，逐项更新差异清单状态。即使已处于目标版本，也核验解析/配置/skills 漂移；一致时报告无需升级，不制造改动。
+5. 同步受影响的 README、配置样例、skill 与测试，逐项更新差异清单状态。即使已处于目标版本，也核验能力替换项及解析、配置和 skills 漂移。版本一致且清单无待处理项时，报告无需升级。
 
 ### 6. 验证与交付
 
 按应用实际 scripts 和 [分轮验证与集中修复](../hai-app-tests/validation.md) 先收集一轮适用门禁，汇总根因后集中修复、再验证；优先受影响 workspace，跨包契约验证所有消费者。按 [hai-app-tests](../hai-app-tests/SKILL.md) 选择集成/E2E，覆盖启动/关闭、变更 API、认证、持久化等实际路径；CI/发布按 [hai-ci](../hai-ci/SKILL.md) 保留失败阻断。
 
-- 依赖升级后另核对 lockfile 与安装版本、公开入口、配置加载和关键业务流程；build 通过不能替代 typecheck 或运行验收。
+- 依赖升级后核对 lockfile 与安装版本、公开入口、各受影响环境的配置生效值和关键流程。对框架能力替换回归原业务规则、权限与失败路径；有补丁时核验按 lockfile 重装可复现。build 通过不能替代 typecheck 或运行验收。
 - 检查同步后的全部相邻资源、相对引用和各工具入口；目标存在 `check:skills` 时运行，不假定应用具有框架仓库私有脚本。
 - 修复本次引入的失败，区分升级前已有失败。必要验收缺服务/凭证/平台时提示阻塞；额外平台或未涉及的真实 Provider 验证明确标为未执行及原因，不能用 mock/Web 结果冒充真实/原生验证。
-- 最终报告当前 → 目标及来源、差异处理结果、用户选择、变更文件与同步入口、实际门禁和未验证边界、恢复方法。依赖与必要迁移完成、选择/阻塞已解除且必要验证通过才称“升级完成”；否则报告当前进度与下一步，用户处理后继续完成。
+- 最终报告当前 → 目标及来源、复用的框架能力与清理项、补丁等用户决定、配置与关键流程的变动、变更文件与同步入口、实际门禁和未验证边界、恢复方法。依赖与必要迁移完成、选择/阻塞已解除且必要验证通过才称“升级完成”；否则报告当前进度与下一步，用户处理后继续完成。
 
 指定精确版本后先 hai upgrade <version>，一次核对实际消费包及 CLI/deploy 发布完整性、制品/skills、catalog/lock/安装漂移和业务定制。此命令只读，缺包不得先改工程；报告完整后再按本 skill 执行获授权的升级，合并定制不覆盖。数据库迁移单独停旧写入、备份、migrateIam/migrateReach/migrateScheduler 预检；无凭据代次的旧会话重新登录。