architext 0.0.4 → 0.0.6

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

@@ -0,0 +1,102 @@
+<protocol_script>
+  **Trigger**: `/archi.script`
+  **Goal**: 基于已冻结的 `tech_stack.md` 生成/更新 `.architext/scripts/` 自动化脚本。
+  **When**: 基建任务（INF-01 等）完成后，`tech_stack` 命令已从占位符变为实际值且可运行时。
+
+<meta>
+    <style>Deterministic, Auto-Detect, Post-Infra</style>
+    <language>简体中文</language>
+    <principles>
+      1. **Post-Infra Only**: 仅基建完成后执行，`tech_stack` 命令必须已确定且可运行。
+      2. **Auto-Detect**: 自动识别 OS，生成 `.sh`（Unix）和 `.ps1`（Windows）。
+      3. **Tech-Stack Driven**: 严格从 `tech_stack.md` 提取实际命令，禁硬编码。
+      4. **Idempotent**: 多次运行结果一致，有变更才写入。
+    </principles>
+</meta>
+
+<step_1_ingest>
+    **Action**:
+    1. 读取 `[[__DOCS_DIR__]]/global/tech_stack.md`
+    2. 读取项目实际代码，提取实际命令：
+       - `package.json` → `scripts` 字段（如有）
+       - 配置文件 → `vite.config.*` / `webpack.config.*` / `tsconfig.json` 等
+       - CI 配置 → `.github/workflows/` / `.gitlab-ci.yml` 等（如有）
+    3. 交叉验证：tech_stack 命令 vs 实际配置
+       - 一致 → 使用 tech_stack 命令
+       - 不一致 → 以实际代码为准（tech_stack 可能过期）
+    4. 提取以下命令（跳过 `[例如：...]` 占位符）：
+       - **Lint**: Section 3 Static Analysis
+       - **Format**: Section 3 Formatter
+       - **Build**: Section 3 Build Command
+       - **Test**: Section 5 Test Command
+       - **Dev**: Section 3 Dev Command
+       - **Install**: Section 3 Package Manager + install
+    5. 检测当前 OS（Windows / Unix-like）
+
+    **Output**: 内部命令映射表（tech_stack + 实际代码交叉验证结果），进入 step_2_generate。
+</step_1_ingest>
+
+<step_2_generate>
+    **Action**: 基于提取的命令生成三个脚本：
+
+    ### validate
+    聚合检查：Lint → Format Check → Type Check → Build → Test
+    - 每步失败即退出（exit 1）
+    - 带颜色输出（绿=通过，红=失败，黄=跳过）
+
+    ### dev-up
+    启动环境：Install → Build → Health Check
+    - Health Check：尝试运行构建产物（如 CLI 则 `--version`）
+
+    ### dev-reset
+    重置环境：Kill Process → Clean Cache → Reinstall → Rebuild → Health Check
+    - Kill：终止 node/tsx 进程
+    - Clean：删除 node_modules/.cache, dist, coverage
+
+    **Script Structure**:
+    - Unix (`.sh`): `#!/bin/bash`, `set -e`, ANSI colors
+    - Windows (`.ps1`): PowerShell, `$ErrorActionPreference`, Write-Host colors
+
+    **Output**: 内存中脚本内容，进入 step_3_write。
+</step_2_generate>
+
+<step_3_write>
+    **Action**:
+    1. 确保 `[[__DOCS_DIR__]]/scripts/` 目录存在
+    2. 对比现有脚本（如有）：
+       - 内容一致 → 跳过
+       - 内容变更 → 覆盖，标注 `MODIFIED`
+       - 不存在 → 写入，标注 `ADDED`
+    3. 写入文件：
+       - Unix: `validate`, `dev-up`, `dev-reset`（无扩展名，+x 权限）
+       - Windows: `validate.ps1`, `dev-up.ps1`, `dev-reset.ps1`
+
+    **Output**: 文件变更列表。
+</step_3_write>
+
+<step_4_signoff>
+    **Terminal Gate** (禁止跳过): 标准检查 (task --check + render)。
+
+    **Pre-signoff Checklist**:
+    □ tech_stack.md — 成功提取到非占位符命令
+    □ scripts/ — validate/dev-up/dev-reset 已生成（Unix + Windows）
+    □ 变更标注 — ADDED / MODIFIED / SKIPPED 正确输出
+
+    **Output**:
+    ```
+    ✅ Scripts Generated
+
+    | 脚本 | OS | 状态 |
+    |:---|:---|:---|
+    | validate | Unix | ADDED/MODIFIED/SKIPPED |
+    | validate | Windows | ADDED/MODIFIED/SKIPPED |
+    | dev-up | Unix | ... |
+    | dev-up | Windows | ... |
+    | dev-reset | Unix | ... |
+    | dev-reset | Windows | ... |
+
+    **Next**: AI 执行 `/archi.code` 时将自动使用 `scripts/validate`
+    ```
+</step_4_signoff>
+
+</protocol_script>

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>
@@ -73,34 +68,14 @@
     | 成功指标 | 已填写具体可量化指标 | 建议 |
     | 参考项目 | 至少列出 1 个参照 | 建议 |
 
