@givolt/i3-composer-agent 2.3.7 → 3.0.0

package/references/enterprise-sop-resources/technical-baseline/assets-manifest.json

@@ -0,0 +1,101 @@
+{
+  "schemaVersion": 1,
+  "resourceId": "i3-enterprise-sop-technical-baseline",
+  "resourceVersion": "0.2.0",
+  "resourceRole": "auxiliary-shared-engineering-guidance",
+  "status": "local-technical-baseline-distribution-candidate",
+  "businessStage": false,
+  "templateContentVersion": "v0.0.1",
+  "entry": "README.md",
+  "template": "templates/TECHNICAL-BASELINE.md",
+  "files": [
+    {
+      "path": "README.md",
+      "sourceSha256": "9fd3b21cc2f45722d289c7dab3cb75e082865f49ddf1b16d3b2595116dbbcc46",
+      "sha256": "dfcbe6868a29cb99b6a26e779301bebf5c0b53658039a9eb6301553aea143f6c",
+      "role": "adoption-guidance"
+    },
+    {
+      "path": "templates/TECHNICAL-BASELINE.md",
+      "sourceSha256": "f14db13050b97abc3b1bbe253a12218316127df2b3f96b4593e598aadf90b6f1",
+      "sha256": "83f425b2333a5dd10b79a89007a0732b4d273cdc694fd9a7b93bc6527fd5c2f1",
+      "role": "auxiliary-engineering-template"
+    },
+    {
+      "path": "baselines/企业应用-技术规约_v0.0.2.md",
+      "role": "optional-project-technical-baseline",
+      "sourceSha256": "04d42104f4e08ec1150e57930c785e22e8518c735627f5784df255e07cb367f6",
+      "sha256": "c355a720526616f70cc9498452883ca577920f239718905950cdaad7b40709cd"
+    },
+    {
+      "path": "baselines/PROVENANCE.md",
+      "role": "baseline-distribution-provenance",
+      "sourceSha256": "ffbdd653c682cddc3bddcc0a06314c12165919ab0ce4193c5e672edda14632cb",
+      "sha256": "70f400e695813ff310b2f02402520ab19f0a884fb7c2e6c5ddbd8ea7a4262668"
+    },
+    {
+      "path": "references/engineering-directory-v0.2.0/directory-standard.md",
+      "role": "fixed-baseline-directory-dependency",
+      "sourceSha256": "3e9445d35e6ee5cf90bf2ba7de07dc26c82c7103ffe2ac50f32e5e99af660570",
+      "sha256": "08160c392465eb727cdd4e62aadd0ed024d0d578643e5015b4b71534836739b4"
+    },
+    {
+      "path": "references/engineering-directory-v0.2.0/adoption.md",
+      "role": "fixed-baseline-adoption-dependency",
+      "sourceSha256": "2ce821e718007ee2bf259e67db456183846a30b92da72a39982bf2f136631afa",
+      "sha256": "dd99b39c6a2e3f69592f8566455c5d73f35decb4b6ad61c797ba92038edbaf0a"
+    }
+  ],
+  "sha256Scope": "source-and-pure-brand-reference-mapping-not-npm-install-proof",
+  "dependencies": [
+    {
+      "path": "../ad/templates/AD.md",
+      "role": "ad-linkage-reference"
+    },
+    {
+      "path": "../handoff-contract.md",
+      "role": "native-plan-handoff-reference"
+    }
+  ],
+  "provenance": [
+    {
+      "path": "history/sop-design/20261018-before-b01-technical-baseline/technical-baseline-design.md",
+      "sha256": "30ce6f20516321ac651b2c443ae0007d1e3ee1c9dc8ea021552ac920367c97eb",
+      "included": false,
+      "role": "immutable-maintenance-design-provenance-not-runtime-dependency"
+    }
+  ],
+  "integration": {
+    "registeredInParentStageIndex": true,
+    "registeredInCustomRuntimeFiles": true,
+    "includedInParentResourceBundle": true,
+    "packagePolicy": "included-reference-assets-with-per-artifact-verification",
+    "automaticWorkflowActivation": false,
+    "newSkillOrCommand": false,
+    "proofBoundary": "File presence, pack, installation, model reads and project adoption are distinct."
+  },
+  "publication": {
+    "published": false,
+    "businessCandidateApproved": false
+  },
+  "baselines": [
+    {
+      "id": "enterprise-application",
+      "title": "企业应用公共技术规约",
+      "documentVersion": "v0.0.2",
+      "path": "baselines/企业应用-技术规约_v0.0.2.md",
+      "explicitAdoptionRequired": true,
+      "provenance": "baselines/PROVENANCE.md",
+      "requiredSources": [
+        {
+          "path": "references/engineering-directory-v0.2.0/directory-standard.md",
+          "contentVersion": "0.2.0"
+        },
+        {
+          "path": "references/engineering-directory-v0.2.0/adoption.md",
+          "contentVersion": "0.2.0"
+        }
+      ]
+    }
+  ]
+}

