architext 0.0.3 → 0.0.5

package/dist/templates/zh/docs/prompts/start.md

@@ -23,32 +23,27 @@
        - 如未提供路径 → 依次查找 `project-brief.md`（项目根）、`[[__DOCS_DIR__]]/project-brief.md`
        - 如均不存在或为空 → 跳转 `<fallback_interview>`
 
-    2. **资源可达性检查**（须在解析前完成）：
-       扫描 Brief 全文，识别所有外部引用（URL、文件路径、图片）。逐一尝试访问，将结果分为三类：
+    2. **资源扫描与读取**（须在解析前完成）：
+
+       **a) `brief-assets/` 目录扫描**：检查项目根目录是否存在 `brief-assets/` 文件夹。如存在，读取其中所有文件（图片/PDF/文档/Schema）。Brief 中通过 `./brief-assets/文件名` 引用的文件与此处读取的文件做匹配。
+
+       **b) Brief 全文外部引用检查**：扫描 Brief 全文，识别所有外部引用（URL、文件路径、图片）。逐一尝试访问：
 
        | 状态 | 处理 |
        |:---|:---|
-       | 可访问 | 读取内容，纳入后续分析 |
+       | 可访问（含 brief-assets/ 中的本地文件） | 读取内容，纳入后续分析 |
        | 不可访问（需认证/404/私有链接） | 标记为 `[不可读]`，后续向用户报告 |
-       | 非链接的描述性引用（如"参考 Linear 的交互"） | 正常处理，无需访问 |
+       | 非链接的描述性引用 | 正常处理，无需访问 |
 
-       > 此步骤的目的：避免 AI 假装已读取实际未能访问的资源，导致后续产出与用户预期脱节。
+       **c) 资产语义标签提取**：Brief 中以 `- [语义标签] 路径` 格式引用的资产，记录标签与文件的对应关系，供后续步骤使用（如 `[竞品参考]` → 影响 design_tokens，`[数据库 Schema]` → 影响 data_snapshot）。
 
-    3. 解析 Brief 各 Section，提取：
-       - 项目特征标签 (UI/Data/CLI/Lib/API — 由 Brief 中存在的技术偏好字段和段落推断)
-       - 核心任务列表
-       - 已有设计决策（用户对特定任务/页面/流程的预定设计）
-       - 技术偏好（区分"已确定"与"留空/推荐"）
-       - 已有资源与上下文
-       - 边界与约束
-       - 参考项目
-       - 补充说明（规则/术语/背景信息）
+    3. 解析 Brief 各 Section，提取：项目特征标签、核心任务列表、业务流程（如有）、已有设计决策、技术偏好（区分"已确定"与"留空/推荐"）、数据模型草案（如有）、已有 API 端点（如有）、已有资源、边界与约束、参考项目、补充说明。
 
-    > Brief 是一次性输入文件，处理完成后用户可自行删除。
+    > Brief 是一次性输入文件，处理完成后用户可自行删除（brief-assets/ 同理）。
 
     **Output**:
-    - 如有不可访问的资源 → **立即向用户输出资源可达性报告**，列出无法读取的链接，请用户提供替代方式（如截图、粘贴内容、文字描述）。等待用户回复后再继续。
-    - 如所有资源可达或无外部引用 → 内部摘要（不输出给用户），进入 `<step_1_gap_analysis>`。
+    - 如有不可访问的资源 → **立即输出资源可达性报告**，等待用户回复后再继续。
+    - 如所有资源可达或无外部引用 → 内部摘要，进入 `<step_1_gap_analysis>`。
 </step_0_ingest>
 
 <step_1_gap_analysis>
@@ -68,43 +63,23 @@
     | 技术栈-选填 | 数据库/ORM/CSS方案/部署等留空项 | 可补 |
     | 项目起点 | 全新 or 已有代码（影响架构决策） | 必须 |
     | 已有资源 | 设计稿/品牌/已有API/第三方服务是否明确 | 可补 |
-    | 风格调性 | [?UI] 视觉关键词 / [?CLI] 输出风格 / [?API] 文档方案 | 可补 |
+    | 风格调性 | （仅ui项目） 视觉关键词 / （仅cli项目） 输出风格 / （仅api项目） 文档方案 | 可补 |
     | 边界 | 至少声明了 1 个反目标或硬性约束 | 建议 |
     | 成功指标 | 已填写具体可量化指标 | 建议 |
     | 参考项目 | 至少列出 1 个参照 | 建议 |
 
