@h-ai/cli 1.0.0-beta.2 → 1.0.0-beta.21

package/templates/skills/bridges/fullstack/AGENTS.md.hbs

@@ -2,33 +2,17 @@
 
 Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 package/app；模块用法按需读取 `.agents/skills/*/SKILL.md` 及其引用。
 
-## 需求与模板
-
-- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、README、skills、示例、生成代码及其测试中的模板默认行为是起点，不是不可变的业务约束；角色代码、权限模型、页面流程、字段、限额、存储方式与架构均可按实际需求调整。
-- 需求与模板不同，审查时记录为模板适配项，不据此判定需求错误或阻塞审查，也不要求用户额外授权“覆盖模板”；实施时在已有授权范围内修改或移除冲突逻辑，并同步 contract、鉴权、数据迁移、界面、配置、测试、文档及本文件中的过期规则。
-- 未说明的行为可参考现有实现并注明假设，不能升级为强制需求。只有业务要求自身矛盾、与已确认项目决策的优先级不明，或存在真实技术/安全障碍时才提出具体问题；已明确的规则不重复要求选择。
-- 业务规则与技术契约分别判断：可用 API 以当前安装版本的公开类型为准；输入校验、服务端授权、资源隔离和密钥保护仍须落实。需求涉及替换技术方案时说明影响并同步迁移，不能用保留模板默认值代替解决问题。
 
 ## 行为契约
 
-涉及框架结构、配置、核心流程或模块边界变更时，先按 [变更影响与方案确认](.agents/skills/hai-change-plan/SKILL.md) 说明影响并等待用户决定；已确认且未扩大的方案继续执行。
-
-需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
-
-升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
-
-根据文档规划、实施、继续、返修或按已提交文档变更同步实现时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：维护 docs 清单与任务记录，比较已验收与目标文档 Git 快照，更新原任务或新建任务，每项独立分支 TDD、验证并本地合并；全部差异与整体验收通过后才推进基线。返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
+先读 [项目共同规则](.agents/skills/hai-app-create/project.md)，按当前任务读取下面的入口；不要加载整个 skill 树。业务以用户当前明确要求及指定文档为准，模板行为是可调整的起点。
 
-普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
-
-- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
-- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
-- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
-- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
-- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
-
-- 修改前检索实现、调用方、测试和文档，优先复用现有 contract、procedure、共享组件与脚本。
-- 跨包变更先明确受影响的 contract、serv、shared、前端及交付流程，再同步调用方；不必输出固定问卷。
+| 任务 | 入口 |
+| --- | --- |
+| 新增、修改、修复应用 | [hai-app-create](.agents/skills/hai-app-create/SKILL.md)；配置、注释与能力选择按需查 [development.md](.agents/skills/hai-app-create/development.md) |
+| 需求/设计文档审查 | [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md) |
+| 文档驱动规划、实施或返修 | [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md) |
+| 代码审查 / 测试 / 构建 / 升级 | 按任务读取同名 hai-app-review / hai-app-tests / hai-build / hai-framework-sync；模块按实际依赖选择 |
 
 ## 初始架构
 
@@ -55,7 +39,7 @@ Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 pac
 
 这些是可运行示例的默认行为，按实际需求选择保留、修改或移除；不是 hai-framework 对所有应用的要求。
 
-- 初始使用 `admin` / `user` 两种角色：管理员进入用户、角色和审计管理，普通用户进入个人设置。角色代码、数量、权限粒度及可访问页面由业务需求决定；更换模型时同步服务端授权、资源范围与各端入口。
+- 初始角色为 `admin`、`audit_admin`、`config_admin`、`business_operator` 和 `user`，按权限划分账号、审计、配置、业务操作与个人设置入口。角色代码、数量、权限粒度及可访问页面由业务需求决定；更换模型时同步服务端授权、资源范围与各端入口。
 - 初始角色页维护说明并显示人数，用户页分配角色；示例防止管理员自删除、自禁用、自降级及移除最后管理员。是否采用这些流程和保护由需求确定，保留的业务不变量需覆盖并发管理请求。
 - 默认头像接受 PNG/JPEG/WebP，最大 512 KiB；普通用户更新自己的头像，管理员可替用户更新。格式、限额和操作主体可调整，contract、客户端和服务端保持一致；仍需验证文件内容及资源访问权限，storage key 由服务端生成。
 - 默认用户与审计列表使用页码分页：`page >= 1`、`pageSize` 为 1–100、每页 20 条。分页方式、筛选和上限可按需求调整，同步 schema、procedure、store 和测试。
@@ -67,36 +51,7 @@ Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 pac
 - Web 使用内存 access token 和 HttpOnly refresh Cookie；App 原生端装配 `createCapacitorTokenStorage`，浏览器预览沿用 Cookie；Desktop 原生端使用内存 TokenStorage，重启后重新登录。原生 body 刷新通道同时验证 `X-HAI-Token-Transport: body`、端对应的 `x-request-client` 与受信完整 Origin，刷新请求沿用这些头。调整会话方案时保持凭据保护和通道校验；敏感 token 不写 localStorage 或普通配置文件。
 - 服务端依据实际权限模型验证每个受保护操作，个人操作绑定当前会话，代他人操作验证对应权限；不能只靠隐藏导航保护资源。SQL 动态值参数化，日志与审计不泄露密码、token 或密钥。
 