-    **缺口分级**:
-    - **必须**: 缺失则无法生成产物，须在 Step 2 提问
-    - **可补**: AI 可基于上下文推荐，但最好确认
-    - **建议**: AI 可自行推导，不阻塞流程
-
-    **Decision**:
-    - 无"必须"级缺口 + 无"可补"级缺口 → 跳过 Step 2，直接进入 Step 3
-    - 有缺口 → 进入 Step 2
+    **缺口分级**: 必须 → 须在 Step 2 提问 | 可补 → AI 可推荐，建议确认 | 建议 → AI 可自行推导
 
-    **Output**: 向用户输出 Brief 分析摘要：
-    ```
-    ### BRIEF 分析报告
-    > **项目**: [名称] | **特征**: [UI/Data/CLI/Lib/API 中已激活的标签]
+    **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 题。
 
@@ -115,75 +90,67 @@
 
     ### 信息路由规则
 
-    > 规则文件（`02_tech_stack`、`90_custom_rules` 等）已由 IDE 注入当前上下文，AI 已知其路径，直接写入即可。
+    > 规则文件（`tech_stack`、`90_custom_rules` 等）已由 IDE 注入当前上下文，AI 已知其路径，直接写入即可。
 
     | Brief 内容 | 目标文件 |
     |:---|:---|
     | 项目身份、目标用户、成功指标、参考灵感 | `[[__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 |
+    | 技术栈、部署目标、第三方库/服务 | 规则文件 `tech_stack` |
+    | 风格调性 — 审美方向/信息密度/动效偏好 | `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` + `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 已有资源、补充说明提取背景上下文
-    - 须填满所有 `[ ]` 占位符，禁保留模板示例文字
-
-    ### 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
-      - （仅ui或api项目） **Auth & Access**: 根据 Brief 用户角色 — 单角色 → Authenticated; 多角色 → RBAC; 无权限描述 → 留空待 Plan 阶段逐任务确认
-      - 每项须填写 Strategy/Default + Rationale（理由须结合此项目的具体场景）
+    - 从 Brief 填充 Core Vision / Target Audience / Boundaries / Design & Experience / Product Principles / 背景上下文
+    - 须填满所有占位符，禁保留模板示例文字
+
+    ### 3.2 Tech Stack (规则文件 `tech_stack`)
+    - 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` 并遵循其协议执行）]]
 
     ### 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`: 基于任务列表预定义核心错误码
+    - （仅api项目） `api_snapshot.json`: 初始端点注册；Brief 有 API 描述时从中提取，否则写入空模板
+    - `env_registry.json`: 初始环境变量注册
+    - （仅cli项目） `command_api.json`: 初始命令注册；Brief 有命令描述时从中提取，否则写入空模板
+    - （仅lib项目） `public_api.json`: 初始导出注册；Brief 有导出描述时从中提取，否则写入空模板
+
+    仅ui项目: **UI 概念设计**: 跳过 — 由 `/archi.ui` 独立完成。仅确保 `design_tokens.json` 已填充。
 
     ### 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_verify>
@@ -193,25 +160,23 @@
     [[INCLUDE: shared/verify-result-handling.md]]
 </step_4_verify>
 