package/references/enterprise-sop-resources/technical-baseline/baselines/PROVENANCE.md

@@ -0,0 +1,40 @@
+# 企业应用技术规约来源与分发说明
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+## 来源资料
+
+本目录的[企业应用公共技术规约 v0.0.2](企业应用-技术规约_v0.0.2.md)是明确确认过的可复用技术基线。其直接来源为《软件架构设计 Specification 模板》v0.6（2026-09-23），并结合公共技术规约模板和2026-10-20逐项确认结果整理。原架构模板含历史总体设计／MVP组织说明，仅作来源追溯，不是当前SOP的第二套生成入口或项目必读依赖。
+
+| 来源 | 固定内容摘要（SHA-256） | 用途 |
+| --- | --- | --- |
+| 整理前的企业应用技术规约v0.0.2 | `989763c95dcccd6c79198b3d68b1669be52b399a523492219f8b3fbe236d49de` | 保存确认过的正文；本次仅整理位置、链接和示例中的资源定位方式 |
+| 软件架构设计Specification模板v0.6 | `0e3d73df26a10bb741f1f46e55161240b741f8afca5a61b9e87b35abeeb64364` | 原始技术来源；完整原稿保存在维护历史，未作为运行时资料分发 |
+| 公共技术规约模板v0.0.1 | `f14db13050b97abc3b1bbe253a12218316127df2b3f96b4593e598aadf90b6f1` | [通用模板](../templates/TECHNICAL-BASELINE.md)；模板正文未改 |
+
+摘要用于识别本次来源内容，不要求业务JSON新增摘要、审批或任务字段，也不阻止项目人工修改已采用副本。
+
+## 工程目录依赖
+
+技术规约v0.0.2已经确认引用目录规范／采用说明0.2.0，因此附带该版本的必要正文快照。来源为2026-10-20规约确认时保存的原件；不从正在调整的工程骨架工作树选取较新内容，不把0.3.0标成0.2.0。
+
+| 必要资料 | 内容版本 | 固定内容摘要（SHA-256） |
+| --- | --- | --- |
+| [工程目录规范](../references/engineering-directory-v0.2.0/directory-standard.md) | 0.2.0 | `3e9445d35e6ee5cf90bf2ba7de07dc26c82c7103ffe2ac50f32e5e99af660570` |
+| [采用说明](../references/engineering-directory-v0.2.0/adoption.md) | 0.2.0 | `2ce821e718007ee2bf259e67db456183846a30b92da72a39982bf2f136631afa` |
+
+两个正文逐字保留。目录说明是设计依据，不是已经生成的代码框架或工程验收证明。以后采用新版目录规范，需要明确核对变更与适用范围；本次没有升级其技术约定。
+
+## 维护历史
+
+规约v0.0.1、v0.0.2整理前全文、原HTML阅读页、来源模板及既有来源记录均保存在维护工作区的history；原S10候选、执行轨迹、失败和报告完整保留。它们不是同事安装后的运行时依赖。
+
+维护记录标识：`20261020-before-enterprise-technical-baseline`、`20261020-before-technical-baseline-confirmation`、`20261020-before-technical-baseline-distribution`。分发正文使用包内相对引用；具体安装路径以当前宿主的安装清单为准。
+
+模板内容版本v0.0.1、基线文档版本v0.0.2、辅助资源版本0.2.0和上层资料组合版本0.14.0各自管理，不等同于i3软件发行版本。此整理仍是本地候选，不表示已经发布或被某个项目采用。