-## 代码注释与示例
-
-- 尽可能补充有信息量的中文 JSDoc：所有 export 的函数/类/方法、核心算法与业务流程、所有数据库表/列、接口/type/schema 及其字段都必须说明用途、单位、约束和关联关系。核心逻辑解释决策原因、边界、权限与失败路径，不逐行复述代码。
-- 函数按实际契约写 @param、@returns，仅确实抛错时写 @throws；异步、HaiResult 与事务失败行为须说明。类型/表结构说明字段含义、可空性、默认值、主外键和唯一约束。
-- 上述函数和结构的 JSDoc 均提供可理解的 @example：函数给调用及结果判断，结构给合法数据，表给典型行或查询示例。省略上下文要标明，不使用真实凭据。示例随实现同步，不能只堆叠没有信息量的注释。
-- 调用及结构示例见 [.agents/skills/hai-app-create/development.md](.agents/skills/hai-app-create/development.md) 的 JSDoc 注释一节。
-
-## 质量门禁
-
-按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集一轮适用门禁及日志，汇总后集中修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。跨包契约从根工作区验证：
-
-```bash
-pnpm typecheck
-pnpm lint
-pnpm build
-pnpm test
-pnpm test:e2e
-```
-
-发布或原生壳改动另检查 Capacitor/Tauri 配置、根脚本，并按目标平台执行 `pnpm compile`、`pnpm package`。浏览器测试不能代替原生包验证。
 
 ## 完成条件
 
-- 同步受影响的 contract、serv procedure、shared client、各端调用方、README、messages、skills 和测试。
-- 报告实际门禁结果、受影响 package/app、未执行项及原因；不得将跳过或失败写成通过。
-
-## 优先 Skills
-
-构建与验收：`hai-build`、`hai-app-review`、`hai-app-tests`。管理业务按需读取 `hai-iam`、`hai-reldb`、`hai-cache`、`hai-audit`、`hai-storage`、`hai-crypto`；配置与跨端读取 `hai-core`、`hai-ui`、`hai-serv`、`hai-api-contract`、`hai-api-client`、`hai-capacitor`。
-
-前端页面先按 [hai-ui-design](.agents/skills/hai-ui-design/SKILL.md) 确定任务、布局、状态与组件映射，使用 [hai-ui](.agents/skills/hai-ui/SKILL.md) 实现，再由 [hai-ui-review](.agents/skills/hai-ui-review/SKILL.md) 检查真实页面。窄范围修改复用已有设计；按实际语言/主题/尺寸验证。
-
-工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。
+按实际 package scripts 和 [分轮验证](.agents/skills/hai-app-tests/validation.md) 选择受影响范围，依次收集 typecheck → lint → build（需要时）→ test → 相关 E2E；例如 `pnpm typecheck`。普通失败不中断独立检查，汇总后集中修复并定向复测。报告实际结果、文档/调用方同步与未验证原因；不能用静态、mock 或 Web 结果代替真实业务、外部服务或原生验证。

package/templates/skills/bridges/h5/AGENTS.md

@@ -2,35 +2,17 @@
 
 > H5 移动端项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`src/routes/`、`messages/*` 与移动端测试工作。
 
-## 需求与模板
-
-- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、README、skills、示例、生成代码及其测试中的模板默认行为是起点，不是不可变的业务约束；角色代码、权限模型、页面流程、字段、限额、存储方式与架构均可按实际需求调整。
-- 需求与模板不同，审查时记录为模板适配项，不据此判定需求错误或阻塞审查，也不要求用户额外授权“覆盖模板”；实施时在已有授权范围内修改或移除冲突逻辑，并同步 contract、鉴权、数据迁移、界面、配置、测试、文档及本文件中的过期规则。
-- 未说明的行为可参考现有实现并注明假设，不能升级为强制需求。只有业务要求自身矛盾、与已确认项目决策的优先级不明，或存在真实技术/安全障碍时才提出具体问题；已明确的规则不重复要求选择。
-- 业务规则与技术契约分别判断：可用 API 以当前安装版本的公开类型为准；输入校验、服务端授权、资源隔离和密钥保护仍须落实。需求涉及替换技术方案时说明影响并同步迁移，不能用保留模板默认值代替解决问题。
 
 ## 行为契约
 
-涉及框架结构、配置、核心流程或模块边界变更时，先按 [变更影响与方案确认](.agents/skills/hai-change-plan/SKILL.md) 说明影响并等待用户决定；已确认且未扩大的方案继续执行。
-
-需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
-
-升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
-
-根据文档规划、实施、继续、返修或按已提交文档变更同步实现时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：维护 docs 清单与任务记录，比较已验收与目标文档 Git 快照，更新原任务或新建任务，每项独立分支 TDD、验证并本地合并；全部差异与整体验收通过后才推进基线。返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
-
-普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
+先读 [项目共同规则](.agents/skills/hai-app-create/project.md)，按当前任务读取下面的入口；不要加载整个 skill 树。业务以用户当前明确要求及指定文档为准，模板行为是可调整的起点。
 
-- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
-- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
-- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
-- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
-- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
-
-先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
-
-- 直接影响：哪些页面、layout、导航、API、messages、README、测试会变。
-- 间接影响：哪些移动端流程、权限入口、共享组件和接口断言需要同步。
+| 任务 | 入口 |
+| --- | --- |
+| 新增、修改、修复应用 | [hai-app-create](.agents/skills/hai-app-create/SKILL.md)；配置、注释与能力选择按需查 [development.md](.agents/skills/hai-app-create/development.md) |
+| 需求/设计文档审查 | [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md) |
+| 文档驱动规划、实施或返修 | [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md) |
+| 代码审查 / 测试 / 构建 / 升级 | 按任务读取同名 hai-app-review / hai-app-tests / hai-build / hai-framework-sync；模块按实际依赖选择 |
 
 ## 项目定位
 
@@ -45,44 +27,7 @@
 - 敏感 token 不要写入不安全存储；优先复用模板已有的鉴权与请求模式。
 - 本样板默认不以 `@h-ai/serv`、`@h-ai/api-contract`、`@h-ai/api-client`、`@h-ai/capacitor` 作为主架构。
 
-## 工作流程
-
-1. 先搜索现有移动端页面、导航、messages、API 和测试。
-2. 修改导航、触屏交互、API 或认证流程时，同步 README、i18n 和测试。
-3. 按改动范围验证，修复本次引入的失败；已有问题与未运行项明确报告。
-
-页面统一继承根布局的 header/footer；新增页面沿用 SvelteKit 自动文件路由，刷新定位及服务端 load/鉴权保持一致。
-
-## 代码注释与示例
-
-- 尽可能补充有信息量的中文 JSDoc：所有 export 的函数/类/方法、核心算法与业务流程、所有数据库表/列、接口/type/schema 及其字段都必须说明用途、单位、约束和关联关系。核心逻辑解释决策原因、边界、权限与失败路径，不逐行复述代码。
-- 函数按实际契约写 @param、@returns，仅确实抛错时写 @throws；异步、HaiResult 与事务失败行为须说明。类型/表结构说明字段含义、可空性、默认值、主外键和唯一约束。
-- 上述函数和结构的 JSDoc 均提供可理解的 @example：函数给调用及结果判断，结构给合法数据，表给典型行或查询示例。省略上下文要标明，不使用真实凭据。示例随实现同步，不能只堆叠没有信息量的注释。
-- 调用及结构示例见 [.agents/skills/hai-app-create/development.md](.agents/skills/hai-app-create/development.md) 的 JSDoc 注释一节。
-
-## 质量门禁
-
-先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
-
-```bash
-pnpm typecheck
-pnpm lint
-pnpm build
-pnpm test
-pnpm test:e2e
-```
 
 ## 完成条件
 
-- 页面、导航、API、i18n 与测试保持一致。
-- 最终回复说明门禁状态、已更新移动端流程 / 文档与未完成项。
-
-## 优先 Skills
-
-- `hai-build`、`hai-app-create`、`hai-app-review`、`hai-app-tests`
-- `hai-kit`、`hai-ui`、`hai-reldb`、`hai-cache`
-- 其它 `hai-*` 模块按需读取
-
-前端页面先按 [hai-ui-design](.agents/skills/hai-ui-design/SKILL.md) 确定任务、布局、状态与组件映射，使用 [hai-ui](.agents/skills/hai-ui/SKILL.md) 实现，再由 [hai-ui-review](.agents/skills/hai-ui-review/SKILL.md) 检查真实页面。窄范围修改复用已有设计；按实际语言/主题/尺寸验证。
-
-工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。
+按实际 package scripts 和 [分轮验证](.agents/skills/hai-app-tests/validation.md) 选择受影响范围，依次收集 typecheck → lint → build（需要时）→ test → 相关 E2E；例如 `pnpm typecheck`。普通失败不中断独立检查，汇总后集中修复并定向复测。报告实际结果、文档/调用方同步与未验证原因；不能用静态、mock 或 Web 结果代替真实业务、外部服务或原生验证。

package/templates/skills/bridges/mobile-app/AGENTS.md

@@ -2,35 +2,17 @@
 
 > Capacitor Mobile App 项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`src/`、`messages/*` 与移动端测试工作。
 
-## 需求与模板
-
-- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、README、skills、示例、生成代码及其测试中的模板默认行为是起点，不是不可变的业务约束；角色代码、权限模型、页面流程、字段、限额、存储方式与架构均可按实际需求调整。
-- 需求与模板不同，审查时记录为模板适配项，不据此判定需求错误或阻塞审查，也不要求用户额外授权“覆盖模板”；实施时在已有授权范围内修改或移除冲突逻辑，并同步 contract、鉴权、数据迁移、界面、配置、测试、文档及本文件中的过期规则。
-- 未说明的行为可参考现有实现并注明假设，不能升级为强制需求。只有业务要求自身矛盾、与已确认项目决策的优先级不明，或存在真实技术/安全障碍时才提出具体问题；已明确的规则不重复要求选择。
-- 业务规则与技术契约分别判断：可用 API 以当前安装版本的公开类型为准；输入校验、服务端授权、资源隔离和密钥保护仍须落实。需求涉及替换技术方案时说明影响并同步迁移，不能用保留模板默认值代替解决问题。
 
 ## 行为契约
 