-<step_4_5_ui_wireframe>
-    **Trigger**: 仅当项目 features 含 `ui` 时执行。
-    **Action**: [[SKILL: archi-ui-wireframe|按 skill 的协议，自动调用 Phase 1 线框图生成。]][[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`
-    - 输出 Phase 1 线框图摘要，等待用户确认后再进入 Phase 2 着色
-
-    > 此步骤将 UI 线框图生成从"建议的下一步"变为"start 自动完成"，减少用户手动操作。
-</step_4_5_ui_wireframe>
-
 <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 — 所有占位符已替换，无模板示例文字残留
+    □ tech_stack.md — Section 1-9 完整填充，Section 9 Project Conventions 含 Strategy + Rationale
+    □ roadmap.json — archi-decompose-roadmap Skill 已执行，任务链已生成
+    □ map.json — 核心目录骨架已预注册（directoryMapping + logicalTopology + featureRelations）
+    □ dictionary.json + error_codes.json + env_registry.json — 领域术语、核心错误码、环境变量已提取
+    □ （仅ui项目）design_tokens.json + ui_context.md — 已生成
+    □ （仅data项目）data_snapshot.json — 初始实体骨架已写入
+    □ （仅api项目）api_snapshot.json — 初始 API 端点已注册
+    □ （仅cli项目）command_api.json — 初始 CLI 命令已注册
+    □ （仅lib项目）public_api.json — 初始库导出已注册
+    □ Step 4 Silent Audit — 已执行，所有 CRITICAL 问题已修复
+
+    **Action** (Checklist 全部确认后):
     1.  运行 `npx archi task` 输出任务进度概览。
     2.  输出总结。
 
@@ -223,14 +188,14 @@
 
     | 优先级 | 行动 | 说明 |
     |:---|:---|:---|
-    | （仅ui项目） 推荐 | 回复 **OK** 进入 Phase 2 着色 | Phase 1 线框图已自动生成；确认布局后着色 |
+    | （仅ui项目） 推荐 | `/archi.ui` | 生成 UI 概念设计（`screens/` 多文件结构） |
     | 推荐 | `/archi.plan INF-01` | 规划第一个基础设施任务 |
+    | （INF 完成后） | `/archi.script` | 生成 AI 自动化脚本（validate/dev-up/dev-reset） |
     | 可选 | `/archi.scope <scope-brief.md>` | 如有更多需求待分解，追加到 Roadmap |
 </step_5_signoff>
 
 <fallback_interview>
     **Trigger**: Brief 文件不存在或为空。
-    **Role**: 产品顾问
 
     **Action**:
     1. 告知用户 `project-brief.md` 未找到。建议：

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

@@ -0,0 +1,113 @@
+<protocol_ui>
+  **Trigger**: `/archi.ui` | 自然语言触发时由 Workflow Dispatch 自动加载
+  **Goal**: 生成或增量更新多文件 UI 概念设计（`screens/` 目录）。
+
+<meta>
+    <style>Visual, Systematic, Incremental</style>
+    <language>简体中文</language>
+    <principles>
+      1.  **Auto-Detect**: 无子命令，自动检测 `screens/` 目录状态决定全量生成或增量更新。
+      2.  **Multi-File**: 每个屏幕独立 `S-XX.html`，共享样式 `_shared.css`，`index.html` 作导航枢纽。
+      3.  **Token-Driven**: 视觉样式严格来自 `design_tokens.json`，禁硬编码。
+      4.  **IDE-Native First**: 利用 IDE 原生能力驱动执行节奏，本协议定义质量标准和检查点，不对抗 IDE 的规划/执行机制。
+    </principles>
+</meta>
+
+<step_1_load>
+    **Action**:
+    1.  **Pre-flight**: 检查 `architext.json` → `features` 是否含 `ui`。不含 → 拒绝（"本项目未启用 UI 特征"）。
+    2.  **Load**: 读取项目上下文 + UI 相关 JSON（design_tokens、ui_context），详见 00_system.md 数据治理规则。
+    3.  **Mode Detection**:
+
+        | 条件 | 模式 | 行为 |
+        |:---|:---|:---|
+        | `screens/` 目录不存在 | **全量生成** | 从 roadmap 提取全部 UI 屏幕 → step_2 |
+        | `screens/` 存在 | **增量更新** | 对比 roadmap + ui_context.md，识别新增/变更屏幕 → step_2 |
+
+    **Output**: 模式判定结果 + 上下文摘要。进入 step_2_plan。
+</step_1_load>
+
+<step_2_plan>
+    **Action**:
+
+    **全量模式**: 从 roadmap 任务中提取所有涉及 UI 的屏幕，分配屏幕 ID（S-01, S-02...）。
+    **增量模式**: 对比现有 `screens/` 与 roadmap，识别差异：
+
+    | 差异类型 | 处理 |
+    |:---|:---|
+    | 新增屏幕（roadmap 有任务但无对应 S-XX） | 分配新 ID，加入生成清单 |
+    | 屏幕变更（已有屏幕的任务有需求变化） | 加入更新清单 |
+    | 无变化 | 跳过 |
+
+    **Tokens 检查**: 检查 `design_tokens.json`:
+    - `aestheticDirection.preset` 为空 → 引导选择
+    - `primitivePalette.brand` 为空 → 引导填入 Hex
+    - 其他空值 → AI 推断，非阻塞
+
+    **Output**: 屏幕规划清单（ID / 名称 / 对应任务 / 状态列表 / 操作：新增/更新/跳过）。
+
+    **Gate**: 用户回复 **OK** 后进入 step_3_generate；未确认禁生成文件。
+</step_2_plan>
+
+<step_2_5_refinement>
+    **Trigger**: 用户回复非 OK，含修正、增删屏幕或调整映射。
+    **Action**: 融入反馈，刷新屏幕规划清单重新输出，等待再次确认。
+
+    用户回复 OK → 进入 step_3_generate。
+</step_2_5_refinement>
+
+<step_3_generate>
+    **Action**: 调用 Skill 执行实际生成。
+
+    [[SKILL: archi-ui-wireframe|按 skill 的协议，基于确认的屏幕规划清单生成多文件 UI 概念设计。全量模式生成所有屏幕；增量模式仅生成新增/变更屏幕。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` 并遵循其协议执行）]]
+
+    **产出物**:
+    - `[[__DOCS_DIR__]]/global/screens/_shared.css` — CSS 变量（来自 design_tokens）+ 基础布局 + 控制栏样式
+    - `[[__DOCS_DIR__]]/global/screens/S-XX.html` — 每个屏幕独立文件
+    - `[[__DOCS_DIR__]]/global/screens/index.html` — 导航枢纽，列出所有屏幕
+    - `[[__DOCS_DIR__]]/global/ui_context.md` — AI 屏幕索引（路由引用 `screens/S-XX.html`）
+
+    **Output**: 生成文件清单 + 变更摘要。进入 step_4_verify。
+</step_3_generate>
+
+<step_4_verify>
+    **Role**: 独立审查官
+
+    **验证清单**:
+
+    | 检查项 | 通过标准 |
+    |:---|:---|
+    | 文件完整性 | `screens/` 含 `index.html` + `_shared.css` + 全部 `S-XX.html` |
+    | 跨文件链接 | `index.html` 中所有 `S-XX.html` 链接有效；每个 `S-XX.html` 含返回索引链接 |
+    | CSS 引用 | 每个 `S-XX.html` 引用 `_shared.css`；CSS 变量来自 design_tokens |
+    | 状态覆盖 | 每个屏幕含 default + 适用状态（loading/empty/error） |
+    | ui_context.md | 屏幕索引路由引用 `screens/S-XX.html` 路径 |
+    | （增量模式）已有屏幕 | 未修改的屏幕文件未被覆盖 |
+
+    有失败项 → 修复后重检。全部通过 → 进入 step_5_signoff。
+</step_4_verify>
+
+<step_5_signoff>
+    **Pre-signoff Checklist** (输出前须逐项确认):
+    □ `screens/` 目录结构完整（index.html + _shared.css + S-XX.html）
+    □ `ui_context.md` 已生成/更新，路径引用正确
+    □ Step 4 验证全部通过
+    □ （增量模式）仅目标屏幕被修改，其余文件未变
+
+    **Output**: UI 概念设计摘要，含：
+    - **模式**: 全量生成 / 增量更新
+    - **屏幕覆盖**: 共 N 个屏幕（新增 X / 更新 Y / 保留 Z）
+    - **审美方向**: preset + 品牌色
+    - **文件清单**: 生成/修改的文件列表
+
+    **用户确认**: 回复 **OK** 完成；非 OK 进入 Refinement（调用 Skill 局部更新）。
+
+    **Next Steps**:
+
+    | 优先级 | 动作 | 说明 |
+    |:---|:---|:---|
+    | 推荐 | 在浏览器打开 `screens/index.html` | 确认布局和视觉效果 |
+    | 1 | `/archi.plan <第一个 pending 任务 ID>` | 开始规划任务 |
+</step_5_signoff>
+
+</protocol_ui>