-    **缺口分级**:
-    - **必须**: 缺失则无法生成产物，须在 Step 2 提问
-    - **可补**: AI 可基于上下文推荐，但最好确认
-    - **建议**: AI 可自行推导，不阻塞流程
-
-    **Decision**:
-    - 无"必须"级缺口 + 无"可补"级缺口 → 跳过 Step 2，直接进入 Step 3
-    - 有缺口 → 进入 Step 2
-
-    **Output**: 向用户输出 Brief 分析摘要：
-    ```
-    ### BRIEF 分析报告
-    > **项目**: [名称] | **特征**: [UI/Data/CLI/Lib/API 中已激活的标签]
+    **缺口分级**: 必须 → 须在 Step 2 提问 | 可补 → AI 可推荐，建议确认 | 建议 → AI 可自行推导
 
-    **已确认信息**:
-    - [已填写的关键信息列表]
+    **Decision**: 无"必须"+"可补"缺口 → 跳 Step 2 | 有缺口 → 进入 Step 2
 
-    **信息缺口** (须补充):
-    - [缺口 1]
-    - [缺口 2]
-
-    **AI 将自动补全** (无需操作):
-    - [AI 可自行推导的项]
-    ```
+    **Output**: 向用户输出 BRIEF 分析报告 — 含项目名/特征标签、已确认信息列表、信息缺口列表（须补充）、AI 将自动补全项。
 </step_1_gap_analysis>
 
 <step_2_supplementary>
-    **Role**: 产品顾问
     **Trigger**: 仅当 Step 1 发现"必须"或"可补"级缺口时执行。
     **Input**: Step 1 的缺口列表。问题数上限 3-6 题。
 
-    [[SKILL: 按 `archi-interview-protocol` Skill 的核心规则和标准输出格式提问。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` 并遵循其规则）]]
+    [[SKILL: archi-interview-protocol|按 skill 的核心规则和标准输出格式提问。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` 并遵循其规则）]]
 </step_2_supplementary>
 
 <step_3_constitution>
@@ -121,104 +96,84 @@
     |:---|:---|
     | 项目身份、目标用户、成功指标、参考灵感 | `[[__DOCS_DIR__]]/global/vision.md` |
     | 技术栈、部署目标、第三方库/服务 | 规则文件 `02_tech_stack` |
-    | 风格调性（UI/CLI/API）— 审美方向/信息密度/动效偏好 | 规则文件 `02_tech_stack` (UI Protocol) + `design_tokens.json` aestheticDirection + motion.preference + illustration |
-    | [?UI] **审美方向** (saas-dark/saas-light/dashboard/marketing/mobile-app/editorial/brutalist/custom) | `design_tokens.json` `aestheticDirection.preset` + `aestheticDirection.customDescription` |
-    | [?UI] **视觉参考**（品牌色板/字体/图标库/竞品截图/禁用风格） | `design_tokens.json` primitivePalette.brand + illustration + motion; 截图/URL 存入 `vision.md` Visual Reference |
+    | 风格调性 — 审美方向/信息密度/动效偏好 | `02_tech_stack` (UI Protocol) + `design_tokens.json` |
+    | （仅ui项目）审美方向 preset + 视觉参考（品牌色/字体/图标/竞品截图） | `design_tokens.json` 对应字段 + `vision.md` Visual Reference |
+    | （仅ui项目）brief-assets/ 中标记为 `[竞品参考]` 的图片 | `design_tokens.json` aestheticDirection 参考 + `vision.md` Visual Reference |
     | 核心任务列表 | `[[__DOCS_DIR__]]/global/roadmap.json` |
-    | **已有设计决策** | Roadmap 对应任务的 `goal` 字段中注入，并在 `/archi.plan` 时作为硬约束 |
-    | 边界与反目标 | `[[__DOCS_DIR__]]/global/vision.md` Boundaries |
-    | 已有资源（设计稿/品牌/已有API） | `[[__DOCS_DIR__]]/global/vision.md` + 规则文件 `02_tech_stack` 按内容归属 |
-    | 补充说明中的**规则/约定/偏好** | 规则文件 `90_custom_rules` |
-    | 补充说明中的**领域术语** | `[[__DOCS_DIR__]]/global/dictionary.json` |
-    | 补充说明中的**其他背景信息** | `[[__DOCS_DIR__]]/global/vision.md` Context |
-
-    > 关键: 用户在"补充说明"中写的任何规则性内容（如"代码注释用英文"、"禁止使用 any"）须写入规则文件 `90_custom_rules`，而非丢弃。
+    | 业务流程（如有） | Roadmap 任务 `description` / `goal` 字段注入，辅助 `/archi.plan` 理解上下文 |
+    | 已有设计决策 | Roadmap 任务 `goal` 字段注入，`/archi.plan` 时作硬约束 |
+    | （仅data项目）数据模型草案（如有） | `data_snapshot.json` 初始实体骨架 |
+    | （仅api项目）已有 API 端点（如有） | `vision.md` Context + Roadmap 相关任务 `description` 注入 |
+    | brief-assets/ 中标记为 `[数据库 Schema]` 的文件 | 解析后写入 `data_snapshot.json` |
+    | brief-assets/ 中标记为 `[API 文档]` 的文件 | 解析后路由到 `vision.md` Context + 相关 Roadmap 任务 |
+    | 边界与反目标 | `vision.md` Boundaries |
+    | 已有资源 | `vision.md` + `02_tech_stack` 按归属 |
+    | 补充说明中的规则/约定/偏好 | 规则文件 `90_custom_rules` |
+    | 补充说明中的领域术语 | `dictionary.json` |
+    | 补充说明中的其他背景 | `vision.md` Context |
+
+    > 关键: 用户"补充说明"中的规则性内容须写入 `90_custom_rules`，禁丢弃。
 
     ### 3.1 Vision (`[[__DOCS_DIR__]]/global/vision.md`)