-涉及框架结构、配置、核心流程或模块边界变更时，先按 [变更影响与方案确认](.agents/skills/hai-change-plan/SKILL.md) 说明影响并等待用户决定；已确认且未扩大的方案继续执行。
-
-需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
-
-升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
-
-根据文档规划、实施、继续、返修或按已提交文档变更同步实现时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：维护 docs 清单与任务记录，比较已验收与目标文档 Git 快照，更新原任务或新建任务，每项独立分支 TDD、验证并本地合并；全部差异与整体验收通过后才推进基线。返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
-
-普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
+先读 [项目共同规则](.agents/skills/hai-app-create/project.md)，按当前任务读取下面的入口；不要加载整个 skill 树。业务以用户当前明确要求及指定文档为准，模板行为是可调整的起点。
 
-- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
-- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
-- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
-- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
-- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
-
-先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
-
-- 直接影响：哪些页面、store、原生桥接、messages、README、测试和打包脚本会变。
-- 间接影响：哪些 Android/iOS 权限、API 调用方、构建/打包流程和共享组件需要同步。
+| 任务 | 入口 |
+| --- | --- |
+| 新增、修改、修复应用 | [hai-app-create](.agents/skills/hai-app-create/SKILL.md)；配置、注释与能力选择按需查 [development.md](.agents/skills/hai-app-create/development.md) |
+| 需求/设计文档审查 | [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md) |
+| 文档驱动规划、实施或返修 | [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md) |
+| 代码审查 / 测试 / 构建 / 升级 | 按任务读取同名 hai-app-review / hai-app-tests / hai-build / hai-framework-sync；模块按实际依赖选择 |
 
 ## 项目概述
 