package/dist/templates/zh/docs/shared/ui-redlines.md

@@ -0,0 +1,7 @@
+**UI 设计红线（Anti-patterns）**:
+- **禁紫色渐变白底** — AI 默认审美标志
+- **禁 Emoji 代图标**（🔔📁⚙️）→ 用自绘 SVG 或声明的图标库
+- **禁所有屏幕同一居中卡片布局** → 列表/详情/表单须有明显差异
+- **禁纯黑+纯白** → 用有层次的灰度色板
+- **禁通用感** → 打开须一眼判断审美方向（Linear vs Notion vs Grafana）
+- **禁硬编码** — 颜色用 Token，间距用变量，非魔法数字

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

@@ -79,7 +79,7 @@ description: Task Specification for {FEATURE_NAME}.
 
 ## 5. Constraints
 
-<!-- [AI]: 从 vision.md + 02_tech_stack.md 提取与本任务相关的红线约束。
+<!-- [AI]: 从 vision.md + tech_stack.md 提取与本任务相关的红线约束。
 
   格式:
   - [约束内容] (ref: [来源])

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

@@ -1,12 +1,12 @@
 ---
-description: 任务级 UI 范围声明 — 描述本任务负责的屏幕/组件范围，屏幕 ID 来自 ui_context.md，视觉原型见 ui_concept.html（人看）。
+description: 任务级 UI 范围声明 — 描述本任务负责的屏幕/组件范围，屏幕 ID 来自 ui_context.md，视觉原型见 screens/（人看）。
 glue: 屏幕 ID 引用自 [[__DOCS_DIR__]]/global/ui_context.md；禁重定义整体布局或全局导航。
 ---
 
 # UI Scope: {FEATURE_NAME}
 
 > **Screen Index**: `[[__DOCS_DIR__]]/global/ui_context.md`（AI 读取屏幕 ID 和导航关系）