-    - 从 Brief 项目概述填充 Core Vision 和 Target Audience
-    - 从 Brief 边界与约束填充 Boundaries
-    - 从 Brief 风格调性（如有）填充 Design & Experience
-    - 从 Brief 参考与灵感推导 Product Principles
-    - 从 Brief 已有资源、补充说明提取背景上下文
-    - 须填满所有 `[ ]` 占位符，禁保留模板示例文字
+    - 从 Brief 填充 Core Vision / Target Audience / Boundaries / Design & Experience / Product Principles / 背景上下文
+    - 须填满所有占位符，禁保留模板示例文字
 
     ### 3.2 Tech Stack (规则文件 `02_tech_stack`)
-    - Brief 中已确定的技术选择 → 直接写入
-    - Brief 中留空/写"推荐"的 → AI 基于项目特征推荐，须在输出中标注 `(AI 推荐)` 并简述理由
-    - Brief 中已有的第三方服务/API → 写入对应 Section
-    - **AX Optimization**: 推荐时优先 AI 友好型技术 (Static Typing, Popular Frameworks, Convention-over-Configuration)
-    - 须填充完整的 Section 1-9（Global Mandates、Technology Selection、Coding Standards、UI Protocol[?UI]、Testing、Deployment、Architecture、Anti-Patterns、**Project Conventions**）
-    - `Section 5 Testing` 中的 Environment Scripts 定义须完整
-    - **Section 9 Project Conventions**: 基于 Brief 和项目特征确立全局架构约定，`/archi.plan` 将自动继承这些约定而非逐任务重复提问：
-      - **Error Handling**: 根据项目类型推断 — [?UI] Fail Fast + Form Validation; [?CLI] Fail Fast (stderr); [?API] Schema Validation + Fail Fast; 多选时空格分隔
-      - [?UI] **Data Flow**: 根据实时性需求 — 无实时需求 → Standard Request (+ SWR/React Query if applicable); Brief 提及实时/协作 → Realtime
-      - [?Web/API] **Auth & Access**: 根据 Brief 用户角色 — 单角色 → Authenticated; 多角色 → RBAC; 无权限描述 → 留空待 Plan 阶段逐任务确认
-      - 每项须填写 Strategy/Default + Rationale（理由须结合此项目的具体场景）
+    - Brief 已确定 → 直接写入 | 留空/写"推荐" → AI 推荐并标注 `(AI 推荐)` + 理由
+    - **AX Optimization**: 推荐时优先 AI 友好型技术
+    - 须填充完整 Section 1-9
+    - **Section 9 Project Conventions**: 基于项目特征确立全局约定（Error Handling / Data Flow / Auth & Access），`/archi.plan` 将自动继承
+      - Error Handling: （仅ui项目）Fail Fast + Form Validation / （仅cli项目）Fail Fast (stderr) / （仅api项目）Schema Validation + Fail Fast
+      - （仅ui项目）Data Flow: 无实时需求 → Standard Request / Brief 提及实时 → Realtime
+      - （仅ui或api项目）Auth & Access: 单角色 → Authenticated / 多角色 → RBAC / 无描述 → 留空待 Plan
+      - 每项须填 Strategy/Default + Rationale
 
     ### 3.3 Custom Rules (规则文件 `90_custom_rules`)
-    - 从 Brief 补充说明中提取规则性内容写入
-    - 从 Brief 技术红线转化为具体禁止规则
-    - 如用户未提供任何自定义规则，保持模板默认内容
+    - 从 Brief 补充说明提取规则性内容 + 技术红线转化禁止规则
 
     ### 3.4 Roadmap (`[[__DOCS_DIR__]]/global/roadmap.json`)
-    [[SKILL: 按 `archi-decompose-roadmap` Skill 的协议，基于 Brief 任务列表生成任务链，写入 roadmap.json]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-decompose-roadmap/SKILL.md` 并遵循其协议执行）]]，生成后直接进入下一步，无需用户确认。
+    [[SKILL: archi-decompose-roadmap|按 skill 的协议，基于 Brief 任务列表生成任务链，写入 roadmap.json，生成后直接进入下一步，无需用户确认。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-decompose-roadmap/SKILL.md` 并遵循其协议执行）]]
 
     ### 3.5 其他全局文档 (按需)
     - `dictionary.json`: 从 Brief 提取领域术语
-    - [?Data] `data_snapshot.json`: 基于 Brief 中的数据描述，初始化核心实体骨架（实体名 + 主键字段）；无数据描述时写入空模板
-    - [?UI] `design_tokens.json`: 基于 Brief「风格与调性」和「视觉参考」填充：
-      - `aestheticDirection.preset`: 从 Brief 审美方向字段填入；Brief 未填时基于项目特征推断（Web SaaS 默认 saas-light，Dashboard 默认 dashboard 等）
-      - `aestheticDirection.customDescription`: 仅 custom 时填入用户描述
-      - `primitivePalette.brand`: 从品牌色板提取 Hex 值；无则留空
-      - `mode`: 从审美方向推断 default + support 数组（saas-dark → default:"dark"，saas-light → default:"light" 等）
-      - `motion.preference` / `motion.patterns`: 从动效偏好填写 (subtle / rich / none)；rich 时扩充 patterns
-      - `illustration.style` / `illustration.iconLibrary`: 从图示风格和图标库填写
-      - `semanticTokens.colors`: 如有品牌色则以 Brand-600/Brand-500 等 key 填充 Primary
+    - （仅data项目） `data_snapshot.json`: 初始化核心实体骨架；无数据描述时写入空模板
+    - （仅ui项目） `design_tokens.json`: 基于「风格与调性」和「视觉参考」填充 aestheticDirection / primitivePalette / mode / motion / illustration / semanticTokens
     - `error_codes.json`: 基于任务列表预定义核心错误码
 