@@ -58,43 +40,7 @@ pnpm cap:build:android:debug
 pnpm cap:build:android:release
 ```
 
-## 工作流程
-
-1. 先搜索现有页面、stores、原生桥接、API client、messages 和测试。
-2. 修改原生能力、权限、登录态或 API 流程时，同步 README、i18n 和测试。
-3. 按改动范围验证，修复本次引入的失败；已有问题与未运行项明确报告。
-
-## 代码注释与示例
-
-- 尽可能补充有信息量的中文 JSDoc：所有 export 的函数/类/方法、核心算法与业务流程、所有数据库表/列、接口/type/schema 及其字段都必须说明用途、单位、约束和关联关系。核心逻辑解释决策原因、边界、权限与失败路径，不逐行复述代码。
-- 函数按实际契约写 @param、@returns，仅确实抛错时写 @throws；异步、HaiResult 与事务失败行为须说明。类型/表结构说明字段含义、可空性、默认值、主外键和唯一约束。
-- 上述函数和结构的 JSDoc 均提供可理解的 @example：函数给调用及结果判断，结构给合法数据，表给典型行或查询示例。省略上下文要标明，不使用真实凭据。示例随实现同步，不能只堆叠没有信息量的注释。
-- 调用及结构示例见 [.agents/skills/hai-app-create/development.md](.agents/skills/hai-app-create/development.md) 的 JSDoc 注释一节。
-
-## 质量门禁
-
-先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
-
-```bash
-pnpm typecheck
-pnpm lint
-pnpm build
-pnpm test
-pnpm test:e2e
-```
 
 ## 完成条件
 
-- 页面、原生桥接、API、i18n 与测试保持一致。
-- 若改动影响打包 / 原生权限 / 设备能力，README 与脚本说明必须同步更新。
-- 最终回复说明门禁状态、已更新移动端流程 / 文档与未完成项。
-
-## 优先 Skills
-
-- `hai-build`、`hai-app-review`、`hai-app-tests`
-- `hai-ui`、`hai-api-client`、`hai-capacitor`
-- 其它 `hai-*` 模块按需读取
-
-前端页面先按 [hai-ui-design](.agents/skills/hai-ui-design/SKILL.md) 确定任务、布局、状态与组件映射，使用 [hai-ui](.agents/skills/hai-ui/SKILL.md) 实现，再由 [hai-ui-review](.agents/skills/hai-ui-review/SKILL.md) 检查真实页面。窄范围修改复用已有设计；按实际语言/主题/尺寸验证。
-
-工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。
+按实际 package scripts 和 [分轮验证](.agents/skills/hai-app-tests/validation.md) 选择受影响范围，依次收集 typecheck → lint → build（需要时）→ test → 相关 E2E；例如 `pnpm typecheck`。普通失败不中断独立检查，汇总后集中修复并定向复测。报告实际结果、文档/调用方同步与未验证原因；不能用静态、mock 或 Web 结果代替真实业务、外部服务或原生验证。

package/templates/skills/bridges/website/AGENTS.md

@@ -2,35 +2,17 @@
 
 > 企业官网项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`src/routes/`、`messages/*` 与测试工作。
 
-## 需求与模板
-
-- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、README、skills、示例、生成代码及其测试中的模板默认行为是起点，不是不可变的业务约束；角色代码、权限模型、页面流程、字段、限额、存储方式与架构均可按实际需求调整。
-- 需求与模板不同，审查时记录为模板适配项，不据此判定需求错误或阻塞审查，也不要求用户额外授权“覆盖模板”；实施时在已有授权范围内修改或移除冲突逻辑，并同步 contract、鉴权、数据迁移、界面、配置、测试、文档及本文件中的过期规则。
-- 未说明的行为可参考现有实现并注明假设，不能升级为强制需求。只有业务要求自身矛盾、与已确认项目决策的优先级不明，或存在真实技术/安全障碍时才提出具体问题；已明确的规则不重复要求选择。
-- 业务规则与技术契约分别判断：可用 API 以当前安装版本的公开类型为准；输入校验、服务端授权、资源隔离和密钥保护仍须落实。需求涉及替换技术方案时说明影响并同步迁移，不能用保留模板默认值代替解决问题。
 
 ## 行为契约
 
-涉及框架结构、配置、核心流程或模块边界变更时，先按 [变更影响与方案确认](.agents/skills/hai-change-plan/SKILL.md) 说明影响并等待用户决定；已确认且未扩大的方案继续执行。
-
-需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
-
-升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
-
-根据文档规划、实施、继续、返修或按已提交文档变更同步实现时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：维护 docs 清单与任务记录，比较已验收与目标文档 Git 快照，更新原任务或新建任务，每项独立分支 TDD、验证并本地合并；全部差异与整体验收通过后才推进基线。返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
-
-普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
+先读 [项目共同规则](.agents/skills/hai-app-create/project.md)，按当前任务读取下面的入口；不要加载整个 skill 树。业务以用户当前明确要求及指定文档为准，模板行为是可调整的起点。
 
-- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
-- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
-- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
-- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
-- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
-
-先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
-
-- 直接影响：哪些页面、layout、表单/API、messages、README、测试会变。
-- 间接影响：哪些导航入口、SEO 标签、部署脚本和共享组件需要同步。
+| 任务 | 入口 |
+| --- | --- |
+| 新增、修改、修复应用 | [hai-app-create](.agents/skills/hai-app-create/SKILL.md)；配置、注释与能力选择按需查 [development.md](.agents/skills/hai-app-create/development.md) |
+| 需求/设计文档审查 | [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md) |
+| 文档驱动规划、实施或返修 | [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md) |
+| 代码审查 / 测试 / 构建 / 升级 | 按任务读取同名 hai-app-review / hai-app-tests / hai-build / hai-framework-sync；模块按实际依赖选择 |
 
 ## 项目定位
 
@@ -45,44 +27,7 @@
 - SEO 元信息、路由结构和消息文案要一起维护。
 - 本样板默认不以 `@h-ai/serv`、`@h-ai/api-contract`、`@h-ai/api-client`、`@h-ai/capacitor` 作为主架构。
 
-## 工作流程
-
-1. 先搜索现有页面、layout、组件、messages、表单/API 和测试。
-2. 修改页面时同步 README、i18n、测试和 SEO 相关元信息。
-3. 按改动范围验证，修复本次引入的失败；已有问题与未运行项明确报告。
-
-页面统一继承根布局的 header/footer；新增页面沿用 SvelteKit 自动文件路由，刷新定位及服务端 load/鉴权保持一致。
-
-## 代码注释与示例
-
-- 尽可能补充有信息量的中文 JSDoc：所有 export 的函数/类/方法、核心算法与业务流程、所有数据库表/列、接口/type/schema 及其字段都必须说明用途、单位、约束和关联关系。核心逻辑解释决策原因、边界、权限与失败路径，不逐行复述代码。
-- 函数按实际契约写 @param、@returns，仅确实抛错时写 @throws；异步、HaiResult 与事务失败行为须说明。类型/表结构说明字段含义、可空性、默认值、主外键和唯一约束。
-- 上述函数和结构的 JSDoc 均提供可理解的 @example：函数给调用及结果判断，结构给合法数据，表给典型行或查询示例。省略上下文要标明，不使用真实凭据。示例随实现同步，不能只堆叠没有信息量的注释。
-- 调用及结构示例见 [.agents/skills/hai-app-create/development.md](.agents/skills/hai-app-create/development.md) 的 JSDoc 注释一节。
-
-## 质量门禁
-
-先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
-
-```bash
-pnpm typecheck
-pnpm lint
-pnpm build
-pnpm test
-pnpm test:e2e
-```
 
 ## 完成条件
 
-- 页面、表单、SEO、i18n 与测试保持一致。
-- 最终回复说明门禁状态、已更新页面 / 表单 / 文档与未完成项。
-
-## 优先 Skills
-
-- `hai-build`、`hai-app-create`、`hai-app-review`、`hai-app-tests`
-- `hai-kit`、`hai-ui`、`hai-reldb`、`hai-cache`
-- 其它 `hai-*` 模块按需读取
-
-前端页面先按 [hai-ui-design](.agents/skills/hai-ui-design/SKILL.md) 确定任务、布局、状态与组件映射，使用 [hai-ui](.agents/skills/hai-ui/SKILL.md) 实现，再由 [hai-ui-review](.agents/skills/hai-ui-review/SKILL.md) 检查真实页面。窄范围修改复用已有设计；按实际语言/主题/尺寸验证。
-
-工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。
+按实际 package scripts 和 [分轮验证](.agents/skills/hai-app-tests/validation.md) 选择受影响范围，依次收集 typecheck → lint → build（需要时）→ test → 相关 E2E；例如 `pnpm typecheck`。普通失败不中断独立检查，汇总后集中修复并定向复测。报告实际结果、文档/调用方同步与未验证原因；不能用静态、mock 或 Web 结果代替真实业务、外部服务或原生验证。

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

@@ -1,6 +1,6 @@
 ---
 name: hai-ai
-description: "接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像、语音及 A2A。"
+description: "接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像、语音、A2A 及 ACP。"
 ---
 
 # hai-ai
@@ -9,7 +9,7 @@ description: "接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像、语音及 A2A |
+| 能力 | 接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像、语音、A2A 及 ACP |
 | 适用场景 | AI 应用服务端集成或浏览器代理接入 |
 | 输入 | AIConfigInput、消息/音频/图片、scope、AbortSignal |
 | 输出 | 领域操作为 HaiResult；流为 AsyncIterable，迭代可抛错 |
@@ -26,6 +26,8 @@ description: "接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像
 
 ## 按需参考
 
+智能体接入、工程/worktree、容器和 Git 发布见 [ACP 接入指南](acp.md)。
+
 详细配置、API 签名、错误码和范本在 [guide.md](guide.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
 
 - 使用边界
@@ -48,3 +50,5 @@ description: "接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像
 公开 API 示例以安装包的实际入口为准；框架源码中的内部工厂例子仅供模块维护。HaiResult 调用先检查 success，流与浏览器 AudioClient 按显式抛错契约处理；Context flush 失败和 A2A 未知外部效果不得盲目重放。
 
 Node 自定义 SSE 使用 ai.stream 的统一编解码，不用 split/trim 手拆上游事件；encoder 的非法元数据会显式抛错。Anthropic/MiMo 的真实 HTTP 流在退出和取消时释放正文，EOF 不伪造未完成事件，不自动重连或重放业务。
+
+资源目录维护见 [配置与数据库资源清单](resources.md)：配置只读、数据库 CRUD、来源与版本、LLM/音频/图像/MCP/检索源/ACP。

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

@@ -0,0 +1,153 @@
+# ACP 智能体、工作区和会话
+
+ACP 把宿主应用接到能操作工程的智能体。`ai.llm` 负责模型调用，`ai.acp` 负责智能体进程、协议、工程目录和会话；SDD、代码评审规则、预览页面、验收和业务部署仍由应用实现。仅在 Node 服务端使用，浏览器经应用自己鉴权的 API 接收事件。
+
+## 选择接入方式
+
+| mode | 用途 | 模型和文件 |
+| --- | --- | --- |
+| `embedded` | 启动本机安装的原生 ACP 程序 | 引用 Hai `llm.models`；使用 directory 工作区 |
+| `builtin-service` | 使用已构建镜像启动专属容器 | 引用 Hai 模型；workspace volume 挂 `/workspace`，状态卷挂 `/state` |
+| `custom-service` | 已有原生 HTTP/WS ACP 服务 | 远端自行维护模型；传远端可见的 cwd；框架不操作远端 Git |
+
+Codex 用 `adapter: 'codex'`，DeepSeek Harness 用 `adapter: 'deepseek-harness'`，其他已配置模型的 ACP 程序用 `adapter: 'generic'` 和 `command/args`。需生成其他原生配置时，向 `ai.init(config, { acpAdapters })` 提供可信服务端适配器；适配器返回 command、args、env、可选 files（写到隔离状态目录）。不把密钥存入 Agent 定义，`environmentRefs` 是目标变量名到宿主环境变量名的映射。
+
+内置 Codex/dsh 通过 stdio 使用。HTTP/WS 是锁定 SDK 2.2.0 的官方实验传输，服务必须实现相同的 ACP 传输版本；不把任意 HTTP 聊天接口当 ACP，也不自动架设 stdio 网关。自定义服务必须声明 `supportedTransports`，协议不匹配返回错误。
+
+Linux 上运行 embedded Codex 前，按 [Codex 沙箱前置](https://learn.chatgpt.com/docs/sandboxing) 准备 bubblewrap 和所需的 AppArmor profile，并用 `codex sandbox` 在临时目录验证读写。沙箱初始化失败应先修复宿主环境，不能通过关闭沙箱或让模型猜测文件内容完成任务。
+
+## 原生 HTTP/WS 服务：Goose
+
+Goose 1.57.0 自身提供 `goose serve` 与 `/acp` HTTP/WS，使用 custom-service 接入。先由部署方启动服务、挂载工作区/状态卷，并在 Goose 端维护模型（例如 `GOOSE_PROVIDER=openrouter`、`GOOSE_MODEL`、`OPENROUTER_API_KEY`）；服务独立设置 `GOOSE_SERVER__SECRET_KEY`。Hai 只使用 `X-Secret-Key` 认证，不向服务注入 Hai 模型密钥。
+
+```ts
+import { ai } from '@h-ai/ai'
+
+// ai 已初始化，Goose 已运行；HAI_GOOSE_SECRET 为服务端环境变量，值与远端服务密钥一致。
+async function connectGoose() {
+  const registered = await ai.acp.agents.register({
+    id: 'goose', name: 'Goose', mode: 'custom-service',
+    transport: 'http', url: 'http://127.0.0.1:3284/acp',
+    supportedTransports: ['http', 'ws'],
+    headerEnv: { 'X-Secret-Key': 'HAI_GOOSE_SECRET' },
+  })
+  if (!registered.success) return registered
+  return ai.acp.sessions.create({ agentId: 'goose', cwd: '/workspace' })
+}
+```
+
+WebSocket 改为 `transport: 'ws'` 和 `ws://` 地址。`cwd` 是远端可见路径；应用负责远程服务和存储的启动、关闭、Git、归属检查及 TLS。缺少或错误服务密钥会被 Goose 拒绝；恢复按握手能力走原生 load/resume，不用历史 prompt 模拟。依据：[Goose 固定版本接入文档](https://github.com/aaif-goose/goose/blob/v1.57.0/documentation/docs/gdk/acp/index.md)。
+
+## 配置和数据库共同维护
+
+`acp.agents`、`acp.workspaces` 可以直接写在配置文件里，也可通过 register 保存到数据库。get/list 返回 `{ value, source, version? }`，配置同 ID 优先且不可修改；数据库支持完整 update 和 remove。模型、MCP 等清单也遵循此规则，见 [资源清单](resources.md)。创建会话可通过 `mcpServerIds` 绑定合并清单里的 MCP。
+
+## 最小本机接入
+
+下面的目录、Git 地址、模型和密钥由部署方提供。首次登记一次，后续用 get/list 读取；重复 register 返回冲突。普通 API 都先检查 `success`。
+
+Windows stdio 需要系统 PowerShell 可用；npm 的 `.cmd` 包装应改用 `command: 'node.exe'` 和实际 JS 入口参数数组。框架跟踪整个进程树，关闭时清理后台子进程；系统策略阻止启动时直接返回错误。
+
+```ts
+import { ai } from '@h-ai/ai'
+
+async function run() {
+  const initialized = await ai.init({
+    llm: { models: [{
+      id: 'coding', model: 'your-responses-model', protocol: 'responses',
+      apiKey: process.env.MODEL_API_KEY,
+      baseUrl: 'https://models.example.com/v1',
+      capabilities: { contextWindow: 128000, maxOutputTokens: 16384, inputModalities: ['text'], outputModalities: ['text'], toolCalling: true, reasoning: { supported: false } },
+    }] },
+  })
+  if (!initialized.success) return initialized
+  try {
+    const agent = await ai.acp.agents.register({ id: 'coder', name: 'Codex', mode: 'embedded', adapter: 'codex', modelIds: ['coding'], defaultModelId: 'coding' })
+    if (!agent.success) return agent
+    const workspace = await ai.acp.workspaces.register({ id: 'project', storage: { type: 'directory', path: '/srv/projects/demo' }, repositories: [{ id: 'api', url: 'https://git.example.com/team/api.git', mainBranch: 'trunk' }] })
+    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', repositoryId: 'api', newWorktree: true })
+    if (!created.success) return created
+    const session = created.data
+    const response = await session.prompt([{ type: 'text', text: '阅读工程并说明结构' }])
+    if (!response.success) return response
+    return response.data.text
+  }
+  finally { await ai.close() }
+}
+```
+
+`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 当跨节点锁。
+
+## 容器运行与模型复用
+
+源码仓库提供 `packages/ai/models/agents` Dockerfile 和构建命令：
+
+```sh
+pnpm --filter @h-ai/ai agent:build codex-acp
+pnpm --filter @h-ai/ai agent:build deepseek-harness --engine=docker --java --rust --go
+```
+
+Codex 镜像明确包含 `@agentclientprotocol/codex-acp@2.5.0` 和 `@openai/codex@0.165.0`。所有镜像包含 Git、Node、Python；Java/Rust/Go 按构建选项安装。镜像自行构建、推送和部署；框架启动时不偷偷构建镜像、不挂引擎 socket。Dockerfile 随 npm 包的 models/agents 一起提供。
+
+Agent 改为 `mode: 'builtin-service', image: 'hai-ai/codex-acp:2.5.0', engine: 'auto'`；workspace 改为 `storage: { type: 'volume', name: 'project-code', image: 'hai-ai/codex-acp:2.5.0', engine: 'auto' }`。容器重建继续复用这两个命名卷，Git 和 Agent 在容器内始终看到 `/workspace`，不会混用宿主绝对 worktree 路径。工作区主目录为 `main/`，隔离 session 为 `sessions/<id>/`，上传文件放 `files/`。
+
+Podman 不自动继承远程服务的代理变量。需要代理时，使用 Agent/workspace 的 `environmentRefs` 显式传入容器可达的地址；宿主的回环代理不能直接在容器内使用。
+
+模型能力配置位于 `llm.models[].capabilities`：contextWindow、maxOutputTokens、inputModalities、outputModalities、toolCalling、reasoning.supported/efforts。未知就省略；不能用请求 `maxTokens` 预算推断真实容量。dsh 自定义模型需明确上下文、输出容量、输入模态、工具和推理能力，避免其内部默认值夸大模型能力。dsh 映射 Chat Completions、Responses、Anthropic；Codex 原生要求 Responses。现有 Hai 的 Responses 转换是客户端能力，不是对外反向网关。只有 Chat Completions 的服务不会因配置了 Codex 自动变成 Responses 服务。
+
+模型密钥在启动时重新解析；恢复时模型名、协议、地址、能力发生变化会拒绝，密钥轮换可以继续。自定义 ACP 服务只接受 `headerEnv` 里的认证引用，不接收 Hai 模型配置。
+
+## 工程和 Git
+
+相对 Git 地址固定相对于工作区根目录解析，clone/fetch/push 使用相同目标。协议取消因断连失败后，close 仍尝试核验拥有的进程/容器已退出；无法确认退出时保留锁。删除与同 ID 重建争用同一会话锁，忙碌失败不会建立 opening 记录。
+
+每个 Git 工程必须写明 `mainBranch`，remote 默认为 origin。`prepare` 只克隆缺失工程并校验既有工程；不自动 pull、不重置脏目录。`workspaces.importFiles(id, [{ path, content }])` 添加普通文件，拒绝路径逃逸、链接和覆盖；没有 Git 工程的工作区无需安装 Git。涉及 Git 而命令缺失返回 `ACP_GIT_NOT_FOUND`。
+
+当前托管 Git 面向普通仓库；发现子模块或 Git LFS 属性时返回 `ACP_UNSUPPORTED`，不把未拉取的子模块或 LFS 指针当作完整工程。需要这些能力的应用可自行准备环境并使用低层 `connect`，其 Git 生命周期由应用负责。
+
+创建 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 也保留，避免删除已有成果。
+
+## 交互、事件和结果
+
+`onEvent` 在创建会话前注册，接收原生 session/update（含 `_meta`）；`session.stream(content, signal)` 提供有界 AsyncIterable，提前退出会取消该轮。prompt 返回 stopReason、text、events；有 messageId 时 text 取最后一条消息，完整消息仍在 events。没有消息边界的 Agent 只能拼接其文本，不能猜测某段是最终答案。
+
+`promptStructured(content, zodSchema, signal)` 只接受 end_turn、完整唯一 JSON（可为完整 JSON fenced block）和通过 Schema 的内容。不提取夹在说明中的任意对象，不自动重试付费请求。需要业务证据、ID 或范围判断时由应用进一步校验。
+
+权限默认取消。通过 `handlers` 提供官方 SDK 类型的 permission/fs/terminal/elicitation 回调，并在 `capabilities` 声明实际实现；terminal 必须提供完整回调组。回调运行在可信服务端，应用需按用户、session 和路径授权。Agent 自带本机工具可能不经过回调，worktree 也不是安全沙箱；只读评审需要操作系统/容器权限隔离。
+
+图片、音频、嵌入资源和远程 MCP 按初始化能力检查。mode/config 通过原生协议操作。取消、握手/任务超时、输出超限会返回明确错误；连接关闭后不会自动重放请求。`sessions.resume` 仅在 Agent 声明 load/resume 时使用原生 ID 和原状态，不用历史 prompt 伪造恢复。`connect` 提供底层连接、认证和原生会话枚举/删除，用于应用已经管理执行环境的情况。
+
+`session.close()` / `ai.close()` 等待拥有的进程树或容器停止后释放占用，保留目录和卷。失联或清理失败不会按 TTL 直接抢占；管理员先检查记录里的容器资源和实际执行环境，确认停止后再恢复占用记录。生产部署需监控此类故障。应用仍需负责 API 鉴权、项目归属、外部 Git 凭据及预览/业务发布。
+
+## 配置与错误
+
+`acp` 可省略：requestTimeout=30000ms、promptTimeout=600000ms、cancelTimeout=5000ms、maxContentBytes=8388608、maxPendingEvents=1024。对应 `HAI_AI_ACP_REQUESTTIMEOUT`、`HAI_AI_ACP_PROMPTTIMEOUT` 等环境变量。CLI 的 `_ai.yml` 和 `.env.example` 由公共配置目录生成这些字段；仅取消需要的配置注释不会自动启动 Agent。
+
+错误码：070 Git 缺失；071 普通操作失败；072 参数；073 未登记；074 占用；075 不支持；076 取消；077 超时；078 输出无效/超限；079 状态冲突；080 多工程部分失败；081 已关闭；082 运行环境不可用；083 模型不兼容；084 清理失败。统一前缀 `hai:ai:`。错误不包含原始 stderr、凭据或完整命令行。
+
+## 事件与恢复边界
+
+事件保留原生内容。智能体提供 messageId 时，prompt.text 使用最后一条消息；没有 messageId 时合并本轮收到的文本。HTTP 的 session/new 响应与会话事件是独立通道，早期事件可能稍晚到达；需要严格结果时使用 promptStructured，混入说明或不完整 JSON 会返回失败，不自动截取一个看似合法的对象。
+
+DSH 模型需要容量、输入模态、工具能力与推理声明；reasoning.supported 为 true 时需明确 efforts，false 会映射为原生 reasoningEfforts: false。Codex 原生配置会选择 api-key 认证并使用 Hai Responses provider。
+
+会话绑定、定义删除和工作区修改通过共享 CAS 临界区防止悬空引用；工作路径使用独立占用锁。进程或宿主异常中断后，不自动用 TTL 假定执行者已停止：需运维先核验/终止记录中的执行资源，再修复遗留占用；正常 close 后可直接 resume。框架不将 Git worktree 当成安全沙箱。