@givolt/i3-composer-agent 2.3.7 → 3.1.0

package/skills/i3-enterprise-sop/references/technical-baseline/baselines/enterprise-application-technical-baseline-v0-0-4.md

@@ -0,0 +1,380 @@
+# 企业应用公共技术规约
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+## 0. 身份、范围与来源
+
+| 项目 | 当前内容 |
+| --- | --- |
+| 文档版本 | v0.0.4，2026-10-22；当前分发规约，工程目录规范与采用说明统一为1.0.0 |
+| 文档性质 | 根据使用者逐项确认整理的企业共用技术基线；供具体项目明确选用，新稿文字仍可人工审阅修改 |
+| 适用范围 | 明确采用本文件的企业业务项目及其前端、业务后端、Agent、任务工程；各工程按实际需求采用 |
+| 项目绑定 | 本文件不绑定某一业务项目；项目名称、采用版本、PRD／AD与实际工程在项目采用说明或AD中记录，见 Q01、Q12 |
+| 直接来源 | 软件架构设计 Specification 模板 v0.6（2026-09-23），含原文明确的技术方向及工程约束 |
+| 编排依据 | 当前企业 SOP 的公共技术规约模板、AD 模板及交接合同；工程组织引用现有目录规范1.0.0 |
+| 确认依据 | 2026-10-20确认原有共用规则；2026-10-21确认将推荐版本矩阵补入规约，K8s暂按既有1.28记录。确认技术选择不等于授权升级、安装、部署或通过兼容验收 |
+| 维护与采用 | 共用规则及选型方向按上述确认维护；具体项目仍需记录采用版本、适用范围、责任和例外，不由本轮确认替代业务认可或开工许可 |
+| 现有证据 | 已核官方版本／依赖要求及本机工具；已完成Dapr 1.18.7针对K8s 1.28的三组离线Helm渲染。版本矩阵已明确；尚无目标集群连接、工程安装／构建及完整联调证明，见§2.3—§2.6 |
+
+本文件定位为可复用的企业共用技术基线，已写入确认的选型方向与共用约定。第8节分别记录“已经确认的规则”和“项目仍需落实的事实”，不能把版本、环境或运行结果自动标成已验证。项目明确选用后，AD准确引用本文件路径、文内版本及适用条款；按影响起草和交接，不要求所有项目事实先清零。
+
+本文件是业务项目的技术资料，不是 i3-composer-agent 工具自身的运行规范，也不作为所有标准流程或所有企业 SOP 项目的安装默认。项目已有适用规范时，优先核对其权威范围，避免建立第二份相互冲突的规约。
+
+### 0.1 来源与整理边界
+
+| 来源 | 本次使用内容 | 整理后的维护位置 |
+| --- | --- | --- |
+| 软件架构设计 Specification 模板 v0.6，第 3—4 章 | 架构边界、已明确技术方向、按需选型、版本与兼容要求 | 本文件第 1—2 节 |
+| 同一来源，第 6—11 章 | 数据、接口、前端、Agent、集成、权限及恢复的共用约束 | 本文件第 1、3—5 节；主题接口、实体和流程由各 AD 详设 |
+| 同一来源，第 12—17 章及附录 | 工程质量、环境、流水线、实施交接、验证与未决事项 | 本文件第 6—9 节 |
+| 使用者本轮逐项确认（2026-10-20） | 共用基线定位、Java／Spring Boot、前端工具链、MaxKey／OIDC、接口惯例、目录采用、部署分工及按项目落实的规则 | 对应第2—9节；不扩展为版本兼容、业务批准或实际环境就绪 |
+| 2026-10-21官方资料核对、本机只读检查与使用者确认 | 固定首套版本选择、保留K8s 1.28及现有GitLab；记录兼容范围与真实验证边界 | 本文件§2.3—§2.6及Q02—Q06、Q09；不自动执行升级或替项目采用 |
+| [公共技术规约模板及采用说明](../readme.md) | 已有规范优先、公共规则与主题设计分工、候选与真实采用分开 | 本文件的范围、采用和版本规则 |
+| [当前 AD 模板](../../ad/templates/ad.md) §0.3、§2.2、§9.6 | 基线引用、技术落实和真实骨架来源 | 各主题 AD 的对应条款 |
+| [当前交接合同](../../handoff-contract.md) §10 | 选定 AD 及必要配套交原 Plan，再进入获准 Build | 本文件第 9 节 |
+| [目录规范1.0.0](../../engineering-skeleton/directory-standard.md)、[采用说明1.0.0](../../engineering-skeleton/adoption.md) | 工程目录与职责、AD映射、原Plan任务路径、获准Build的实际文件落点 | 本文件第1、6—9节；目录规范可先采用，不要求预先取得代码框架模板 |
+| [原Ship命令](../../../../../.claude/commands/i3-ship.md)及[原Spec的内容要求](../../../../i3-spec-driven-development/SKILL.md) | 发布前检查／决策／回滚，及原SPEC六项的工程命令和项目依据 | 本文件第6—7、9节；原命令与Skill未改 |
+
+源材料沿用总体 `design.md` 和旧 MVP 产物组织。本文件只提取其中适用的技术内容，并按当前已确认的“公共规约＋多主题 PRD／AD”组织；不恢复旧 MVP 流程，不改动源文件，不要求把公共规则复制到每份 AD。原文要求明确写出规则的目的继续保留：AD 必须指出准确规则、适用范围和落实位置，不能只写“沿用旧规范”。
+
+本规约保留已确认技术条款及其来源说明，仅分发当前版本；工程组织统一采用同一SOP Skill内的1.0.0目录规范与采用说明。来源材料或发行资源后续修改，不自动改变项目已经采用的版本。
+
+## 1. 共用架构与工程边界
+
+| 条款 | 共用规则 | 主题 AD 的落实责任 |
+| --- | --- | --- |
+| ARC-01 | 根据真实业务目标确定逻辑模块、工程、运行应用和部署单元；一个 PBC 不自动等于一个微服务、仓库或数据库 | 明确本主题组件职责、依赖、运行单元和部署关系，以及采用或拆分理由 |
+| ARC-02 | 前端负责交互与呈现；业务服务负责正式业务规则、最终授权、状态及数据；Agent 负责其获准的分析或工具执行；任务工程负责实际选择的触发、执行与恢复职责 | 给出三图和详设，绑定实际组件及数据维护责任；按需采用工程类型，不为凑目录新增服务 |
+| ARC-03 | 前端临时状态、Agent 会话或执行结果、工作流历史、任务状态与正式业务状态分别维护 | 写清各类状态的存储、可信来源、标识映射及最终业务完成条件 |
+| ARC-04 | Dapr 的运行支撑能力与项目业务授权、数据责任及人工决定分开设计 | 明确所用能力、组件、调用方向、业务校验和失败责任；服务能够互通不代表用户获准操作 |
+| ARC-05 | 缓存、向量检索、消息、GIS、三维、多 Agent 等按实际需求选择 | 给出需求来源、用途和选型；不使用时说明理由，未知时列为待确认 |
+| ARC-06 | 消费外部能力应依据正式契约，不复制提供方内部实现作为本主题权威 | 固定提供／消费关系和版本；分别记录已可用、待核实、待接入及真实联调条件 |
+
+来源：软件技术说明第3、5、8—11章；现有工程骨架目录方案及目录规范1.0.0的职责分工。
+
+前端共用规则：
+
+- FE-01：业务评审 HTML 原型与正式 Vue 工程分别交付，模拟数据明确标识；新项目不自动套用既有平台 Console 或 BladeX 外壳。
+- FE-02：根据真实页面从 Antdv Next 的完整组件能力中选择，starter 展示内容不构成组件白名单；主题、布局、字体、图标和反馈由实际设计明确。
+- FE-03：页面设计说明响应式、实际终端、键盘操作和可访问性范围，并定义加载、空、错误、无权限、重复提交、取消及长任务结果等适用状态。
+- FE-04：前端类型和 API 客户端绑定正式契约；区分服务端数据、界面状态及草稿，明确会话失效、租户切换、缓存失效和敏感信息展示行为。
+
+来源：软件技术说明第 8 章。具体页面、断点、浏览器范围及专业引擎仍由真实需求和项目决定。
+
+## 2. 技术与工程基线
+
+### 2.1 已确认的技术方向
+
+下表保留源材料第4.1节的技术方向，并补入本轮使用者确认的后端、前端工具链及统一身份方向。它们作为本基线的首套选型方向；具体项目明确采用后落实，确需差异时记录例外。方向确认与某个精确版本组合已经兼容、可运行分别记录。
+
+| 技术领域 | 已确认的选型方向 | 适用范围 | 当前版本及落实状态 |
+| --- | --- | --- | --- |
+| 正式 Web 前端 | Vue 3＋TypeScript＋Antdv Next | 实际需要 Web 界面的业务工程；具体页面由 PRD 及适用原型确定 | 采用§2.3的Vue 3.5.44、TypeScript 5.9.3及Antdv Next 1.6.0；实际安装／构建待验证，见Q03 |
+| 前端工程工具链 | Vite＋TypeScript类型检查＋Vitest | 首套Web工程的构建、类型检查和单元／组件测试；路由和共享状态管理按需选择 | 采用§2.3固定工具链；按需增加路由与状态管理，运行验证见§2.5、Q03 |
+| 分布式运行时 | Dapr | 项目实际采用的服务调用、状态、事件或其他运行能力 | Runtime 1.18.7，所需SDK／组件按§2.3选用；K8s 1.28实际联调待验证，见Q04 |
+| 业务 Agent | Python＋Dapr Agents | 项目包含业务 Agent 时适用；未采用 Agent 的项目不生成 Agent 工程 | 项目环境采用Python 3.12.15、Dapr Agents 1.0.9；保留宿主系统Python，模型接入仍按需验证 |
+| 持久工作流 | Dapr Workflow | 经具体设计确定需要持久编排或恢复的场景 | Python Workflow包1.18.3，按需使用PostgreSQL状态组件v2；恢复与跨版本行为待验证 |
+| 目标运行平台 | Kubernetes（K8s） | 采用此企业基线的产品目标部署环境 | 沿用使用者提供的K8s 1.28，完整补丁／发行版／访问条件待取得；本轮不升级 |
+| 主数据库 | PostgreSQL | 权威业务数据；执行历史、会话、缓存等用途另行明确 | 无既有约束时采用17.11候选；优先核现有服务端，Java驱动42.7.14，实例／扩展／迁移待落实 |
+| 代码与流水线 | 企业 GitLab＋GitLab CI | 业务项目的代码协作、构建和交付 | 现有GitLab 19.2.4；Runner按19.2.x匹配，补丁与平台能力待核；安全更新另行安排 |
+| 普通业务后端 | Java＋Spring Boot | 首套普通业务后端选型方向，与Python Agent的职责和工程分别明确；可用的企业框架先核对复用条件 | 采用OpenJDK 21.0.13、Spring Boot 4.1.1、Maven 3.10.0；依赖与启动验证见Q02 |
+| 统一身份与单点登录 | MaxKey＋OIDC | 企业统一账号与认证入口；角色和权限按实际采用能力映射，业务服务执行最终业务授权 | MaxKey 4.1.12为首轮OIDC接入基线；实例与生产安全更新仍需核实，见§2.3、Q06 |
+
+缓存、消息设施、对象存储、检索、网关、ORM、迁移工具、状态管理、GIS及三维引擎尚未统一指定产品。AD按需说明来源、用途和方案，不默认为全部引入。MaxKey是已确认的统一身份方向，其实际接入信息由项目取得。
+
+### 2.2 版本、选型及变更规则
+
+- TECH-01：工程初始化或依赖安装前，取得本次所用的精确版本或有依据的兼容范围，并核对实际软件包、API及所需能力；不使用“最新版本”代替记录。
+- TECH-02：技术方向、文档兼容核对、实际安装、构建启动、集成验证分别记录；锁文件存在不证明运行通过。
+- TECH-03：模型不能自行替换已采用的框架、数据库、平台或版本。确需调整时，记录原因、备选、受影响契约／数据／AD／工程与验证安排，由使用者按项目规则决定。
+- TECH-04：私有框架、集团服务或外部骨架必须有准确来源及当前可用性证据；仅有名称时记录待取得，不生成假安装命令或假调用。
+- TECH-05：优先兼容企业已有且仍受支持的PostgreSQL版本；没有现有约束时，再结合驱动、迁移工具、Dapr相关组件及运维条件选择并核验。业务库、工作流历史和Agent会话可共用基础设施，但逻辑责任、隔离和恢复分别设计，不推定一个PBC必须独占数据库。
+
+来源：软件技术说明第4章及使用者对Q02—Q05的确认。实际版本选择分别核对[Spring Boot系统要求](https://docs.spring.io/spring-boot/system-requirements.html)、[Vue工具说明](https://vuejs.org/guide/scaling-up/tooling)、[Dapr Agents入门条件](https://docs.dapr.io/developing-ai/dapr-agents/dapr-agents-getting-started/)和[PostgreSQL支持政策](https://www.postgresql.org/support/versioning/)。官方说明用于核对方向与条件，不代替本项目完整版本矩阵和运行验证。
+
+### 2.3 首套版本矩阵（2026-10-21确认）
+
+本节记录已确认的首套技术选择及有条件候选，不把“推荐目标”写成“已经安装”或“集成已通过”。实际项目先核已有平台与规范，明确采用本版后再落实所需组件。新增工程在实际依赖文件及锁文件中固定准确版本；可选组件不因列在本表就一律引入。
+
+| 类别 | 组件 | 推荐目标／既有版本 | 选择理由及适用限制 |
+| --- | --- | --- | --- |
+| 前端运行工具 | Node.js | 24.22.0 LTS | 沿用本机24系列，满足Vite和Vue工具链要求；本机当前24.15.0，本轮未升级 |
+| 前端包管理 | pnpm | 12.9.1 | 复用本机已安装版本；项目采用时固定`packageManager`及锁文件，不自动跟随最新版本 |
+| 前端框架 | `vue`、`@vue/compiler-sfc` | 均为3.5.44 | 运行时与编译器保持同版；采用Vue 3稳定线 |
+| 组件库 | Antdv Next | 1.6.0 | 采用正式发布且已有完整工程依赖依据的版本；新发布1.7.0留作后续评估，不自动替换 |
+| 类型检查 | TypeScript／`vue-tsc` | 5.9.3／3.3.13 | 以Antdv Next 1.6.0的TS工具链为依据，保留类型检查；不因TS出现新大版就自动切换 |
+| 构建 | Vite／`@vitejs/plugin-vue` | 8.3.5／6.0.10 | 插件声明支持Vite 8；Vite要求Node `^20.19.0`或`>=22.12.0`，所选Node满足 |
+| 前端测试 | Vitest及所需coverage插件 | 均为4.1.12 | 此版本依赖声明包含Vite 8；作为本规约的保守选择，不宣称与组件库仓库的Vitest版本相同 |
+| 按需前端依赖 | Vue Router／Pinia | 4.6.4／3.0.4 | 沿用Antdv Next 1.6.0工程所用版本线；仅在页面路由或共享状态确有需要时引入 |
+| Java环境 | OpenJDK | 21.0.13 LTS | 延续现有OpenJDK 21系列；本机当前Homebrew OpenJDK 21.0.12.1，升级另行执行 |
+| Java构建 | Maven | 3.10.0 | 复用已安装版本，满足Spring Boot的Maven 3.6.3以上要求 |
+| 普通业务后端 | Spring Boot | 4.1.1 | 所选Java 21在官方兼容范围内；其余Spring依赖由该版BOM管理，不逐项随意混配 |
+| Java数据库驱动 | PostgreSQL JDBC | 42.7.14 | 对Boot 4.1.1 BOM中的42.7.13作明确安全补丁覆盖；需验证连接认证与读写，不以BOM存在替代安全核对 |
+| Agent项目环境 | Python | 3.12.15 | Dapr Agents 1.0.9要求Python `>=3.11,<3.14`；使用独立项目环境，保留本机系统默认3.14.4 |
+| 分布式运行时 | Dapr Runtime | 1.18.7 | 普通sidecar方式；K8s 1.28离线渲染已通过，实际运行与支持边界见§2.4—§2.5 |
+| Dapr管理工具 | Dapr CLI | 1.18.2 | CLI与Runtime分别记录真实发行号；本机尚未安装，不把补丁号强行设成Runtime相同 |
+| 按需Java集成 | Dapr Java SDK | 1.18.1 | 要求Java 17以上；仅采用相应能力时引入。若使用Spring集成，选择专用Boot 4 starter并单独验证，不能误用Boot 3 starter |
+| Python运行能力 | `dapr`／`dapr-ext-workflow` | 均为1.18.3 | 与所选Agents要求的Dapr 1.18包范围一致；工作流包仅用于相应工程 |
+| Agent框架 | `dapr-agents` | 1.0.9 | 已核Python和Dapr依赖范围；框架成熟度与实际模型／工具链仍需项目验证，版本1.x不等于生产验收 |
+| 业务数据库 | PostgreSQL服务端 | 17.11（无既有约束时的候选） | 优先复用已有受支持服务端；本机只确认libpq／psql客户端18.3，不能据此假定服务端也是18.3或自动新建17.11 |
+| Dapr存储 | PostgreSQL state组件 | `v2` | 这是组件协议版本，与数据库17.11分别管理；按需用于Actor／Workflow，业务数据与运行历史分别明确责任、隔离和恢复 |
+| 统一身份 | MaxKey＋OIDC | 4.1.12（首轮接入基线） | 作为独立身份服务通过协议对接，无需与业务服务的Boot主版相同；4.2.0为新发布候选，投产前核其安全修复及迁移影响，不将4.1.12直接认定为生产安全验收通过 |
+
+Java若实际采用Spring集成，候选坐标为`io.dapr.spring:dapr-spring-boot-4-starter:1.18.1`。官方该专用starter存在不等于Boot 4.1.1组合已经联调；仍需核依赖收敛、Jackson序列化和启动行为。只采用Dapr HTTP／gRPC接口时也需明确接口与认证边界，不在本规约里提前替项目改变集成方式。
+
+| 平台／工具 | 本次保留的环境／选择 | 采用与后续处理 |
+| --- | --- | --- |
+| Kubernetes | 1.28，完整1.28.x补丁与发行版待取得 | 按使用者要求保留，不预设升级。该系列已结束上游维护，亦不在本次Dapr官方支持／发布测试范围内；不由此推导为必然无法运行 |
+| kubectl | 集群操作时使用与1.28匹配的专用客户端，准确补丁待核 | 本机Docker附带kubectl 1.34.1，与1.28超出官方±1小版本范围；保留现有工具，后续按需隔离使用匹配客户端 |
+| GitLab | 19.2.4，使用者提供 | 延续既有19.2分支；19.2.8作为同分支安全更新建议，需单独确认与执行，不把它写成已经升级 |
+| GitLab Runner | 19.2.x，实际补丁待核 | 与GitLab主／次版本匹配；未取得实例信息前不编造精确补丁号或可用Runner |
+| Docker Desktop | 本机4.70.0 | 4.96.0作为另行评估的更新候选；本轮未启动Docker或升级。CLI版本不证明实际运行的Engine版本 |
+| Helm及集群部署工具 | 项目实际工具待选择 | 研究中临时使用的Helm 3.19.0不是项目默认工具，也不构成本机全局安装事实 |
+| 工程骨架 | 统一采用本SOP Skill内的目录规范／采用说明1.0.0 | 按本次确认统一来源；项目既有采用不自动升级，先核差异、适用范围及真实工程映射。目录规则不等于可运行代码模板 |
+
+### 2.4 已取得的环境事实与K8s兼容边界
+
+2026-10-21在本机只读检查：macOS 26.3、Apple Silicon、64GB内存；Node 24.15.0、pnpm 12.9.1、Homebrew OpenJDK 21.0.12.1、Maven 3.10.0；系统默认Python 3.14.4，另有3.12.13和3.13.13环境。Python目标3.12.15尚未建立项目环境，不替换系统Python。
+
+PostgreSQL已定位的是Homebrew libpq 18.3工具。在已查常见路径、进程、服务及本机5432端口中未找到正在运行的服务端；仍可能存在停止的容器、其他路径或远端实例。项目应先取得服务端的真实版本、位置和访问方式，再决定是否采用17.11新建候选。
+
+本机Docker daemon未运行，当前没有Kubernetes context或可访问集群配置；Dapr CLI和Helm不在当前PATH中。K8s 1.28及GitLab 19.2.4来自使用者说明，尚未通过目标平台查询核实。
+
+对官方Dapr 1.18.7 chart所做的离线检查仅包括：针对`--kube-version 1.28.0`和`1.28.15`的默认渲染，以及1.28.15的HA渲染，三组退出码均为0。该chart没有`kubeVersion`硬性排除1.28；渲染出的内置API未见明显要求高于1.28的版本。首轮校验文件下载超时与后续成功记录分别保留，没有把失败转算通过。
+
+这些结果不包含服务端Schema接收、server-side dry-run、实际安装、Pod启动、网络／存储、Workflow或Agent验收。Dapr 1.18.7该发布的kind矩阵覆盖K8s 1.32.8、1.33.4、1.34.0，没有1.28。因此本规约的结论是“既有1.28保留，普通sidecar有静态兼容依据，真实兼容待验证”，不能写成“官方支持1.28”或“已证明必然不能运行”。
+
+保持`dapr_sidecar_injector.nativeSidecar=false`，不主动设置Pod注解`dapr.io/enable-native-sidecar=true`。K8s 1.28的原生sidecar依赖默认关闭的Alpha功能，普通Dapr sidecar不要求启用它。Job／CronJob若使用普通sidecar，AD须按所选版本说明结束和退出方式，避免业务容器结束后sidecar阻碍Job完成。
+
+### 2.5 实施前后的验证安排
+
+| 编号 | 需取得的结果 | 通过依据及影响范围 |
+| --- | --- | --- |
+| V01 前端 | 选定版本的安装、类型检查、构建及适用测试 | 依据真实`package.json`、锁文件和命令输出验证Vue／Antdv／Vite／TS／Vitest组合；缺项仅限制相关前端实现／交付 |
+| V02 Java | Boot 4.1.1的依赖收敛、启动、序列化与JDBC行为 | 核所选JDK、Maven、PG JDBC安全补丁覆盖；实际用到Dapr starter时再核Boot 4专用starter及Jackson组合，不预判联调通过 |
+| V03 Agent／Workflow | Python 3.12.15环境及完整依赖解析；真实模型、工具和持久执行 | 核Agents／SDK约束、中断恢复、重复执行与授权失效；替身范围与真实服务联调分开，未采用能力不要求凭空搭建 |
+| V04 K8s／Dapr | 目标1.28集群中的实际安装与必要业务链 | 取得准确补丁、发行版、匹配客户端和合法访问条件；核CRD／webhook／权限、Pod、DNS／网络、持久卷、Placement／Scheduler及业务实际所用能力，保留失败和回滚说明 |
+| V05 数据与身份 | 真实PostgreSQL／MaxKey实例信息及联调 | 优先核既有实例；验证认证、角色／租户映射、退出撤权、读写／迁移／恢复及版本安全更新，不能用客户端号或产品名代替服务端事实 |
+| V06 交付平台 | GitLab／Runner／镜像与部署所需实际能力 | 据实补Runner补丁、仓库、环境和权限引用；GitLab／Docker更新另行安排，不因版本矩阵已写入就宣称平台已准备好 |
+
+验证按对应AD、Plan任务及实际阶段执行，继续区分设计审查、工程执行、集成、业务认可和发布授权。未验证项可以保留并明确其影响，不要求在AD起草前先搭出所有环境；依赖它们的实施或放行也不能凭文档确认自动通过。
+
+### 2.6 官方依据与核对日期
+
+以下资料用于2026-10-21的版本选择和兼容条件核对。滚动文档可能变化；实际实施时以本节明确版本、相应发布说明及真实解析结果复核，不跟随链接自动更新本规约。
+
+| 范围 | 官方依据 | 本次核对点 |
+| --- | --- | --- |
+| Node／包管理 | [Node 24.22.0](https://nodejs.org/en/blog/release/v24.22.0)、[pnpm安装要求](https://pnpm.io/installation) | 24系列LTS及所选工具环境要求；pnpm复用实际12.9.1 |
+| Vue／Antdv | [Vue 3.5.44包](https://registry.npmjs.org/vue/3.5.44)、[Antdv Next 1.6.0](https://github.com/antdv-next/antdv-next/releases/tag/antdv-next%401.6.0)、[对应工程依赖](https://github.com/antdv-next/antdv-next/blob/antdv-next%401.6.0/pnpm-workspace.yaml) | 组件库发布、Vue／TS／Router／Pinia工程范围；不把组件库仓库所有测试版本照搬成项目义务 |
+| TS／构建／测试 | [TypeScript 5.9.3](https://registry.npmjs.org/typescript/5.9.3)、[vue-tsc 3.3.13](https://registry.npmjs.org/vue-tsc/3.3.13)、[Vite 8.3.5](https://registry.npmjs.org/vite/8.3.5)、[Vue插件6.0.10](https://registry.npmjs.org/@vitejs/plugin-vue/6.0.10)、[Vitest 4.1.12](https://registry.npmjs.org/vitest/4.1.12) | Node engines及peer／依赖约束；包元数据满足不代替项目构建 |
+| Java／Boot | [Homebrew OpenJDK 21](https://formulae.brew.sh/formula/openjdk@21)、[Maven历史](https://maven.apache.org/docs/history.html)、[Boot要求](https://docs.spring.io/spring-boot/system-requirements.html)、[Boot 4.1.1 BOM](https://repo.maven.apache.org/maven2/org/springframework/boot/spring-boot-dependencies/4.1.1/spring-boot-dependencies-4.1.1.pom) | JDK／Maven兼容、BOM依赖管理；Homebrew OpenJDK发行与其他JDK发行包分别判断 |
+| PostgreSQL驱动 | [JDBC 42.7.14说明](https://jdbc.postgresql.org/changelogs/2026-10-07-42.7.14-release/) | 针对BOM的42.7.13明确采用安全补丁，保留项目认证和读写验证 |
+| Python／Agent | [Python 3.12.15](https://www.python.org/downloads/release/python-31215/)、[Agents 1.0.9依赖](https://github.com/dapr/dapr-agents/blob/v1.0.9/pyproject.toml)、[Dapr 1.18.3](https://pypi.org/pypi/dapr/1.18.3/json)、[Workflow 1.18.3](https://pypi.org/pypi/dapr-ext-workflow/1.18.3/json) | Python范围及Dapr SDK范围，不采用系统3.14为Agent项目环境 |
+| Dapr版本／Java集成 | [Runtime 1.18.7](https://github.com/dapr/dapr/releases/tag/v1.18.7)、[CLI 1.18.2](https://github.com/dapr/cli/releases/tag/v1.18.2)、[Boot 4 starter 1.18.1 POM](https://repo.maven.apache.org/maven2/io/dapr/spring/dapr-spring-boot-4-starter/1.18.1/dapr-spring-boot-4-starter-1.18.1.pom)、[Spring集成说明](https://docs.dapr.io/developing-applications/sdks/java/spring-boot/) | 组件分别定版；专用starter可用性与完整组合验证分开 |
+| K8s兼容 | [Dapr支持政策](https://docs.dapr.io/operations/support/support-release-policy/)、[1.18.7 chart](https://github.com/dapr/dapr/blob/v1.18.7/charts/dapr/Chart.yaml)、[sidecar配置](https://github.com/dapr/dapr/blob/v1.18.7/charts/dapr/charts/dapr_sidecar_injector/values.yaml)、[该版kind测试](https://github.com/dapr/dapr/blob/v1.18.7/.github/workflows/kind-e2e.yaml)、[K8s版本](https://kubernetes.io/releases/)、[kubectl偏差规则](https://kubernetes.io/releases/version-skew-policy/) | 支持范围、发布测试、离线模板与真实运行分别取证；保留既有1.28 |
+| 数据／身份 | [PostgreSQL支持](https://www.postgresql.org/support/versioning/)、[Dapr PostgreSQL v2](https://docs.dapr.io/reference/components-reference/supported-state-stores/setup-postgresql-v2/)、[MaxKey 4.1.12](https://github.com/dromara/MaxKey/releases/tag/4.1.12)、[MaxKey 4.2.0](https://github.com/dromara/MaxKey/releases/tag/4.2.0) | 新建候选、已有实例及生产安全选择分别处理 |
+| 交付工具 | [GitLab安全补丁](https://docs.gitlab.com/releases/patches/patch-release-gitlab-19-4-2-released/)、[Runner版本](https://docs.gitlab.com/runner/#gitlab-runner-versions)、[Docker Desktop说明](https://docs.docker.com/desktop/release-notes/) | 保留19.2.4及本机4.70.0；更新建议不写成已执行 |
+
+## 3. 身份、安全与业务权限
+
+统一身份和单点登录采用MaxKey，通过OIDC对接。MaxKey作为独立的公共身份服务，业务工程不再自行复制一套账号密码体系；如需适配现有账号系统，先明确来源、映射和生命周期责任。
+
+| 环节 | 采用规则 |
+| --- | --- |
+| MaxKey | 承担项目实际采用的统一账号、认证、单点登录及角色／权限管理能力；具体版本、类型和应用注册据实取得 |
+| 业务前端与后端 | 按OIDC及所选版本的真实接口接入，后端验证身份；前端展示和路由控制不代替服务端授权 |
+| 业务权限与数据 | 角色、组和权限可映射MaxKey实际提供的定义；具体动作、资源、租户和业务状态仍由责任服务最终校验 |
+| Agent与任务工程 | 区分运行服务身份和被代理用户，明确授权传递、失效和审计；模型参数不作为可信身份来源 |
+| 项目接入细节 | 身份服务地址、用户与租户映射、会话退出、撤权、失效、密钥及配置引用由AD明确；不照抄演示地址或推定claims字段 |
+
+先按社区版的标准协议能力核对对接条件；实际类型与版本仍由项目明确。细粒度权限、权限OpenAPI等能力以实际版本类型和证据为准，不因产品名称存在就视为具备。[MaxKey OIDC接入说明](https://www.maxkey.top/doc/docs/am/sso/oidc/)、[版本类型功能对比](https://www.maxkey.top/doc/about/cevsenterprise/)。
+
+- SEC-01：用户、代理和服务身份分别说明可信来源。租户、资源范围及权限必须由服务端在受控边界校验；前端显隐和模型自填参数不作为授权凭据。
+- SEC-02：身份或权限上下文无法确认时，不按成功授权继续执行。撤权、过期、租户切换、缓存失效和恢复后的复核行为由相应 AD 明确。
+- SEC-03：业务角色、权限及状态转换依据选定 PRD。角色名称不能代替具体动作和数据范围判断，不推定管理员可以执行所有操作。
+- SEC-04：Dapr 服务访问控制、K8s 运行身份和业务用户授权分别落实。统一身份系统存在时，明确账号、密码和会话责任，不自动创建第二套账号体系。
+- SEC-05：文档与仓库只保存配置及凭据引用，不写真实密码、令牌或密钥。数据传给模型、日志、追踪、导出和备份的范围，应按实际数据分类与访问规则明确。
+- SEC-06：工具调用先建立可信上下文，核工具、输入、权限及适用确认，再执行动作、校验／过滤结果并保存证据。人工确认是否适用取决于具体动作的已确认规则，不一律放行或一律增加审批。
+
+身份提供方和协议方向已确定；claims映射、租户标识、审计字段、实例信息和保留要求按项目落实，见Q06、Q07、Q09、Q10。来源：软件技术说明第7.1、9.3、9.7、11章及使用者对Q06的确认。
+
+## 4. 契约通则、Agent 与共享定义
+
+### 4.1 已确认的接口与数据惯例
+
+| 范围 | 共用约定 | 项目及主题AD补充内容 |
+| --- | --- | --- |
+| API字段命名 | 本项目自有API字段使用camelCase | 外部契约或既有系统沿用其真实定义，适配处写明映射与例外 |
+| 数据库字段命名 | 本项目新建数据库字段使用snake_case | 保留存量字段，具体表名、约束、索引及schema按工程实际明确 |
+| 跨端大整数标识 | API中用字符串承载需保持完整精度的大整数ID | 主键生成方式、数据库类型、唯一范围和外部标识映射由具体契约确定 |
+| 时间点 | 契约明确时区、格式和精度，避免无时区的含糊表达 | 存储／展示时区、业务日期、时长及事件时间和处理时间分别定义，不自行补默认数值 |
+| 错误与关联 | 返回稳定业务码和可关联请求／追踪的标识 | 正式契约固定字段名、接口状态、允许／拒绝含义及副作用；分页字段和上限按实际资源限制确定 |
+
+以上为使用者对Q07确认的共用约定。已有正式契约不被本轮静默改写，差异按项目明确采用范围处理。
+
+### 4.2 契约与智能执行规则
+
+| 条款 | 统一要求 |
+| --- | --- |
+| CON-01 | 每项 API、事件和工具有准确身份、用途、提供／消费方、输入输出、权限、前置条件、错误及副作用；精确字段由 OpenAPI、proto 或适用 Schema 唯一维护，AD 写清语义及映射 |
+| CON-02 | 空值、缺省、默认值、枚举、时间、金额、大整数、分页和错误格式必须明确；已确认的共用惯例按§4.1执行，未统一指定的字段名或数值由项目决定，不由生成工具自行套用另一套惯例 |
+| CON-03 | 适用的写动作或长任务明确幂等作用域、输入判定、并发处理、同键不同输入、结果重放、去重保留及权限变化后的访问行为 |
+| CON-04 | 接收任务不代表业务完成，超时不自动代表失败。结果未知时按权威结果查询或对账，再确定是否重试；重试责任、总预算、取消与补偿由 AD 定义 |
+| CON-05 | 事件明确提交关系、标识、数据权限、投递／确认、重复、迟到、顺序、重试和人工处理；不假定全局有序或恰好投递一次 |
+| CON-06 | 契约新增、删除及语义变化均核实际消费者和旧版本，明确并存、升级、弃用与回归；版本号或 Schema 通过不能独自证明语义兼容 |
+| AGT-01 | 模型负责理解和建议，正式授权、输入校验和业务状态迁移由确定的服务规则执行；模型回复或工作流结束不独自证明业务成功 |
+| AGT-02 | 采用持久工作流时，按选定版本核对重放、Activity 和重试语义，落实确定性编排、副作用去重、未知结果对账及故障恢复；不得把本轮资料整理记为运行验证 |
+| AGT-03 | 模型、Prompt、工具描述与流程版本分别追踪；不能暗中替换模型。知识检索、记忆和多 Agent 按需设计，资料与工具返回不能修改系统权限 |
+| AGT-04 | 定义模型／工具调用、Token、时长、并发和循环预算，以及超限、取消和人工处理行为；具体数值依据业务和工程事实，不能由模板填造 |
+
+来源：软件技术说明第 7、9、10 章。具体业务接口、事件、工具和模型尚未提供；它们属于对应主题 AD 及正式契约的后续设计内容。
+
+## 5. 数据、状态与跨主题责任
+
+- DATA-01：每项正式业务实体、共享字段、状态及共享文件明确唯一逻辑维护责任与受控读写边界。共用数据库实例不代表允许跨模块任意读写。
+- DATA-02：业务数据、执行历史、Agent 会话、缓存和检索索引分别说明权威来源、保存范围、过期语义、恢复及清理责任；临时或派生数据不能冒充正式结果。
+- DATA-03：ER 图、字段字典、API、事件和 UI 的对应关系由各 AD 明确。标识、主外键、基数、唯一范围、默认值、精度及序列化必须有准确来源；不虚构业务实体或本地表。
+- DATA-04：各关键动作写清本地事务、并发冲突、重复请求及失败恢复。跨服务业务更新和消息发送必须明确补发、补偿或对账责任，不能以“先查后写”代替必要的一致性设计。
+- DATA-05：状态迁移、终态、撤销、重开、删除和保留要求来自 PRD 及实际项目决定；不能用技术规约新增权限、删除能力或保留期限。
+- DATA-06：索引根据真实查询和数据特征设计，并核写入及维护成本；迁移、初始化、回填、备份、应用回滚和数据恢复分别说明。
+
+命名、跨端大整数标识、时间点和错误关联的共用惯例按§4.1执行。主键生成、审计字段、实际时区／格式、删除方式和保留期按项目与业务依据落实，见Q07、Q10；具体实体及提供／消费责任从选定PRD和主题AD形成，见Q12，不要求提前填入通用规约。来源：软件技术说明第6—7、9、11、13章、当前AD模板及使用者确认。
+
+## 6. 工程组织、质量与原方法衔接
+
+### 6.1 工程骨架与文件责任
+
+- ENG-01：工程骨架沿用现有[目录规范1.0.0](../../engineering-skeleton/directory-standard.md)和[采用说明1.0.0](../../engineering-skeleton/adoption.md)。`pbc-composite`与`agent-standalone`是组织方式，frontend、backend、agents、jobs及配套契约、共享代码、测试和交付位置按需采用；内部遵循实际语言／框架惯例。
+- ENG-02：目录规范是实际可读的设计输入，可以在工程创建前采用。AD记录规范来源／版本、业务项目根、已有／拟建工程和模块映射；未采用代码框架模板时如实说明，不要求预先取得企业代码模板或冻结首套完整技术栈。
+- ENG-03：AD §9.2明确源码、模块、配置、测试、契约及装配位置，§9.6说明已有工程与拟建内容；原Plan把预计新增／修改文件路径、依赖和验证写入任务；获准的Build在这些位置生成实际内容，核对文件落点并执行原有测试／构建。
+- ENG-04：共享底座、契约和文件只有一处维护责任及实际任务来源，其他主题引用依赖；新增 PRD 不自动复制底座。再次生成或更新时保留人工修改、历史及已完成任务，冲突先核范围。
+- ENG-05：目录规范不要求另建project.yaml、templates.lock、contracts.lock、生成记录库或代码模板三方升级流程。已有项目或工具确有这些文件时按其实际用途保留；项目另行要求复用特定代码模板时，才取得该模板及所需版本、应用和验证依据。
+
+可以在现有AD的骨架栏目写明“目录规范已采用；工程拟建；未采用代码框架模板”，不能据此声称“可运行代码模板已取得”或“代码已生成”。实际目录来源为本资源附带的1.0.0定版资料；资源目录和i3维护工作区均不是业务工程输出根。
+
+既有工程先映射实际目录，不为套规范移动或重建。实际有内容时再建所需位置；项目根的构建／CI配置与框架原有布局允许按实情保留。目录检查、代码存在、构建、启动、业务验证和发布分别取证。
+
+来源：现有工程骨架目录方案、目录规范／采用说明1.0.0，以及当前AD §9.2／§9.6的对应栏目。本轮只引用这些资源，不修改工程骨架工作树或SOP运行模板；原命令的读取与实际落点继续按对应工程验证任务取证。
+
+### 6.2 工程命令与编码规范
+
+| 用途 | 根据实际情况填写的内容 | cwd、环境与成功依据 |
+| --- | --- | --- |
+| build | 实际构建工具／脚本、参数和交付产物 | 各工程自己的工作目录、运行时、依赖、配置及产物判据 |
+| test | 实际测试命令、执行层级、范围和参数 | 测试目录、数据／依赖、退出条件及结果位置 |
+| lint／类型检查 | 实际静态检查或类型检查入口；只检查和自动改写分别说明 | 工程根、配置及规则来源、允许副作用和失败判据 |
+| dev | 实际本地启动命令及必要参数 | 工程根、依赖、配置引用、实际端口和就绪检查 |
+
+这里填写业务工程的终端命令；`/i3-build`、`/i3-test`等是交给模型的工作入口，两者用途不同。命令拼写不要求所有工程一致，也不把i3-composer-agent包自身的npm命令当作业务命令。
+
+已有工程从真实脚本、构建配置和代码中取得命令、cwd、前提及风格示例；新工程由AD注明拟建入口和当前缺口，原Plan安排初始化及验证任务，获准Build创建后实际验证，再在获准的工程说明中据实记录。未验证的命令不写成已经可运行；业务稿需要修改时另按明确修订范围处理。使用者无需在采用通用基线时手工编造全部工程命令。
+
+### 6.3 测试、工程边界与事实记录
+
+- QA-01：针对实际需求选择规则、契约／集成、前端／端到端、Agent 行为与恢复、性能／安全／部署验证；测试框架、层级、目录和目标由实际项目补足。独立 TestCase 文件不是起草 AD 或所有 Plan 的统一前置。
+- QA-02：覆盖正常、拒绝、异常、重复、结果未知及恢复等适用行为；Agent 的程序测试与行为评测分别记录。替身能验证的范围与真实依赖联调分开，不能以 mock 关闭要求真实集成的验收。
+- QA-03：保留项目和原方法已有质量下限。新增性能、容量、可用性、覆盖要求、恢复目标、告警、保留期和预算阈值由PRD、适用规范或真实工程决定提供，写清测量范围、环境、目标和方法；不统一填造模板示例数字，见Q10。
+- QA-04：原 SPEC 的目标、命令、项目结构、代码风格、测试策略及工程边界，须在本次有效 PRD、AD、规约和必要配套中有可回读依据。未定项按影响处理，不能仅凭本规约存在就宣称六项齐备。
+- QA-05：Always／Ask first／Never 沿用适用项目规则、原 Skill 和真实用户决定；输入冲突需说明，不能降低要求。已有授权按真实范围复用，本文件不自造业务审批、开工或发布许可。
+- QA-06：来源、假设、候选、人工选择、认可、实际执行和业务验收分别记录。最终新增要求逐条回源，表格核列数与列义，末次修改后回读最终稿；缺证据保留未知。
+
+来源：软件技术说明第 9.8、12、14—17 章，当前 AD 模板和交接合同。
+
+## 7. 版本兼容、交付与恢复
+
+- DEL-01：文档、正式契约、代码提交、依赖、制品、配置和运行环境分别定位版本；不强制所有主题 PRD／AD 同号，也不机械升级无关主题。
+- DEL-02：GitLab 实例、仓库、保护规则、MR、Runner、CI 模板、镜像库、变量及环境权限按实际资源填写。设计方案、资源存在、配置完成和真实验证分开记录；企业 GitLab 方向不改动 i3 工具仓库自身的 GitHub 工作流。
+- DEL-03：流水线按项目实际组合变更检查、测试／评测、构建、迁移／部署、部署后验证及放行。每项明确触发、身份、输入、通过条件、失败处理和证据；本文件不宣称这些流水线已经存在。
+- DEL-04：K8s／Dapr 配置基于所选版本和实际需求确定工作负载、入口、运行身份、组件作用域、资源、探针、优雅退出、网络及密钥引用。端口、实例数和部署工具未定时不得猜测。
+- DEL-05：发布前明确契约与数据、提供方与消费方、应用与配置的兼容顺序；处理在途工作流和任务的版本绑定、完成、迁移及退出条件。
+- DEL-06：应用回退与数据恢复分别设计。流水线或动作重试不能重复迁移或覆盖有效结果；不可逆操作须明确恢复限制，生产发布沿用真实人工放行要求。
+
+来源：软件技术说明第 4.3—4.4、7.5、9.4、13 章。当前没有部署、恢复或生产验收结果。
+
+### 7.1 部署文件、环境事实与Ship分工
+
+| 内容 | 形成与维护方式 | Ship如何使用 |
+| --- | --- | --- |
+| Dockerfile、K8s配置、Helm或其他实际选用的部署文件、GitLab CI配置 | AD明确需求和适用方式，原Plan安排任务，获准Build创建并验证；未选工具不默认全部引入 | 核部署输入、迁移、配置及验证证据，不把检查报告当作配置已生成 |
+| 版本、环境、发布顺序、检查项、迁移和回滚说明 | 根据真实实现、部署配置及环境信息整理；需要保存额外清单时明确本次目标 | 原Ship汇总发布前检查、GO／NO-GO决策与回滚；可按明确任务整理部署准备说明，不设新默认输出文件 |
+| 集群、命名空间、域名、Runner、镜像库、凭据引用等 | 从真实平台和项目取得，按构建、联调、部署及发布依赖分别落实；配置只保存引用 | 检查实际就绪程度，缺项照实报告，不编造地址、权限或已配置事实 |
+
+这一路径不修改原`/i3-ship`：先有设计与任务，再形成工程部署资料，最后按原命令完成发布前审查和回滚准备。生产环境参数无需全部成为AD起草前置；发布条件和实际发布授权继续分别判断。
+
+## 8. 确认结果、项目待落实项与变更影响
+
+| 编号 | 已确认的共用处理 | 项目仍需落实的内容与影响 | 处理时点 |
+| --- | --- | --- | --- |
+| Q01 | 本文作为可复用企业技术基线，项目明确采用准确版本 | 项目名称、维护责任、范围和既有规范由项目采用说明／AD绑定；不在公共规约预造业务身份 | 实际项目采用时 |
+| Q02 | 首套普通业务后端采用Java＋Spring Boot方向，与Python Agent分工 | §2.3已明确JDK／Boot／Maven／JDBC目标；核实际工程依赖、企业框架复用、启动及序列化，不将版本确认写为兼容已通过 | 相关详设和工程任务按依赖核实 |
+| Q03 | 保留Vue 3＋TypeScript＋Antdv Next，工具链采用Vite、类型检查和Vitest方向 | §2.3已明确首套前端版本；核实际依赖／锁文件，按需引入路由／状态管理，安装／类型／构建／测试结果仍待验证 | 初始化及依赖安装前核实，生成后验证 |
+| Q04 | Dapr／Agent按实际需要的能力建立组合版本和验证安排 | 按§2.3固定所用版本；在保留的K8s 1.28上验证实际安装、必要业务链、中断恢复、重复与授权失效，离线渲染不替代运行证据 | 依赖相关能力的设计／工程阶段分别核实 |
+| Q05 | PostgreSQL优先兼容企业已有受支持版本，逻辑责任与恢复分别设计 | 先定位已有服务端；17.11仅是无既有约束的新建候选，驱动42.7.14已定，扩展／实例／迁移／DDL／恢复仍须真实证据 | 数据工程设计、迁移及运行前 |
+| Q06 | 统一身份采用MaxKey，通过OIDC接入；业务服务执行最终授权 | 4.1.12为首轮接入基线，投产前核4.2.0安全更新；取得实际实例／类型、应用注册、映射、退出撤权及配置引用，不虚构claims或可用能力 | 身份相关契约和实现前 |
+| Q07 | API camelCase、数据库snake_case、跨端大整数ID字符串、明确时间点时区、稳定业务码与关联标识 | 正式契约补精确字段、分页上限、格式／精度、主键生成、审计及存量映射，避免擅改已有契约 | 相关公共契约及主题AD定稿前 |
+| Q08 | 引用现有目录规范／采用说明1.0.0，沿用原AD→Plan→Build的目录映射链 | 明确业务根及真实／拟建路径；目录规范可先采用，实际代码由获准Build生成验证；只有另行要求特定代码模板才须取得该模板 | AD映射、Plan任务文件路径、Build实际落点依次核对 |
+| Q09 | AD规定部署要求，Plan安排任务，Build形成配置，Ship核验汇总部署准备 | K8s 1.28和GitLab 19.2.4为使用者提供的环境；补完整集群信息、Runner及实际资源／权限／配置，部署资料不冒充平台已就绪 | 构建、联调、部署和发布按需落实 |
+| Q10 | 保留已有质量下限，新增指标从PRD或真实工程决定取得 | 质量、容量、恢复、预算、保留、告警与适用要求的具体值和测量方法属于项目；不得填造通用数字 | 对应测试设计、处理数据或放行前 |
+| Q11 | 根据实际情况填写各工程命令、cwd、前提、成功依据和风格 | 已有工程读取真实配置；新工程按任务创建并验证，未验证保持实际状态；不要求用户预先写假命令 | 本次规划与任务执行按依赖补足 |
+| Q12 | 具体业务主题及数据／契约责任从选定PRD和各主题AD形成 | 绑定实际接口、事件、工具、实体和提供／消费方；不把它们作为通用规约必须提前填完的内容 | 每个主题AD与必要关联契约设计时 |
+
+上述共用规则及处理方式不再保持“全部待确认”。项目采用、具体版本、配置和运行结果仍需各自真实依据，不能因使用者同意规则就自动关闭。缺项只限制依赖它的范围，不无差别阻断AD起草或不相关的准备任务；也不能因文档生成完成而填造工程结果。
+
+改变公共条款、技术栈、共享契约、数据责任或骨架时，应记录旧→新内容、原因、来源、直接及必要传递消费者、受影响 AD／AC／TestCase／任务、验证及恢复安排。公共规则在其权威位置维护；单份 AD 不静默覆盖公共约定。保留未受影响内容、人工修改、旧稿和已完成任务。
+
+## 9. AD、Plan 与 Build 的采用和交接
+
+### 9.1 进入 AD
+
+1. 在具体业务项目明确采用本规约的路径、版本和适用范围；先核已有规范及冲突，不凭安装或发现文件自动启用。
+2. 选定准确 PRD 主题和版本。起草／修订 AD 必须按企业入口加载原 Spec Skill，使用完整 AD 模板；本公共规约本身不替代主题规格。
+3. AD §0.3登记本规约及目录规范／采用说明的来源和版本，§2.2落实技术选择，§9.2映射工程及模块位置，§9.6区分现有工程和拟建内容；目录规范可在代码生成前采用，保留三图和全部详设责任。
+4. 原型按需，可与 AD 并行。记录假设和受影响未决；候选生成、完整回读和人工认可分别处理，保存后遵守原 Spec 停轮。
+
+以下任务在项目明确取得并采用本版规约后使用；资料由实际加载的SOP Skill的references及辅助清单定位，不要求使用者填写安装内部路径。文件存在不证明项目已采用，已有安装不被假定包含本地候选：
+
+```text
+/i3-sop ad
+本次采用我明确提供的《企业应用公共技术规约 v0.0.4》作为公共技术依据；按本次选定SOP Skill资源索引定位。
+先确定当前业务项目、我已选定的 PRD 主题和准确版本；存在歧义先问。
+实际读取这份规约、其引用的工程目录规范／采用说明1.0.0及本次必要来源，列出适用条款、已有规范冲突和影响本主题的项目缺口。
+按原 Spec Skill 和完整 AD 模板生成本主题设计，保留三图、工程细节和 SPEC 六项。
+沿用§2.3已确认的版本矩阵，保留既有K8s 1.28与GitLab 19.2.4；逐项区分目标与实装，未验证的兼容性、具体字段和工程映射按实际来源补足。
+按现有目录规范明确本主题源码、模块、配置、测试和契约的已有／拟建位置，不要求预先提供一套代码框架模板，也不宣称工程已生成。
+保留已有人工修改，回读最终稿，交我审阅后停轮，不进入 Plan 或 Build。
+```
+
+### 9.2 交原 Plan
+
+以选定AD为入口，读取其准确PRD、本规约适用条款、共享契约、目录规范／项目采用说明和已有代码；尚无代码时如实记录拟建，不虚构工程根。按主题加载完整必要内容，核本范围SPEC六项和FR／AC；Plan任务保留真实／拟建文件路径及验证依据，不全量注入无关AD和历史。
+
+可以手动给实际路径，不必先建立 JSON。用户明确选用并允许登记时，现有清单只在 `selected.technicalBaseline` 保存本规约的实际路径，主题 AD 保存于相应主题引用；清单仍只保留 `schemaVersion`、`scope`、`selected`。本次没有建立或改写业务 JSON，也不把文档完成视为已选用或已批准。
+
+```text
+/i3-plan
+以我本轮明确选定的AD为规划入口，实际读取它引用的PRD、公共技术规约适用条款、共享契约、工程目录规范／采用说明及已有代码。
+公共技术规约使用本次明确采用的准确路径和版本，不仅凭清单存在判断已读。
+核对本主题需求、验收条件、SPEC 六项、共享依赖和未决影响；TestCase 按需引用。
+按AD的工程／模块映射，将每项任务预计新增或修改的文件路径、真实来源、初始化或增量内容及验证依据保留在原计划和唯一任务目标中，交我审阅，暂不实施。
+```
+
+### 9.3 进入 Build 与后续验证
+
+原 Plan 保留 `tasks/plan.md` 和项目选定的唯一任务目标，不被本规约替换；计划获真实认可后，原 Build 或 Build auto 按原规则执行。Build 应回读任务及必要设计；输入或同路径内容变化时先核影响，不能用新规约偷偷替换旧任务依据。原技能、命令、Git 条件、认可和风险停点完整保留。
+
+测试设计写预期与方法，实际测试写执行结果，原 review 审查真实变更；它们各自保留职责。模板完整、文档审查、实际安装、工程构建、集成、业务验收和生产发布分别取证。
+
+### 9.4 本次交付结论
+
+本版保留2026-10-20／21确认的共用规则、技术版本矩阵、本机及既有平台事实、官方依据与V01—V06验证安排，并按2026-10-22确认将工程目录及采用说明统一为1.0.0。Q02—Q06、Q09区分已选择版本与仍待取得的环境／运行证据；其他已确认规则保留。K8s 1.28继续保留，三组Dapr离线渲染不作为真实集群通过证明。
+
+本文件可供人工审阅，并可在明确选用后作为 AD 的公共输入。它不证明某项目的整体技术设计已经批准，也不证明所有主题可交 Plan、可直接 Build 或已通过运行验收。
+
+版本记录：v0.0.4（2026-10-22）统一SOP Skill内的工程目录来源1.0.0及资源引用，技术选型、版本矩阵和验证边界保留。通用模板、AD模板、原版Skill／命令、已有UI原型能力与业务稿未改。未执行技术栈安装、升级、部署或npm发布，i3发行版本未调整。

package/skills/i3-enterprise-sop/references/technical-baseline/readme.md

@@ -0,0 +1,132 @@
+# 公共技术规约：采用说明
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+资源版本：0.4.0；通用模板内容版本：v0.0.1；可选企业应用技术规约：v0.0.4；引用同一SOP Skill内的工程目录规范／采用说明1.0.0。发行只保留当前资源，不附旧版或归档副本。当前本地候选的打包、安装及真实宿主行为分别验证，暂不发布。
+
+本资源帮助项目固定共用工程约束及其来源。已有规范优先，新项目缺少规范时才起草最小候选。它不是第五个业务阶段、总AD、项目配置或批准记录；不新增Skill、命令、路由和执行器。
+
+## 0. 模板与可选技术规约
+
+| 资料 | 用途与采用边界 |
+| --- | --- |
+| [公共技术规约模板](templates/technical-baseline.md) v0.0.1 | 根据项目真实资料起草规约，或核对已有规范的覆盖；不默认技术栈 |
+| [企业应用公共技术规约](baselines/enterprise-application-technical-baseline-v0-0-4.md) v0.0.4 | 保留已确认的技术条款、版本矩阵和环境／验证边界；统一引用同一Skill内的工程骨架1.0.0，项目明确选择后才生效 |
+| [工程目录规范与采用说明](../engineering-skeleton/readme.md) 1.0.0 | 与本规约引用同一份资料；提供工程职责及AD→Plan→Build映射规则，不是可运行代码模板 |
+
+随包提供不等于所有项目默认采用。项目已有适用规范时先复用；选择本规约时记录准确路径、文内版本、适用范围及必要差异。多个版本或来源并存且未明确选择时先确认，不按目录最大版本猜选。
+
+项目需要调整时，沿用项目现有规范位置或明确维护项目副本；发行原件与项目规范分别定位。项目自改副本优先，不用发行摘要恢复它，不在升级时覆盖项目规范；不可读或存在冲突时如实报告，不静默切换。
+
+最短任务示例：
+
+```text
+/i3-sop ad
+为当前选定的PRD生成AD，采用我明确提供的《企业应用公共技术规约 v0.0.4》。先核项目已有规范和适用范围，按本次资源目录定位并完整读取规约及必要目录资料；版本以规约§2.3为准，兼容验证按§2.5安排，保留项目自改内容和未决项，生成后交我审阅，暂不进入Plan或Build。
+```
+
+资料由本次实际加载的SOP Skill的references/stages.json中auxiliaryResources定位，再读取本清单baselines条目，不要求使用者填写安装内部路径。当前候选是否可用以实际安装内容为准；项目自改资料不被发行来源替换。原版Skill／命令和标准流程保持。
+
+## 1. 先核对来源，再选择采用方式
+
+只在用户明确采用企业SOP或明确要求本项技术资料任务时使用。安装、出现PRD字样或发现本文件，不代表项目已启用企业SOP；标准任务继续使用原方法。
+
+先实际读取项目说明、明确提供的规范和已有采用记录；目录列表和自动上下文只能作线索。不扫描全部项目、宿主、历史样例或备份来猜规范。
+
+资源位置与项目规范来源分开判断：
+
+- 对本资源，实际读取本次选定目录的README、清单和所选模板；明确采用的项目自改副本优先，已选根不可读或损坏时报告缺项，不换发行原件或全局新版。
+- 对项目规范，优先复用项目已明确采用且适用的集团／平台／工程规范、CONSTRAINTS、ADR及正式契约。已有代码和锁文件提供实现事实，不自动成为替换规范的决定。
+- 用户本次明确材料与既有采用发生冲突时，同时保留并核对适用范围；本次提供文件不自动授权覆盖原规范、取消约束或切换全项目采用。
+- “规范未提供／未读取”与“项目确认没有规范”分开。不可读、无适用版本或存在冲突时，记录准确缺口及影响；不能从缺文件推断不存在。
+
+## 2. 路径一：已有适用规范
+
+1. 读已有规范及采用记录，固定可回读内容与本项目适用条款。可使用准确版本加固定提交、不可变快照或实际计算的摘要；未计算就明确说明。只有版本标签和可变链接不足以区分内容时，补固定依据。
+2. 用模板核对覆盖，沿用已有位置、身份和格式。内容已完整时，只在现有采用说明或本次唯一明确目标中记录引用及真实缺口；不复制全文、迁移文件或要求填一份同构大文档。
+3. 公共规则直接引用唯一权威。仅当实际存在项目特定约束时补充有来源的差异，注明维护位置和适用范围；有冲突先列Q，不悄悄覆盖。
+4. 记录本次AD如何引用这些规则的方式即可，不自动生成或修改AD。每份AD仍需自己的三图和完整工程设计。
+
+最小采用记录可以使用项目现有表格表达，无需新的registry：
+
+| 记录项 | 需要的实际内容 |
+| --- | --- |
+| 来源与固定内容 | 规范身份、权威位置、版本／固定提交或真实摘要、实际读取范围 |
+| 本次适用 | 项目／工程／主题范围、准确条款、实际采用依据；阅读不等于采用或批准 |
+| 落实与差异 | 项目补充或AD引用位置、例外及真实决定；无差异就直接引用 |
+| 项目本地修改 | 当前副本与发行来源分别记录；同名同版本改变后旧证据不自动沿用 |
+| 缺口与交接 | 未读、未知、冲突、需何答复、只影响哪些动作和独立可继续部分 |
+
+已有文件或人工修改先读并保留，不用发行摘要恢复项目副本。已有采用说明已足够时，可以只提出只读核对结果；是否写入及唯一目标由本次实际授权决定。
+
+## 3. 路径二：缺少规范时起草最小候选
+
+先确认已取得的项目事实与已查范围；未知保持Q。按模板涵盖共用架构、技术工程、身份安全、契约通则、共享数据、工程质量、交付恢复、维护例外八个领域。可以直接固定引用，不强制拆出八份文档或重复已有材料。
+
+沿用项目既有位置；没有约定时，可建议 `docs/engineering/{项目名称}-技术规约_v0.0.1.md` 作为共用辅助文档。建议路径不是已经存在、已采用或可覆盖的事实。核心业务文档的一能力一目录和主题命名保持。
+
+没有事实时，不默认框架、数据库、消息中间件、部署平台、权限、责任人、保留期限、质量数字或命令。项目已明确采用的公共平台约束应引用保留，准确版本和工程细节未取得时列Q，不重新选另一套默认。项目尚未建成时，命令、目录、风格示例和环境可以待定，不编造已运行证据。
+
+最小候选不要求全项目技术问题先清零。AD可先起草独立部分，原型按需并行；共同定义未决时，只限制依赖范围。交原Plan前补齐当前有效规格六项、依赖范围的共用定义和必要真实认可；Plan形成、获准逐任务Build及真实工程验收分别核对，不要求起草规范前已有构建通过。
+
+## 4. 规约、契约、AD与版本
+
+| 内容 | 唯一维护责任与交接 |
+| --- | --- |
+| 公共技术规约 | 维护共用原则或准确权威引用；不替代产品规则、CONSTRAINTS或ADR |
+| 正式接口／事件／数据定义 | 每项一个权威位置，字段与行为分担时明确范围；可先用提供方AD固定章节，不强制新协议或拆文件 |
+| 主题AD | 对应选定PRD完整设计，固定规范版本、条款、提供／消费契约及落实／例外；不包办另一主题PRD |
+| TestCase／实际报告 | 预期直接核PRD，技术判据核AD及契约；候选、真实执行和人工认可分开 |
+| 工程登记与锁 | 记录实际选择、正式采用、应用及验证事实；不另建架构权威或任务tracker |
+
+同一PBC多份主题PRD各自独立版本，每份配套逻辑AD及TestCase；文档不要求同号。规范版本、契约版本、代码／制品和环境分别固定。兼容核实际消费者、字段及语义、迁移和运行组合，不能靠版本号或Schema通过下结论。
+
+共享数据、状态及文件明确唯一逻辑维护责任与受控写入；前端、后端、Agent及jobs各自状态不能代替正式业务结果。具体角色、事务和数据保留必须有产品／规范依据。
+
+变更先固定旧／新内容及来源，定位直接和必要传递的契约、AD、AC、TestCase及真实任务，区分不受影响范围。人可人工修改、明确委托修订、有据不采纳或保持Q；不自动重写全项目、自动升版或承接旧批准。外部契约正式采用与模板实际应用并验证的锁分别留证，本作业不自动创建锁。
+
+## 5. 写入、审查与退出
+
+写前列明项目根、已读资料、已有规范／采用记录、固定来源、假设／Q、唯一目标和本次权限。先读现稿，保留人工内容和原报告；仅写明确获准目标，未知权限或覆盖风险时先说明。
+
+最后编辑后实际回读：新增要求逐条回查来源，规范与权限描述一致，逐表检查表头列数和列义。摘要、版本与内容相符，不要求文档写自身摘要。
+
+审查只标注问题、来源、位置、影响与建议，保留人工修改空间。只有真实独立新上下文才称独立审查，无隔离能力时提供新会话任务；自查不冒称独立。修订另行明确，不为清零代答业务或技术决定。
+
+完成后报告来源／目标、复用方式、补充与Q、实际验证和未执行事项，交人工审阅并停轮，不自动进入AD、Plan、Build、测试执行、提交或发布。
+
+## 6. 可复制任务说明
+
+可明确提供本资源目录或项目已采用副本，也可在明确企业任务后按[上层入口](../readme.md)及其索引定位本辅助资源。源码登记不等于宿主自动发现，以下均为明确任务，没有新增slash命令。
+
+已有规范：
+
+```text
+本次只做公共技术规约采用核对。使用我明确提供的公共技术规约资源，先实际读取该目录README、清单和模板，再读取当前项目说明、已有规范及采用记录。
+优先复用项目已采用规范，固定来源、内容与适用条款；已有资料完整时只记录引用和真实缺口，不复制一份新规范，不覆盖原规范或人工修改。
+写前说明事实、假设、未读取项和唯一获准目标。位置按项目已有约定选择；若存在歧义或覆盖风险，先说明，不新建另一套registry。
+不把阅读当采用、把采用当批准；冲突按影响保留Q，不自行改选型或权限。最后回读候选，新增要求逐条回源，权限描述一致，表格逐行核列数与列义。完成后交我审阅并停轮。
+```
+
+新项目或资料不足：
+
+```text
+本次只起草项目公共技术规约候选。先读取我明确提供的资源README、清单、模板及当前项目资料，确认已有规范、已查范围和未取得内容；如果找到适用规范，优先采用它。
+确实缺少规范时，按模板只写当前有依据的最小候选，可用固定引用代替重复正文。框架、版本、责任、权限、质量数字、命令和运行结果没有来源就列Q，不填默认答案。
+沿用项目已有位置和命名，只写本次明确的唯一目标，保护人工内容。草拟不冒充可计划或获准Build；每份主题AD仍须三图及完整设计，原型按需。
+最后实际回读，逐条核新增要求来源、权限一致性及表格列数／列义，列出缺口和未执行事项，交我审阅并停轮。原版技能和命令不动，不写AD、Plan、工程或测试结果，不提交发布。
+```
+
+## 7. 资源范围与后续接入
+
+本子目录包含采用说明、通用模板、唯一当前可选技术规约及局部清单。工程目录资料位于同一SOP资料根的engineering-skeleton，不复制到技术规约内部。entry、template、baselines[].path、files[].path及requiredSources[].path均相对本manifest；依赖可在所选SOP根内引用，不能越界。
+
+上层stages.json登记辅助资源根与清单，局部baselines条目列出可选规约的身份、版本和必要来源；不设置默认采用，不增加配置系统、审批字段或自动调度。清单的文件摘要固定发行资料，本轮变化检查不用于恢复或覆盖项目副本。
+
+B01—B05和原S10记录保留各自版本与验证范围。本次只整理分发资源及引用，打包／安装可读性另取新证据；静态、安装、真实模型行为、项目采用与正式发布分别判断。原型仍按需，TestCase不作为Plan统一必需输入，原Spec及Plan／Build停点不变。