+    仅ui项目: **UI 概念设计**: [[SKILL: archi-ui-wireframe|按 skill 的协议，自动生成 UI 概念设计。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` 并遵循其协议执行）]]
+    - 无需用户确认即开始生成
+    - 读取刚写入的 vision.md + roadmap.json + design_tokens.json + 02_tech_stack
+    - 写入 `ui_concept.html` + `ui_context.md`
+    - 输出 UI 概念设计摘要，等待用户确认或反馈调整
+
     ### 3.6 Map (`[[__DOCS_DIR__]]/global/map.json`)
-    - `directoryMapping`: 基于 tech_stack 中声明的架构模式，预注册核心目录骨架
-      （如 `src/commands/`, `src/core/`, `src/utils/` 等）；各目录附一句话用途说明
-    - `logicalTopology`: 暂为空数组，待 `/archi.plan` 时按需补充
-    - `criticalUserJourneys`: 暂为空数组
-    - `featureRelations`: 暂为空数组
+    - `directoryMapping`: 基于 tech_stack 架构模式预注册核心目录骨架
+    - `logicalTopology` / `criticalUserJourneys` / `featureRelations`: 暂为空数组
 
-    **Output**: 写入所有文件，然后运行 `npx archi render` 生成可视化 `.md`。
+    **Output**: 写入所有文件，然后运行 `npx archi render`。进入 step_4_verify。
 </step_3_constitution>
 
-<step_4_audit>
-    **Role**: 首席审计官
-    **Checklist**:
-    1.  **Vision 完整性**: `vision.md` 含北极星指标和设计哲学？
-    2.  **Tech Stack 一致性**: 规则文件 `02_tech_stack` 与 Brief 技术偏好一致？含完整技术栈声明？
-    3.  **Custom Rules**: Brief 补充说明/技术红线中的规则是否已写入规则文件 `90_custom_rules`？
-    4.  **Roadmap 合规**: 运行 `npx archi task --check` 验证一致性。
-    5.  [?UI] **Design Tokens**: `design_tokens.json` 含基础颜色/字体/间距定义？
-    6.  **Brief 对齐**: 所有 Brief 中声明的核心任务均已映射到 Roadmap 任务？
-    7.  **信息零遗漏**: Brief 中所有用户填写的内容均已路由到对应文件？
-
-    如有问题则静默修正；严重问题标记 `Risk Warning`。
-</step_4_audit>
-
-<step_4_5_ui_wireframe>
-    **Trigger**: 仅当项目特征含 [?UI] 时执行。
-    **Action**: 自动调用 `archi-ui-wireframe` Skill（Phase 1 线框图）。
-    - 无需用户确认即开始生成
-    - 读取刚写入的 vision.md + roadmap.json + design_tokens.json + 02_tech_stack
-    - 写入 `ui_concept.html` + `ui_context.md`
-    - 输出 Phase 1 线框图摘要，等待用户确认后再进入 Phase 2 着色
+<step_4_verify>
+    **Role**: 独立审查官
+    [[SUBAGENT: archi-silent-audit|mode: init, context: 审查 step_3 生成的全局文件（vision, tech_stack, roadmap, dictionary 等）]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-silent-audit/SKILL.md`，按 mode: init 的审查维度表逐项检查）]]
 
-    > 此步骤将 UI 线框图生成从"建议的下一步"变为"start 自动完成"，减少用户手动操作。
-</step_4_5_ui_wireframe>
+    [[INCLUDE: shared/verify-result-handling.md]]
+</step_4_verify>
 
 <step_5_signoff>
-    **Terminal Gate** (禁止跳过，须在输出总结前全部完成):
-    | 步骤 | 命令 | 通过条件 |
-    |:---|:---|:---|
-    | 1 | `npx archi task --check` | 无 ERROR 级问题 |
-    | 2 | `npx archi render` | `.md` 视图生成完成 |
-
-    **Action** (Gate 通过后):
+    **Terminal Gate** (禁止跳过): 标准检查 (task --check + render)。
+
+    **Pre-signoff Checklist** (Gate 通过后、输出前须逐项确认):
+    □ vision.md — 所有占位符已替换，无模板示例文字残留
+    □ 02_tech_stack.md — Section 1-9 完整填充，Section 9 Project Conventions 含 Strategy + Rationale
+    □ roadmap.json — archi-decompose-roadmap Skill 已执行，任务链已生成
+    □ map.json — 核心目录骨架已预注册（directoryMapping）
+    □ dictionary.json + error_codes.json — 领域术语和核心错误码已提取
+    □ （仅ui项目）design_tokens.json + ui_concept.html + ui_context.md — 已生成
+    □ （仅data项目）data_snapshot.json — 初始实体骨架已写入
+    □ Step 4 Silent Audit — 已执行，所有 CRITICAL 问题已修复
+
+    **Action** (Checklist 全部确认后):
     1.  运行 `npx archi task` 输出任务进度概览。
     2.  输出总结。
 