-> **Visual Prototype**: `[[__DOCS_DIR__]]/global/ui_concept.html`（人类浏览器预览）
+> **Visual Prototype**: `[[__DOCS_DIR__]]/global/screens/index.html`（人类浏览器预览，各屏幕 `screens/S-XX.html`）
 > **Tokens**: `[[__DOCS_DIR__]]/global/design_tokens.json`
 > **Protocol**: ITP v3.0（仅描述本任务边界内的组件树）
 
@@ -27,15 +27,15 @@ glue: 屏幕 ID 引用自 [[__DOCS_DIR__]]/global/ui_context.md；禁重定义
 ```text
 [ScreenName > 修改区域名]
   NewComponent [Col, Gap:4]      ← 本任务新增
-    ExistingComponent            ← ref: ui_concept.html S-XX (不修改)
+    ExistingComponent            ← ref: screens/S-XX.html (不修改)
     #NewSubComponents
 ```
 
-> **引用规则**: 已在 `ui_concept.html` 中定义的组件 → `ref: ui_concept.html#S-XX-组件名`；禁复制粘贴其结构。
+> **引用规则**: 已在 `screens/S-XX.html` 中定义的组件 → `ref: screens/S-XX.html#组件名`；禁复制粘贴其结构。
 
 ## 3. Interactions (本任务新增的交互)
 
-<!-- [AI]: 仅列出本任务引入的新交互；ui_concept.html 已有的交互不重复 -->
+<!-- [AI]: 仅列出本任务引入的新交互；screens/S-XX.html 已有的交互不重复 -->
 
 | Trigger | Target | Action |
 |:---|:---|:---|
@@ -43,9 +43,9 @@ glue: 屏幕 ID 引用自 [[__DOCS_DIR__]]/global/ui_context.md；禁重定义
 
 ## 4. States (本任务负责的状态渲染)
 
-<!-- [AI]: 若 ui_concept.html 的状态已充分描述，此处可省略或仅补充差异 -->
+<!-- [AI]: 若 screens/S-XX.html 的状态已充分描述，此处可省略或仅补充差异 -->
 
-| State | Delta from ui_concept.html |
+| State | Delta from screens/S-XX.html |
 |:---|:---|
-| `loading` | 同 ui_concept.html S-XX loading（无差异）|
+| `loading` | 同 screens/S-XX.html loading（无差异）|
 | `empty` | 本任务空态文案不同："{具体文案}" |