package/references/enterprise-sop-resources/technical-baseline/baselines//344/274/201/344/270/232/345/272/224/347/224/250-/346/212/200/346/234/257/350/247/204/347/272/246_v0.0.2.md

@@ -0,0 +1,295 @@
+# 企业应用公共技术规约
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+## 0. 身份、范围与来源
+
+| 项目 | 当前内容 |
+| --- | --- |
+| 文档版本 | v0.0.2，2026-10-20；保留 [v0.0.1 的历史记录](PROVENANCE.md#维护历史) |
+| 文档性质 | 根据使用者逐项确认整理的企业共用技术基线；供具体项目明确选用，新稿文字仍可人工审阅修改 |
+| 适用范围 | 明确采用本文件的企业业务项目及其前端、业务后端、Agent、任务工程；各工程按实际需求采用 |
+| 项目绑定 | 本文件不绑定某一业务项目；项目名称、采用版本、PRD／AD与实际工程在项目采用说明或AD中记录，见 Q01、Q12 |
+| 直接来源 | [软件架构设计 Specification 模板 v0.6 的来源说明](PROVENANCE.md#来源资料)，含原文明确的技术方向及工程约束 |
+| 编排依据 | 当前企业 SOP 的公共技术规约模板、AD 模板及交接合同；工程组织引用现有目录规范0.2.0 |
+| 确认依据 | 2026-10-20，使用者确认Q01—Q05、Q07、Q10、Q12的建议方向，随后确认Q06采用MaxKey／OIDC、Q09职责分工、Q11据实填写；Q08按现有工程骨架目录方案衔接 |
+| 维护与采用 | 共用规则及选型方向按上述确认维护；具体项目仍需记录采用版本、适用范围、责任和例外，不由本轮确认替代业务认可或开工许可 |
+| 现有证据 | 已读取来源、现有目录规范及相关原命令，核对MaxKey／Vue官方说明；尚未固定并验证完整软件版本组合，未生成业务工程，未执行安装、构建、测试、部署或发布 |
+
+本文件定位为可复用的企业共用技术基线，已写入确认的选型方向与共用约定。第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节；不扩展为版本兼容、业务批准或实际环境就绪 |
+| [公共技术规约模板及采用说明](../README.md) | 已有规范优先、公共规则与主题设计分工、候选与真实采用分开 | 本文件的范围、采用和版本规则 |
+| [当前 AD 模板](../../ad/templates/AD.md) §0.3、§2.2、§9.6 | 基线引用、技术落实和真实骨架来源 | 各主题 AD 的对应条款 |
+| [当前交接合同](../../handoff-contract.md) §10 | 选定 AD 及必要配套交原 Plan，再进入获准 Build | 本文件第 9 节 |
+| [现有工程骨架方案的来源说明](PROVENANCE.md#工程目录依赖)、[目录规范0.2.0](../references/engineering-directory-v0.2.0/directory-standard.md)、[采用说明0.2.0](../references/engineering-directory-v0.2.0/adoption.md) | 工程目录与职责、AD映射、原Plan任务路径、获准Build的实际文件落点 | 本文件第1、6—9节；目录规范可先采用，不要求预先取得代码框架模板 |
+| [原Ship命令](../../../../.claude/commands/i3-ship.md)及[原Spec的内容要求](../../../../skills/i3-spec-driven-development/SKILL.md) | 发布前检查／决策／回滚，及原SPEC六项的工程命令和项目依据 | 本文件第6—7、9节；原命令与Skill未改 |
+
+源材料沿用总体 `design.md` 和旧 MVP 产物组织。本文件只提取其中适用的技术内容，并按当前已确认的“公共规约＋多主题 PRD／AD”组织；不恢复旧 MVP 流程，不改动源文件，不要求把公共规则复制到每份 AD。原文要求明确写出规则的目的继续保留：AD 必须指出准确规则、适用范围和落实位置，不能只写“沿用旧规范”。
+
+初稿来源快照保存在 [首次历史目录的追溯信息](PROVENANCE.md#维护历史)；本版修改前材料与保护范围保存在 [本版来源追溯信息](PROVENANCE.md#维护历史)。来源文件以后修改，不自动改变本规约或项目已经采用的版本。
+
+## 1. 共用架构与工程边界
+
+| 条款 | 共用规则 | 主题 AD 的落实责任 |
+| --- | --- | --- |
+| ARC-01 | 根据真实业务目标确定逻辑模块、工程、运行应用和部署单元；一个 PBC 不自动等于一个微服务、仓库或数据库 | 明确本主题组件职责、依赖、运行单元和部署关系，以及采用或拆分理由 |
+| ARC-02 | 前端负责交互与呈现；业务服务负责正式业务规则、最终授权、状态及数据；Agent 负责其获准的分析或工具执行；任务工程负责实际选择的触发、执行与恢复职责 | 给出三图和详设，绑定实际组件及数据维护责任；按需采用工程类型，不为凑目录新增服务 |
+| ARC-03 | 前端临时状态、Agent 会话或执行结果、工作流历史、任务状态与正式业务状态分别维护 | 写清各类状态的存储、可信来源、标识映射及最终业务完成条件 |
+| ARC-04 | Dapr 的运行支撑能力与项目业务授权、数据责任及人工决定分开设计 | 明确所用能力、组件、调用方向、业务校验和失败责任；服务能够互通不代表用户获准操作 |
+| ARC-05 | 缓存、向量检索、消息、GIS、三维、多 Agent 等按实际需求选择 | 给出需求来源、用途和选型；不使用时说明理由，未知时列为待确认 |
+| ARC-06 | 消费外部能力应依据正式契约，不复制提供方内部实现作为本主题权威 | 固定提供／消费关系和版本；分别记录已可用、待核实、待接入及真实联调条件 |
+
+来源：软件技术说明第3、5、8—11章；现有工程骨架目录方案及目录规范0.2.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 及适用原型确定 | Vue大版本为3；框架、组件库与工具链的精确兼容版本待核，见Q03 |
+| 前端工程工具链 | Vite＋TypeScript类型检查＋Vitest | 首套Web工程的构建、类型检查和单元／组件测试；路由和共享状态管理按需选择 | 工具链方向已确认；Node、包管理器及各依赖的实际版本组合待核，见Q03 |
+| 分布式运行时 | Dapr | 项目实际采用的服务调用、状态、事件或其他运行能力 | Runtime、SDK、组件与后端版本组合待核，见 Q04 |
+| 业务 Agent | Python＋Dapr Agents | 项目包含业务 Agent 时适用；未采用 Agent 的项目不生成 Agent 工程 | Python、框架、SDK及模型接入组合待核，见 Q04 |
+| 持久工作流 | Dapr Workflow | 经具体设计确定需要持久编排或恢复的场景 | 所用 SDK、Runtime、存储支持及版本策略待核，见 Q04 |
+| 目标运行平台 | Kubernetes（K8s） | 采用此企业基线的产品目标部署环境 | 集群版本、部署入口、命名空间与访问条件未提供，见 Q09 |
+| 主数据库 | PostgreSQL | 权威业务数据；执行历史、会话、缓存等用途另行明确 | 版本、扩展、驱动、实例和迁移工具待核，见 Q05 |
+| 代码与流水线 | 企业 GitLab＋GitLab CI | 业务项目的代码协作、构建和交付 | 实例、可用能力、Runner、仓库及产物服务待核，见 Q09 |
+| 普通业务后端 | Java＋Spring Boot | 首套普通业务后端选型方向，与Python Agent的职责和工程分别明确；可用的企业框架先核对复用条件 | 方向经使用者确认；JDK、Spring Boot、构建工具及依赖兼容组合由项目核实，见Q02 |
+| 统一身份与单点登录 | MaxKey＋OIDC | 企业统一账号与认证入口；角色和权限按实际采用能力映射，业务服务执行最终业务授权 | 方向已确认；实例、版本／类型、应用注册、用户／租户映射和失效行为在项目落实，见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/)。官方说明用于核对方向与条件，不代替本项目完整版本矩阵和运行验证。
+
+## 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：工程骨架沿用现有[目录规范0.2.0](../references/engineering-directory-v0.2.0/directory-standard.md)和[采用说明0.2.0](../references/engineering-directory-v0.2.0/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的骨架栏目写明“目录规范已采用；工程拟建；未采用代码框架模板”，不能据此声称“可运行代码模板已取得”或“代码已生成”。实际目录来源为本资源附带的0.2.0定版资料；资源目录和i3维护工作区均不是业务工程输出根。
+
+既有工程先映射实际目录，不为套规范移动或重建。实际有内容时再建所需位置；项目根的构建／CI配置与框架原有布局允许按实情保留。目录检查、代码存在、构建、启动、业务验证和发布分别取证。
+
+来源：现有工程骨架目录方案、目录规范／采用说明0.2.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分工 | 取得JDK、框架、构建及企业框架复用条件的实际版本；不能将方向确认写为兼容已通过 | 相关详设和工程任务按依赖核实 |
+| Q03 | 保留Vue 3＋TypeScript＋Antdv Next，工具链采用Vite、类型检查和Vitest方向 | Node、包管理器、各依赖版本、路由和状态管理需求及安装／构建结果待项目落实 | 初始化及依赖安装前核实，生成后验证 |
+| Q04 | Dapr／Agent按实际需要的能力建立组合版本和验证安排 | 固定Runtime、SDK、Python、Agents、Workflow及底层组件，验证必要业务链、中断恢复、重复与授权失效 | 依赖相关能力的设计／工程阶段分别核实 |
+| Q05 | PostgreSQL优先兼容企业已有受支持版本，逻辑责任与恢复分别设计 | 版本、驱动、扩展、实例、迁移工具、DDL和恢复方案仍须真实来源及执行证据 | 数据工程设计、迁移及运行前 |
+| Q06 | 统一身份采用MaxKey，通过OIDC接入；业务服务执行最终授权 | 取得实例、版本／类型、应用注册、用户／租户／角色映射、退出撤权及配置引用；不虚构claims或可用能力 | 身份相关契约和实现前 |
+| Q07 | API camelCase、数据库snake_case、跨端大整数ID字符串、明确时间点时区、稳定业务码与关联标识 | 正式契约补精确字段、分页上限、格式／精度、主键生成、审计及存量映射，避免擅改已有契约 | 相关公共契约及主题AD定稿前 |
+| Q08 | 引用现有目录规范／采用说明0.2.0，沿用原AD→Plan→Build的目录映射链 | 明确业务根及真实／拟建路径；目录规范可先采用，实际代码由获准Build生成验证；只有另行要求特定代码模板才须取得该模板 | AD映射、Plan任务文件路径、Build实际落点依次核对 |
+| Q09 | AD规定部署要求，Plan安排任务，Build形成配置，Ship核验汇总部署准备 | 实际环境、资源、权限及配置按依赖取得；部署清单和运行配置不冒充平台已就绪 | 构建、联调、部署和发布按需落实 |
+| 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 停轮。
+
+以下提示词供将来明确采用时使用，当前未执行此作业；`/i3-sop` 属于尚未发布的本地候选入口：
+
+```text
+/i3-sop ad
+本次采用 随包提供的《企业应用公共技术规约 v0.0.2》（按所选资源索引定位） 作为公共技术依据。
+先确定当前业务项目、我已选定的 PRD 主题和准确版本；存在歧义先问。
+实际读取这份规约、其引用的工程目录规范／采用说明0.2.0及本次必要来源，列出适用条款、已有规范冲突和影响本主题的项目缺口。
+按原 Spec Skill 和完整 AD 模板生成本主题设计，保留三图、工程细节和 SPEC 六项。
+沿用已确认的后端、前端工具链和MaxKey／OIDC方向，不重复猜选型；未确定的版本、具体字段和工程映射按实际来源补足。
+按现有目录规范明确本主题源码、模块、配置、测试和契约的已有／拟建位置，不要求预先提供一套代码框架模板，也不宣称工程已生成。
+保留已有人工修改，回读最终稿，交我审阅后停轮，不进入 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 本次交付结论
+
+本版已根据使用者确认补齐公共基线定位、普通业务后端、前端工具链、MaxKey／OIDC、接口惯例、目录规范采用、部署分工及按实情填写的规则。Q01—Q12现在区分已确认内容和项目待落实事项；实际项目采用、精确版本兼容和工程实施结果仍各自核验。
+
+本文件可供人工审阅，并可在明确选用后作为 AD 的公共输入。它不证明某项目的整体技术设计已经批准，也不证明所有主题可交 Plan、可直接 Build 或已通过运行验收。
+
+版本记录：v0.0.1（2026-10-20）为首次来源整理，原文完整保留。v0.0.2（2026-10-20）落实本轮确认，并引用当前工程目录规范0.2.0；不再把旧代码模板／工程锁方案作为统一前置。原说明、公共模板、AD模板、Skill、命令、SOP与工程骨架运行资源、业务稿保持原状，未提交或发布。

package/references/enterprise-sop-resources/technical-baseline/references/engineering-directory-v0.2.0/adoption.md

@@ -0,0 +1,112 @@
+# 工程目录规范的采用与原 Plan／Build 交接
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+版本：0.2.0。配套：[工程目录规范](directory-standard.md)。适用于明确选择该规范的新项目或现有项目，不随安装自动启用。
+
+## 1. 采用时明确什么
+
+先确定真实业务项目根、当前能力／需求主题、所选 AD 及已有代码位置。项目已有工程规范时优先复用；本资源补充目录职责或映射，不重选技术栈，也不把维护 i3 Skill 的仓库当成业务工程根。
+
+目录规范可以在 AD 准备时选定，无需另外调用一个工程骨架命令。技术栈、工程内部布局及构建命令仍由公共技术规约、实际配置和 AD 明确。目录规范能够先采用；尚未确定的技术决策只限制依赖它的设计或实施任务。
+
+将采用结果写入项目已有工程说明；没有合适位置时，可使用 docs/engineering/engineering-layout.md，或直接写在 AD 的相应章节。以下是填写要点，实际路径和状态据实填写，不为每个项目重复建立全部文档：
+
+| 项目 | 填写内容 |
+| --- | --- |
+| 采用来源 | 本目录规范的真实可读路径和内容版本 0.2.0；使用项目副本时保留其来源及本项目修改说明 |
+| 组织方式 | pbc-composite 或 agent-standalone；选择理由与项目根 |
+| 实际工程映射 | 工程稳定标识、类别、实际根、已有／拟建、业务模块、共享维护方与消费者 |
+| 配套依据 | 当前 AD 的身份／版本／路径、公共技术规约、必要契约及已有代码 |
+| 目录例外 | 现有结构或框架惯例与规范示例的差异、理由、影响及明确采用情况 |
+| 验证要求 | 本次文件落点核对及实际构建／测试方法；尚无代码时写待实施，不预填通过 |
+
+使用项目已采用副本后，以该副本为本次输入；发行资源更新不覆盖它。原路径失效、版本含糊或映射冲突时先说明准确缺项，不静默改读另一个来源。
+
+## 2. AD 如何引用
+
+沿用现有 AD 模板的栏目，不修改模板或原 Spec：
+
+| 现有 AD 位置 | 本次承接内容 |
+| --- | --- |
+| §0.3 公共技术规约、契约与骨架的本次采用 | 引用目录规范或项目采用说明的准确路径／版本，说明适用工程 |
+| §9.2 项目目录与维护位置 | 工程根、模块／源码、配置、测试、契约和运行装配的真实或拟建路径及 owner |
+| §9.6 工程骨架采用与落地 | 区分现有工程事实与拟建内容；落实当前技术选择、构建／启动／验证／恢复条件及依赖缺口 |
+
+其他版本的 AD 使用同义栏目。AD 的整体技术架构图、功能架构图、数据实体关系及必要详细设计仍完整保留，不能以目录规范替代。
+
+目录标准是实际可读的规范输入，不能据此把“可运行代码模板已取得”或“工程已生成”填为成功。未采用代码框架模板时可据实写“目录规范已采用；工程拟建；未采用代码框架模板”；语言／框架代码由后续获准任务实现。已有代码则引用真实代码／配置。若本项目另行要求复用特定代码模板，仍需取得它，不由本规范替代。
+
+一个 PBC 多份主题 PRD 的各自 AD 引用同一项目规范，并分别映射相关模块；不因 PRD 数量或版本变化重复创建工程。
+
+## 3. 交给原 Plan 的方式
+
+原 Plan 读取 SPEC.md 或等效规格。选定 AD 与其准确 PRD、公共技术规约、契约及目录采用说明共同提供本次等效规格；原 SPEC 六项内容须足够明确。独立 TestCase 为可选输入，已有且适用就引用；原型按需，可与 AD 并行。
+
+手动方式直接提供上述实际路径。已有三字段 JSON 时，可让本次任务先解析 selected 中当前主题的 engineeringSkeleton 及配套路径，再实际读取正文；选择路径不等于读取成功、认可或实施许可。无需为了目录规范新建 JSON，也不把工程说明写入新的顶层字段。
+
+先按当前主题读采用说明和必要规范条款，再读该主题 AD／PRD、所涉代码和共享消费者；不一次加载全部历史、所有主题或所有工程源码。跨主题共用约束及直接依赖仍须读齐。
+
+在项目根使用以下提示；替换方括号中的实际路径。它是原命令的明确任务上下文，不是新增命令参数：
+
+```text
+/i3-plan
+为本次已明确的需求范围制定计划：
+AD：[实际 AD 路径]；准确 PRD：[实际 PRD 路径]。
+公共技术规约：[已采用规范路径]；工程目录采用说明：[实际路径]。
+必要共享契约及已有代码：[实际路径；没有则说明不适用]。
+请实际读取这些来源；缺项或冲突先列出，不猜技术版本。
+按 AD 的工程／模块映射拆任务，明确新增或修改文件相对项目根的位置、
+工程负责人／共享依赖、验收条件及实际验证方法。
+将源码、配置和测试放入已采用位置；已有结构的例外明确写在计划里。
+保留原 Plan 的默认产物、唯一任务目标和审阅停点，不改业务稿。
+```
+
+计划沿用 tasks/plan.md 和原方法确定的唯一任务目标；默认文件目标为 tasks/todo.md，采用其他 tracker 时不复制竞争状态。不同未完成工作不覆盖。工程落点不是把模块名写入任务即可：任务的 Files likely touched 应包含预计路径，验收条件要核对真实新增／修改文件；实施中合理新增文件也须按映射核对。
+
+## 4. 原 Build 如何执行
+
+计划满足原有认可及执行条件后，原 Build 从计划取任务。任务必须指向当前 AD、目录采用说明和所需规范，使执行时能实际回读，而非只相信计划摘要或 JSON 的存在。
+
+```text
+/i3-build
+执行当前计划的下一项获准任务。
+先回读该任务引用的 AD、目录采用说明及所需规范／代码。
+按已采用工程根和模块路径实现；出现目录冲突先说明位置、原因和建议，
+不自行另建同名工程或把源码放进 spec、tasks、文档模板目录。
+完成原有验证后，对照任务及目录映射列出实际变更文件和落点差异。
+业务稿、人工代码和已完成任务按原规则保留。
+```
+
+原 /i3-build auto 使用同一份获准 Plan 和目录映射，保持原有 spec/ 识别、Git、计划认可、TDD／构建及逐任务执行条件。它不会因为本资源存在而自动读取规范；需要时在本次任务上下文明确引用。企业跨阶段 auto／调度不在本资源范围。
+
+规范期望目录约束被设计、任务和验收共同落实，不提供拦截一切写入的 Hook。未实际读取、任务没有落点或实际文件越界时，不声称目录验收通过。
+
+## 5. Build 后如何核目录
+
+在实际业务项目中核对本次任务新增、修改和必要删除的文件。可用 git status --short、针对任务的 git diff／文件清单及实际配置获取事实；不把其他人的未提交文件混作本次结果，也不只看空目录树。
+
+| 核对项 | 通过条件 |
+| --- | --- |
+| 来源与范围 | 当前 AD、目录采用说明及任务可回读，采用版本和实际工程根一致 |
+| 文件落点 | 每个变更文件都能映射到工程／模块、共用资产或原有管理文档位置；例外有明确依据 |
+| 工程边界 | 同一工程标识未重复创建，未按每份 PRD 再造底座；没有未经采用的顶层代码目录 |
+| 共享责任 | 契约、共用代码及跨工程测试各有实际维护位置与相关消费者，未复制其他主题的共享权威 |
+| 构建与测试 | 实际配置的源码、资源、测试和产物路径与采用映射一致；完成本次要求的原有验证 |
+| 人工内容 | 既有目录、项目自改规范、人工代码和已完成任务保留；无整仓覆盖或未经说明的移动／删除 |
+
+结果沿用原工程验证记录或本次任务总结，至少列出“文件／实际位置／采用依据／差异处理／验证结果”。不另建任务完成率或审批状态文件。构建产物、依赖、缓存按实际工具配置和忽略规则处理，不因出现 dist、target、node_modules 等就判源码越界。
+
+落点有偏差时先标注准确位置、影响、推荐和可选处理（按规范调整，或明确采用例外后同步 AD／Plan），不自动移动人工代码或改业务稿。目录核对通过与构建、业务测试、独立审查、Ship 就绪及发布分别记录。
+
+## 6. 现有工程与后续变更
+
+现有项目先映射当前目录及实际命令。已有人采用 services/api、web 等布局时，在采用说明中映射到 backend、frontend 的逻辑职责；不为统一外观改名搬迁。真正的目录迁移另列任务，核导入、构建、CI、部署及消费者影响并保留历史。
+
+规范版本更新只提供新的参考；先比较采用版本与项目修改，明确受影响工程、AD 和未完任务，再决定是否采用。该资源不覆盖项目副本、不生成成功锁、不实现代码模板三方自动升级。I5 的进一步更新／存量辅助另行确认，原先较重的代码模板方案保留在历史中。