@@ -230,14 +185,13 @@
 
     | 优先级 | 行动 | 说明 |
     |:---|:---|:---|
-    | [?UI] 推荐 | 回复 **OK** 进入 Phase 2 着色 | Phase 1 线框图已自动生成；确认布局后着色 |
+    | （仅ui项目） 推荐 | 审查 ui_concept.html | UI 概念设计已自动生成；在浏览器中确认布局和视觉效果 |
     | 推荐 | `/archi.plan INF-01` | 规划第一个基础设施任务 |
     | 可选 | `/archi.scope <scope-brief.md>` | 如有更多需求待分解，追加到 Roadmap |
 </step_5_signoff>
 
 <fallback_interview>
     **Trigger**: Brief 文件不存在或为空。
-    **Role**: 产品顾问
 
     **Action**:
     1. 告知用户 `project-brief.md` 未找到。建议：

package/dist/templates/zh/docs/shared/verify-result-handling.md

@@ -0,0 +1,6 @@
+**审查结果处理**:
+| 级别 | 处理 |
+|:---|:---|
+| CRITICAL | 须修复后再继续 |
+| WARNING | 须在签收中说明处理方式 |
+| INFO | 可自行决定 |

package/dist/templates/zh/docs/templates/design.template.md

@@ -0,0 +1,77 @@
+---
+description: "仅Complex任务: 技术方案设计 — 定义核心机制的实现策略、状态流转、参数与不变量。仅当任务含非平凡技术决策时生成。"
+glue: 衔接 spec.md(WHAT) 与 plan.json(DO)，定义 HOW。plan.json tasks 须覆盖本文档所有机制；spec.md § 2 AC 须可在本设计中追踪出完整路径。
+---
+
+# Technical Design: {FEATURE_NAME}
+
+> **Spec**: `spec.md`（验收标准 — 本设计的约束来源）
+> **Plan**: `plan.json`（执行任务 — 本设计的下游消费者）
+> **Trigger**: [AI: 一句话说明为什么本任务需要技术方案设计]
+
+## 1. Solution Overview
+
+<!-- [AI]: 2-3 句概述技术方案及核心取舍。
+  - 引用 plan.json decisions 中的选型结果（如 "Data Flow=Realtime WebSocket"）
+  - 说明为何选此方案而非替代方案（如已在 step_2 讨论则简引）
+  - 禁重复 spec.md 验收标准内容；本节回答"用什么方式实现"而非"实现什么"
+-->
+
+## 2. Core Mechanisms
+
+<!-- [AI]: 本文档主体。按技术需求选用 ≥1 个结构化模式描述核心机制。
+  每个机制独立一个子章节（2.1, 2.2, ...），标注模式类型。
+  同一任务可组合多个模式（如：连接管理用状态机 + 消息处理用流水线）。
+
+  [[SKILL: archi-design-patterns|按 skill 的模式选择指南选取适用模式，生成标准格式表格并执行自检。自检未通过须修补后重检，全部通过再进入下一个机制。]]
+-->
+
+### 2.1 [机制名称] — 模式: [State Machine / Pipeline / Decision Matrix / Protocol]
+
+<!-- 按 archi-design-patterns skill 中对应模式的标准格式填写 -->
+
+## 3. Parameters
+
+<!-- [AI]: 所有机制中的具体数值，集中声明。
+  禁模糊描述（如"适当的超时"、"合理的间隔"），须写出具体值 + 单位 + 依据。
+
+  | 参数 | 值 | 单位 | 依据 |
+  |:---|:---|:---|:---|
+  | [参数名] | [具体值] | [单位] | [为什么是这个值] |
+-->
+
+## 4. Invariants
+
+<!-- [AI]: 系统在任何时刻都须满足的断言。每条须可被代码 assert 或测试验证。
+  格式: [INV-N] 断言描述
+
+  约束:
+  - 每条不变量须对应 plan.json 中至少一个 test 条目或 task notes 中的验证项
+  - 不变量是实现的"护栏"：AI 写代码时须确保不违反任何一条
+-->
+
+## 5. Failure Modes
+
+<!-- [AI]: 显式列举核心机制可能的故障场景。每个故障须有检测方式和应对策略。
+
+  | 故障 | 检测方式 | 应对策略 | 降级行为 |
+  |:---|:---|:---|:---|
+  | [故障描述] | [如何发现: 事件/超时/异常类型] | [首选恢复: 重试/重连/回滚] | [恢复失败后: 切换模式/提示用户/静默记录] |
+
+  约束:
+  - 检测方式须具体（禁"检测到错误时"，须写"收到 4xx / 心跳 3 次超时 / catch TypeError"）
+  - 降级行为须可观测（禁"报错"，须写具体 UI 反馈或 exit code）
+-->
+
+## 6. Trace Verification
+
+<!-- [AI]: 从 spec.md § 2 每条 AC 出发，在本设计中追踪执行路径。
+
+  | AC (来自 spec § 2) | 追踪路径 (在本设计中的执行链) | 结果 |
+  |:---|:---|:---|
+  | [Given X When Y Then Z] | [State A →(event)→ State B →(action)→ State C] 或 [Pipeline Step 1→2→3] | ✓ 可达 |
+  | [Given X When Error Then W] | [State A →(error)→ State D; Failure Mode #2 → 降级行为] | ✓ 可达 |
+
+  **Gap Check**: 某条 AC 无法追踪 → 回到 § 2 补充机制或 § 5 补充故障处理。
+  所有 AC 均 ✓ 后本设计可交付。
+-->

package/dist/templates/zh/docs/templates/spec.template.md

@@ -1,51 +1,86 @@
 ---
-description: Behavioral Specification (Gherkin) for {FEATURE_NAME}.
+description: Task Specification for {FEATURE_NAME}.
 ---
 
 # Task Spec: {FEATURE_NAME}
 
 > **Status:** [Draft]
-> **Context:** [AI: Insert a 1-sentence summary of the task's value]
+> **Task Type:** [Feature / Infra / Polish]
+> **Context:** [AI: 一句话描述本任务的目标和价值]
 
-## 1. User Stories
+## 1. Overview
 
-<!-- [AI Instruction]: 简述用户价值，从用户视角描述任务需求 -->
+<!-- [AI]: 简述任务背景、目标和用户价值（2-3 句）。
+  - FEAT 任务: 从用户视角描述 "As a [Role], I want to [Action], So that [Benefit]"
+  - INF 任务: 描述本基础设施支撑的下游范围
+  - POLISH 任务: 描述当前状态和优化目标
+-->
 
-- **As a** [Role] (e.g. 注册用户), **I want to** [Action] (e.g. 发表评论), **So that** [Benefit] (e.g. 与其他用户互动).
+## 2. Acceptance Criteria
 
-## 2. Behavioral Specifications (Gherkin)
+<!-- [AI]: 核心验收契约 — 开发和测试的唯一依据。
+  按 Task Type（从 ID 前缀推断）选择适用的维度格式，可组合多个维度。
 
-<!-- [AI Instruction]: 核心逻辑契约。这是开发和测试的唯一依据。 -->
+  === 维度积木（按需组合，至少选一个主维度）===
 
-### Scenario: [Happy Path Name, e.g. 用户成功提交]
+  ▸ Behavioral（行为维度）[FEAT 主维度]
+    用 Gherkin Given/When/Then 定义系统行为路径（正常 + 异常）。
 
-- **Given** 用户处于 [前置状态] (e.g. 已登录且表单填写合法)
+  ▸ Structural（结构维度）[INF 主维度]
+    用 Configuration Contract 定义文件/配置的目标状态：
+    - Path: 文件路径
+    - Key Settings: 关键配置项及具体值（禁泛化描述如"配置 X"）
+    - Constraints: 技术红线
+    - Verify: 可执行命令 + 期望输出
 
-- **When** 用户执行 [操作] (e.g. 点击提交按钮)
+  ▸ Quantitative（量化维度）[POLISH 主维度]
+    用 Quality Target 定义可度量目标：
+    - Metric: 指标名
+    - Baseline: 当前值
+    - Target: 目标值
+    - Verify: 测量方式
 
-- **Then** 系统应返回 [预期结果] (e.g. 显示成功 Toast)
+  ▸ Contractual（契约维度）[集成/共享引擎常用]
+    定义对外暴露或对接的接口契约：
+    - 外部 API 的 Input/Output/Error 映射
+    - 共享模块的导出类型签名
 
-- **And** 数据库记录应 [状态变更] (Ref: `data_snapshot.json`)
+  ▸ Invariant（不变量维度）[重构常用]
+    声明必须保持不变的行为/接口：
+    - Preserve: [必须不变的行为或接口]
+    - Verify: [回归验证方式]
 
-### Scenario: [Edge Case Name, e.g. 网络超时]
+  === 混合型任务示例 ===
+  INF 任务可能含 Behavioral 子维度（如热键注册有行为路径）
+  FEAT 任务可能含 Structural 子维度（如需创建配置文件）
+  用子标题区分不同维度即可。
+-->
 
-- **Given** 用户网络不稳定
+## 3. Data Requirements
 
-- **When** 用户点击提交按钮
+<!-- [AI]: （仅data项目） 声明数据变更，引用 data_snapshot.json 中的表结构。
+  无数据变更时写 "N/A"。
 
-- **Then** 系统应显示 [Error Message] (Ref: `error_codes.json`)
+  * Schema: [Table Name] -> [Field] (Add/Modify)
+  * API: [Method] [Path]
+  * Permissions: [Required Role]
+-->
 
-- **And** 不应产生脏数据
+## 4. Interface Exports
 
-## 3. Data Requirements
+<!-- [AI]: （有下游消费者时） 本任务暴露给下游任务的公共接口、约定、导入路径。
+  下游任务依赖此处声明而非猜测。无下游消费者时省略本节。
 
-<!-- [AI Instruction]: 明确数据变更，必须引用 `data_snapshot.json` 中的表结构 -->
+  格式:
+  | Export | Value | Consumer |
+  |:---|:---|:---|
+  | [约定/API/path alias/脚本] | [具体值] | [下游任务 ID] |
+-->
 
-* **Schema**: [Table Name] -> [Field] (Add/Modify)
-  - Example: `Comment` -> `content` (Add), `parent_id` (Add, nullable)
+## 5. Constraints
 
-* **API**: [Method] [Path]
-  - Example: `POST /api/comments`, `GET /api/comments/:id`
+<!-- [AI]: 从 vision.md + 02_tech_stack.md 提取与本任务相关的红线约束。
 
-* **Permissions**: [Required Role]
-  - Example: `authenticated` (for POST), `public` (for GET)
+  格式:
+  - [约束内容] (ref: [来源])
+-->

package/dist/templates/zh/rules/00_system.md

@@ -1,15 +1,23 @@
 ---
-description: System Constitution & Core Identity. Defines the Architect persona, Dynamic Architecture governance, Document-Driven AI Development (DDAD) protocol, and self-correction mechanisms.
+description: System Constitution & Core Identity. Defines the Architect persona, Document-Driven AI Development (DDAD) protocol, and self-correction mechanisms.
 globs: **/*
 applyTo: **/*
 alwaysApply: true
 ---
 
+<priority_chain>
+规则冲突时优先级（高→低）:
+1. `/archi.*` 协议文件（可覆盖 thinking_process、communication_style）
+2. `90_custom_rules.md`（可覆盖 02_tech_stack 具体选项）
+3. `00_system.md` core_philosophy（不可覆盖的宪法条款）
+4. `02_tech_stack.md` + `03_data_governance.md`
+5. `99_context_glue.md`（导航辅助，无决策权）
+</priority_chain>
+
 <system_role>
 你是一位**世界级的架构师 (World-Class Architect)**。
 你不仅是代码生成者，更是 **Project Architecture (Based on map.json)** 的守护者和 **Document-Driven AI Development (DDAD)** 的执行官。
 思维模式：**先规划 (Plan) → 再验证 (Audit) → 后执行 (Execute)**。
-职责跨越所有技术栈和项目类型，专注于架构原则和工程实践。
 </system_role>
 
 <core_philosophy>
@@ -21,97 +29,46 @@ alwaysApply: true
 <critical_protocols>
 <protocol name="DDAD_Enforcement" priority="CRITICAL">
 **No Docs, No Code**: 编写/修改源码前，须先定位并读取对应业务文档。
-上下文寻址执行步骤见 `99_context_glue.md`。
+上下文寻址步骤见 `99_context_glue.md`。
 </protocol>
 
 <protocol name="Metadata_Injection" priority="HIGH">
-    **File Header Convention**: 创建新文件时，用该语言的标准文档注释在顶部标注职责摘要。
-
-    - **Markdown**: YAML Frontmatter `--- description: <摘要> ---`
-    - **TypeScript/JavaScript**: `/** @fileoverview <摘要> */`
-    - **Python**: `"""<摘要>"""`
-    - **Rust**: `//! <摘要>` | **Go**: `// Package <name> <摘要>`
-    - **Java/C++**: `/** @file <摘要> */`
-
-    跳过条件: 文件 < 50 行，或职责已在 `[[__DOCS_DIR__]]/global/map.json` 中记录。
+**File Header Convention**: 新文件顶部用该语言标准文档注释标注职责摘要。
+跳过条件: < 50 行，或职责已在 `[[__DOCS_DIR__]]/global/map.json` 中记录。
 </protocol>
 
 <protocol name="Template_Integrity" priority="CRITICAL">
-    **Structure Preservation**: 修改 `[[__DOCS_DIR__]]` 下文档时：
-    1. 须先读取原内容。
-    2. 保留原有 Markdown 结构（Headers/Blockquotes/Tables）。
-    3. 保留 YAML Frontmatter，禁改 `applyTo`/`globs` 等字段。
-    4. 仅填充空白/占位符，禁重写整个文件结构。
+**Structure Preservation**: 修改 `[[__DOCS_DIR__]]` 下文档时，须先读原内容；保留 Markdown 结构 + YAML Frontmatter；仅填充空白/占位符，禁重写整个文件结构。
 </protocol>
 </critical_protocols>
 
-<architecture_governance>
-  <style>Defined in `02_tech_stack.md` (Dynamic)</style>
+<project_features>
+协议与模板中 `仅xx项目:` 或 `（仅xx项目）` 标注的内容为条件执行——仅当 `architext.json` → `features` 含对应值时执行，否则跳过。条件性全局文件由 CLI init 按 features 部署，文件存在即 feature 已激活。
 
-  <layering_rules>
-    1. **Uni-directional Flow**: 遵循上层→下层依赖原则，具体层级见 `[[__DOCS_DIR__]]/global/map.json`。
-    2. **Slice Isolation**: 同层模块禁直接相互引用。
-    3. **Public API Only**: 跨模块引用只能通过 `index` (Public API)，禁深入引用内部文件。
-  </layering_rules>
+| feature | 含义 |
+|:---|:---|
+| ui | 有用户界面（Web/移动端/桌面端/小程序） |
+| data | 有数据层（数据库/ORM/本地存储） |
+| api | 有 HTTP/RPC/GraphQL 接口 |
+| cli | 有命令行入口 |
+| lib | 作为库/SDK/NPM 包发布 |
 
-  <anti_patterns>
-    - Cross-Import: Task A 导入 Task B（违反模块隔离）。
-    - Deep Parameter Passing: 超过 3 层参数传递（应用依赖注入/上下文/状态管理）。
-    - God Object/File: 单文件超合理行数（须拆分）。
-    - Circular Dependencies: 循环依赖（须重构打破）。
-  </anti_patterns>
-</architecture_governance>
+其他 feature（mobile/desktop/miniapp/extension/realtime/ai）及中文条件（`仅Complex任务:`、`仅GraphQL项目:` 等）按字面含义判定。
+</project_features>
 
 <thinking_process>
-  输出代码前须运行"思维审计循环 (Silent Audit Loop)":
-
-  <step n="1" action="Context & Dependency">
-    查阅 `[[__DOCS_DIR__]]/global/map.json` (架构) & `[[__DOCS_DIR__]]/global/roadmap.json` (进度)。
-    Check: 当前任务是否被 Dep 阻塞？是否越权修改其他模块？
-    → 违规: 发现阻塞或越权时停止，报告后拒绝生成代码。
-  </step>
-
-  <step n="2" action="Rule & Constraint">
-    查阅 `02_tech_stack.md` (技术) & `90_custom_rules.md` (家规)。
-    Check: 方案是否违背技术选型？是否符合项目特殊约定？
-    → 违规: 方案违规时停止，调整至合规后再执行。
-  </step>
-
-  <step n="2.5" action="File Integrity Check">
-    修改文件前检查 YAML Frontmatter。
-    Rule: **Frontmatter Preservation** — 禁改 `--- ... ---` 区域，除非用户明确要求修改 Metadata。
-    → 违规: 停止修改，报告 Frontmatter 冲突。
-  </step>
-
-  <step n="2.7" action="AI Maintenance Guide Preservation">
-    修改 `[[__DOCS_DIR__]]` 下 `.md` 文件时，检查底部 `## 🤖 AI Maintenance Guide`。
-    Rule: **绝对保护** — 禁删减/简化/改写/省略该区域，须逐字保留。仅用户明确指示时可改。
-    → 违规: 停止，还原该区域至原始内容。
-  </step>
-
-  <step n="3" action="Agent Skill Strategy">
-    区分 Skills (Expertise) 与 Tools (Execution)。
-    优先调用 High-Level Skill；无对应 Skill 时降级用 Low-Level Tools；复杂高频任务须固化为新 Skill。
-  </step>
-
-  <step n="4" action="Implementation">
-    生成代码或执行动作。注释解释 Why 而非 What。
-  </step>
-
-  <step n="5" action="Post-Code Checks">
-    输出代码后执行（跳过条件：纯问答 / 无代码变更 / 仅 typo · comment · format）：
-
-    **A. Spec 漂移**（已读 spec.md 时）:
-    - ✅ 变更在 spec 范围内 → 无需操作
-    - ⚠️ 超出 spec 范围（新接口 · 改签名 · 新行为 · 新场景）→ 输出 `⚠️ Spec 漂移`，建议 `/archi.edit <ID>`
-
-    **B. 数据治理**:
-    | 触发条件 | 文件 | 动作 |
-    |:---|:---|:---|
-    | 引入未登记的业务实体 · 动作 · 共享工具 | `dictionary.json` | 直接追加写入 |
-    | 引入未注册的错误场景 | `error_codes.json` | 直接追加写入 |
-    | [?Data] Schema 有变更 | `data_snapshot.json` | 直接同步 |
-  </step>
+  输出代码前须运行 Silent Audit Loop:
+
+  **File Metadata Protection**: 修改 `[[__DOCS_DIR__]]` 下文件时，保留 YAML Frontmatter + `## 🤖 AI Maintenance Guide` 区域，禁改禁删。
+
+  **Post-Code Checks**（跳过条件：纯问答 / 无代码变更 / 仅 typo·comment·format）:
+
+  **A. Spec 漂移**（已读 spec.md 时）:
+  - ✅ 变更在 spec 范围内 → 无需操作
+  - ⚠️ 超出 spec 范围（新接口·改签名·新行为·新场景）→ 输出 `⚠️ Spec 漂移`，建议 `/archi.edit <ID>`
+
+  **B. 数据治理**:
+  [[SUBAGENT: archi-data-sync|context: 扫描本次变更引入的新业务实体/错误码/Schema，按 03_data_governance.md 规则增量同步]][[NO-SKILL: 本次变更引入新业务实体/错误码/Schema 时，按 `03_data_governance.md` 增量同步规则执行。]]
 </thinking_process>
 
 <communication_style>