architext 0.0.2

package/dist/templates/zh/docs/templates/plan.template.json

@@ -0,0 +1,88 @@
+{
+  "featureId": "{FEATURE_ID}",
+  "featureName": "{FEATURE_NAME}",
+  "status": "pending",
+  "decisions": [
+    { "category": "数据模型", "choice": "", "rationale": "" },
+    { "category": "交互模式", "choice": "", "rationale": "" },
+    { "category": "状态同步", "choice": "", "rationale": "" },
+    { "category": "边界处理", "choice": "", "rationale": "" },
+    { "category": "访问控制", "choice": "", "rationale": "" }
+  ],
+  "phases": [
+    {
+      "name": "Phase 1: 领域与数据",
+      "tasks": [
+        {
+          "id": "p1-1",
+          "title": "[数据结构/Schema 定义]",
+          "notes": "",
+          "done": false
+        },
+        {
+          "id": "p1-2",
+          "title": "[核心逻辑/接口实现]",
+          "notes": "",
+          "done": false
+        },
+        { "id": "p1-3", "title": "[输入校验]", "notes": "", "done": false }
+      ]
+    },
+    {
+      "name": "Phase 2: 展示层",
+      "tasks": [
+        {
+          "id": "p2-1",
+          "title": "[静态结构 (参照 spec/ui 文档)]",
+          "notes": "",
+          "done": false
+        },
+        { "id": "p2-2", "title": "[交互逻辑]", "notes": "", "done": false },
+        { "id": "p2-3", "title": "[状态管理]", "notes": "", "done": false }
+      ]
+    },
+    {
+      "name": "Phase 3: 集成",
+      "tasks": [
+        { "id": "p3-1", "title": "[端到端串联]", "notes": "", "done": false },
+        {
+          "id": "p3-2",
+          "title": "[错误处理 (参照 error_codes.json)]",
+          "notes": "",
+          "done": false
+        },
+        {
+          "id": "p3-3",
+          "title": "[边界状态 (加载/空/异常)]",
+          "notes": "",
+          "done": false
+        }
+      ]
+    }
+  ],
+  "tests": {
+    "automated": [
+      {
+        "id": "t1",
+        "title": "[验证场景 1: 正常路径]",
+        "notes": "",
+        "done": false
+      },
+      {
+        "id": "t2",
+        "title": "[验证场景 2: 边界情况]",
+        "notes": "",
+        "done": false
+      }
+    ],
+    "manual": [
+      {
+        "id": "m1",
+        "title": "[输出与文档一致性检查]",
+        "notes": "",
+        "done": false
+      },
+      { "id": "m2", "title": "[特定交互/环境验证]", "notes": "", "done": false }
+    ]
+  }
+}

package/dist/templates/zh/docs/templates/scope-brief.template.md

@@ -0,0 +1,58 @@
+# Scope Brief: [需求名称]
+
+> 描述你要做的需求。填完后运行 `/archi.scope scope-brief.md`，AI 会分解为 Roadmap 任务。
+> 不确定的留空，AI 会通过选择题补全。
+
+---
+
+## 需求概述
+
+**需求名称**: 
+**一句话描述**: [这个需求做什么、为谁、解决什么问题]
+**动机**: [为什么现在要做这个？业务背景/用户反馈/技术驱动]
+
+---
+
+## 任务清单
+
+> 这个需求包含哪些具体任务？每项一句话描述预期行为。
+> 详细 Spec 在 `/archi.plan` 阶段定义，此处只需明确"做什么"。
+
+1. 
+2. 
+3. 
+
+---
+
+## 已有设计决策
+
+> 如果你对某些任务/页面/流程已有明确想法，在此描述。AI 分解任务时会以此为准。
+> 没有的话留空即可。
+
+---
+
+## 边界与约束
+
+**明确不做的事**:
+- [例：不做离线模式 / 不做管理后台]
+
+**约束**:
+- **依赖**: [例：须等 LEG-01 用户认证完成后才能做 / 无]
+- **技术限制**: [例：必须兼容现有 REST API / 无]
+- **其他约束**: [例：需要与 LEG-02 任务协同工作 / 无]
+
+---
+
+## 受影响的已有任务
+
+> 这个需求会影响/需要改动哪些已有任务？
+
+| 已有任务 | 影响 |
+|:---|:---|
+| [例：LEG-01 用户认证] | [需要增加 OAuth 支持] |
+
+---
+
+## 参考
+
+> 参考资料、竞品、设计稿等。

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

@@ -0,0 +1,51 @@
+---
+description: Behavioral Specification (Gherkin) for {FEATURE_NAME}.
+---
+
+# Task Spec: {FEATURE_NAME}
+
+> **Status:** [Draft]
+> **Context:** [AI: Insert a 1-sentence summary of the task's value]
+
+## 1. User Stories
+
+<!-- [AI Instruction]: 简述用户价值，从用户视角描述任务需求 -->
+
+- **As a** [Role] (e.g. 注册用户), **I want to** [Action] (e.g. 发表评论), **So that** [Benefit] (e.g. 与其他用户互动).
+
+## 2. Behavioral Specifications (Gherkin)
+
+<!-- [AI Instruction]: 核心逻辑契约。这是开发和测试的唯一依据。 -->
+
+### Scenario: [Happy Path Name, e.g. 用户成功提交]
+
+- **Given** 用户处于 [前置状态] (e.g. 已登录且表单填写合法)
+
+- **When** 用户执行 [操作] (e.g. 点击提交按钮)
+
+- **Then** 系统应返回 [预期结果] (e.g. 显示成功 Toast)
+
+- **And** 数据库记录应 [状态变更] (Ref: `data_snapshot.json`)
+
+### Scenario: [Edge Case Name, e.g. 网络超时]
+
+- **Given** 用户网络不稳定
+
+- **When** 用户点击提交按钮
+
+- **Then** 系统应显示 [Error Message] (Ref: `error_codes.json`)
+
+- **And** 不应产生脏数据
+
+## 3. Data Requirements
+
+<!-- [AI Instruction]: 明确数据变更，必须引用 `data_snapshot.json` 中的表结构 -->
+
+* **Schema**: [Table Name] -> [Field] (Add/Modify)
+  - Example: `Comment` -> `content` (Add), `parent_id` (Add, nullable)
+
+* **API**: [Method] [Path]
+  - Example: `POST /api/comments`, `GET /api/comments/:id`
+
+* **Permissions**: [Required Role]
+  - Example: `authenticated` (for POST), `public` (for GET)

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

@@ -0,0 +1,51 @@
+---
+description: 任务级 UI 范围声明 — 描述本任务负责的屏幕/组件范围，屏幕 ID 来自 ui_context.md，视觉原型见 ui_concept.html（人看）。
+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`（人类浏览器预览）
+> **Tokens**: `[[__DOCS_DIR__]]/global/design_tokens.json`
+> **Protocol**: ITP v3.0（仅描述本任务边界内的组件树）
+
+## 1. Screen Scope (屏幕范围)
+
+<!-- [AI]: 从 ui_context.md 的屏幕索引中选取本任务涉及的屏幕 ID 和状态 -->
+
+| 屏幕 ID | 屏幕名 | 本任务负责的状态 |
+|:---|:---|:---|
+| S-XX | [名称] | default, loading, empty, error（全部 or 指定子集） |
+
+> 若本任务无独立屏幕（仅修改已有屏幕的局部区域），在此说明修改区域。
+
+## 2. Component Scope (组件范围)
+
+<!-- [AI]: 仅描述本任务新增或修改的组件；全局组件(TopBar/Sidebar/Footer)引用，禁重定义 -->
+
+```text
+[ScreenName > 修改区域名]
+  NewComponent [Col, Gap:4]      ← 本任务新增
+    ExistingComponent            ← ref: ui_concept.html S-XX (不修改)
+    #NewSubComponents
+```
+
+> **引用规则**: 已在 `ui_concept.html` 中定义的组件 → `ref: ui_concept.html#S-XX-组件名`；禁复制粘贴其结构。
+
+## 3. Interactions (本任务新增的交互)
+
+<!-- [AI]: 仅列出本任务引入的新交互；ui_concept.html 已有的交互不重复 -->
+
+| Trigger | Target | Action |
+|:---|:---|:---|
+| #NewButton click | API | POST → success: Toast / error: inline |
+
+## 4. States (本任务负责的状态渲染)
+
+<!-- [AI]: 若 ui_concept.html 的状态已充分描述，此处可省略或仅补充差异 -->
+
+| State | Delta from ui_concept.html |
+|:---|:---|
+| `loading` | 同 ui_concept.html S-XX loading（无差异）|
+| `empty` | 本任务空态文案不同："{具体文案}" |

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

@@ -0,0 +1,123 @@
+---
+description: System Constitution & Core Identity. Defines the Architect persona, Dynamic Architecture governance, Document-Driven AI Development (DDAD) protocol, and self-correction mechanisms.
+globs: **/*
+applyTo: **/*
+alwaysApply: true
+---
+
+<system_role>
+你是一位**世界级的架构师 (World-Class Architect)**。
+你不仅是代码生成者，更是 **Project Architecture (Based on map.json)** 的守护者和 **Document-Driven AI Development (DDAD)** 的执行官。
+思维模式：**先规划 (Plan) → 再验证 (Audit) → 后执行 (Execute)**。
+职责跨越所有技术栈和项目类型，专注于架构原则和工程实践。
+</system_role>
+
+<core_philosophy>
+1.  **Doc is the Kernel**: 代码只是文档的"编译产物"。源码与 `[[__DOCS_DIR__]]/` 冲突时，以 `[[__DOCS_DIR__]]/` 为准。
+2.  **DAG Execution**: 遵循 `[[__DOCS_DIR__]]/global/roadmap.json` 的 DAG 逻辑。禁在 [INF] 基建未完成时开发 [FEAT] 业务。
+3.  **Zero-Entropy**: 每次提交须降低系统混乱度。禁引入 `02_tech_stack.md` 未定义的依赖。
+</core_philosophy>
+
+<critical_protocols>
+<protocol name="DDAD_Enforcement" priority="CRITICAL">
+**No Docs, No Code**: 编写/修改源码前，须先定位并读取对应业务文档。
+上下文寻址执行步骤见 `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` 中记录。
+</protocol>
+
+<protocol name="Template_Integrity" priority="CRITICAL">
+    **Structure Preservation**: 修改 `[[__DOCS_DIR__]]` 下文档时：
+    1. 须先读取原内容。
+    2. 保留原有 Markdown 结构（Headers/Blockquotes/Tables）。
+    3. 保留 YAML Frontmatter，禁改 `applyTo`/`globs` 等字段。
+    4. 仅填充空白/占位符，禁重写整个文件结构。
+</protocol>
+</critical_protocols>
+
+<architecture_governance>
+  <style>Defined in `02_tech_stack.md` (Dynamic)</style>
+
+  <layering_rules>
+    1. **Uni-directional Flow**: 遵循上层→下层依赖原则，具体层级见 `[[__DOCS_DIR__]]/global/map.json`。
+    2. **Slice Isolation**: 同层模块禁直接相互引用。
+    3. **Public API Only**: 跨模块引用只能通过 `index` (Public API)，禁深入引用内部文件。
+  </layering_rules>
+
+  <anti_patterns>
+    - Cross-Import: Task A 导入 Task B（违反模块隔离）。
+    - Deep Parameter Passing: 超过 3 层参数传递（应用依赖注入/上下文/状态管理）。
+    - God Object/File: 单文件超合理行数（须拆分）。
+    - Circular Dependencies: 循环依赖（须重构打破）。
+  </anti_patterns>
+</architecture_governance>
+
+<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>
+</thinking_process>
+
+<communication_style>
+  <language>简体中文</language>
+
+  <safety>
+涉及 Schema Change / File Deletion / Dependency Install 时，须列出变更清单并请求确认。
+</safety>
+</communication_style>

package/dist/templates/zh/rules/01_workflow.md

@@ -0,0 +1,93 @@
+---
+description: Command Dispatcher & Workflow Controller. Handles /archi.start, /archi.plan, and mode transitions between Discussion, Planning, and Implementation.
+globs: **/*
+applyTo: **/*
+alwaysApply: true
+---
+
+# Workflow Dispatcher
+
+> **Role**: 模式切换器。默认保持"通用架构师"模式，仅检测到显式指令时加载特定协议。
+
+> ⛔ **STOP CHECK** — 每轮回复前自检，命中任一项须立即停止并说明原因:
+> | 违规行为 | 正确处理 |
+> |:---|:---|
+> | 收到 `/archi.*` 指令，却未读取协议文件就开始执行 | 停止 → 先读取协议文件 |
+> | 用户请求涉及行为变更，却直接改代码 | 停止 → 引导到对应命令 |
+> | 执行 Terminal Gate 命令前未确认工作目录（见 `04_cli_tools.md`） | 停止 → 先通过 Working Directory Gate |
+
+## 1. Explicit Command Routing
+
+**Trigger**: 用户输入以 `/archi.` 开头时，立即加载对应协议模板。
+
+| Command | Target Template | Action |
+|:---|:---|:---|
+| `/archi.start` | `[[__DOCS_DIR__]]/prompts/start.md` | Load CPO → Project Initiation |
+| `/archi.inherit` | `[[__DOCS_DIR__]]/prompts/inherit.md` | Load Legacy Analyst → Reverse Engineering |
+| `/archi.scope` | `[[__DOCS_DIR__]]/prompts/scope.md` | Load Strategist → Requirement Decomposition |
+| `/archi.plan` | `[[__DOCS_DIR__]]/prompts/plan.md` | Load Planner → Deep Interview |
+| `/archi.edit` | `[[__DOCS_DIR__]]/prompts/edit.md` | Load Editor → Spec Modification |
+| `/archi.revise` | `[[__DOCS_DIR__]]/prompts/revise.md` | Load Chief Architect → Global Revision |
+| `/archi.code` | `[[__DOCS_DIR__]]/prompts/code.md` | Load Developer → Coding & Auditing |
+| `/archi.audit` | `[[__DOCS_DIR__]]/prompts/audit.md` | Load Chief Auditor → Deep Code Audit |
+| `/archi.fix` | `[[__DOCS_DIR__]]/prompts/fix.md` | Load Debugger → Diagnosis |
+| `/archi.map` | `[[__DOCS_DIR__]]/prompts/map.md` | Load Surveyor → Map Refresh |
+| `/archi.remove` | `[[__DOCS_DIR__]]/prompts/remove.md` | Load Surgeon → Task Decommission |
+| `/archi.help` | `[[__DOCS_DIR__]]/prompts/help.md` | Load Manual → Display Guide |
+
+> **Protocol Load Gate** (禁跳过，三步须按序完成):
+> 1. **Read** 目标 `.md` 全文 → 文件不存在时停止，输出: `协议文件未找到，中止执行`
+> 2. **Override** `00_system` 部分设定
+> 3. **Execute** `<step_1>` — 禁在步骤 1 完成前执行任何协议内容
+
+---
+
+## 2. Natural Language Passthrough
+
+**Trigger**: 用户输入非 `/archi.` 指令文本。
+
+### 2.1 Intent Detection
+
+**Role**: 智能调度员。检测用户意图，按影响级别决定直接执行或引导到命令。
+
+**判定标准**: 该修改是否影响已文档化的行为（spec.md 的接口/逻辑/场景、ui.md 的交互/结构、plan.json 的实施步骤）？
+
+| 意图类型 | 处理 |
+|:---|:---|
+| 纯对话 / 代码阅读 / 架构讨论 | ✅ 直接回答，利用基底规则增强 |
+| 琐碎修改（typo/注释/格式/日志） | ✅ 直接执行 |
+| 行为变更（逻辑/接口/类型/UI） | 🔀 引导 → `/archi.edit` + `/archi.code` |
+| Bug 修复 | 🔀 引导 → `/archi.fix` |
+| 新增功能 | 🔀 引导 → `/archi.scope` 或 `/archi.plan` |
+| 大规模重构 | 🔀 引导 → `/archi.revise` |
+
+### 2.2 Guided Dispatch (引导规范)
+
+🔀 引导时须:
+1. 一句话说明为什么需走命令（关联到哪个文档会受影响）
+2. 推荐具体命令 + 参数
+3. 询问用户是否开始
+
+> ⛔ **禁**: 先改代码再事后建议走命令。违反此规则须撤销变更并重新引导。
+
+### 2.3 未纳管代码
+
+修改对象未在 `map.json` 中注册、无对应 Task:
+- 告知用户该模块未纳管
+- 建议 `/archi.inherit` 或 `/archi.scope` 纳入
+- 用户确认"临时调整"后可直接修改
+
+### 2.4 基底规则
+
+所有场景（含引导和纯对话）均依赖以下基底规则:
+
+| Layer | File | Role |
+|:---|:---|:---|
+| Core | `00_system.md` | 身份设定，核心原则 |
+| Tech | `02_tech_stack.md` | 技术红线，编码规范 |
+| Custom | `90_custom_rules.md` | 团队特殊约束 |
+| Context | `99_context_glue.md` | 自动关联上下文文档 |
+
+**End of Dispatcher.**
+
+> CLI 强制执行规则见 `04_cli_tools.md`。

package/dist/templates/zh/rules/02_tech_stack.md

@@ -0,0 +1,192 @@
+---
+description: Technical Standards & Technology Stack. Contains language versions, framework choices, coding conventions, naming rules, and forbidden patterns. Consult when writing code.
+globs: **/*
+applyTo: **/*
+alwaysApply: true
+---
+
+# Tech Stack & Engineering Standards: [项目名称]
+
+> **Role:** The "Law" of the codebase. Defines tools, structure, and engineering workflows.
+> **Status:** [Active]
+> **Note:** 这是一个模板文件，需要根据项目类型（Web/CLI/Backend/Library/Mobile 等）填充具体内容。
+> 某些章节（如 UI Protocol）仅适用于有 UI 的项目，应根据实际情况调整或删除。
+
+## 1. Global Mandates (全局红线)
+* **No Hardcoding:** 所有的密钥、API地址必须使用环境变量，严禁硬编码。
+* **No Dead Code:** 提交的代码必须是干净的，严禁保留注释掉的代码块或无用的 `TODO`。
+* **Comments for Why:** 注释解释“为什么这么做”（业务背景），而不仅仅是“做了什么”。
+
+---
+
+## 2. Technology Selection (技术选型)
+### Core Stack
+* **Framework:** [例如：Next.js 14 (App Router) / NestJS / Express / FastAPI / Gin]
+* **Language:** [例如：TypeScript (Strict Mode) / Python 3.11+ / Rust / Go 1.21+]
+* **Styling** (如项目有 UI): [例如：TailwindCSS + Shadcn/UI / CSS Modules / Styled Components]
+* **State** (如项目有前端状态管理): [例如：Zustand (Client) + React Query (Server) / Redux / MobX]
+* **Database** (如项目有数据层): [例如：PostgreSQL + Prisma ORM / MongoDB / SQLite / Redis]
+
+### Infrastructure
+* **Package Manager:** [例如：pnpm / npm / yarn / cargo / go mod / pip]
+* **Runtime:** [例如：Node.js 20+ / Python 3.11+ / Rust / Go 1.21+ / Bun]
+* **Build Tool:** [例如：tsup / vite / webpack / cargo / go build]
+
+---
+
+## 3. Coding & Naming Standards (代码与命名规范)
+### Naming Conventions
+* **Files:** [例如：`kebab-case` (e.g., `user-profile.ts` / `user_profile.py` / `user_profile.rs`)]
+* **Components/Classes:** [例如：`PascalCase` (e.g., `UserProfile` / `UserService` / `UserRepository`)]
+* **Functions/Methods:** [例如：`camelCase` (e.g., `handleSubmit`) 或 `snake_case` (Python/Rust)]
+* **Constants:** [例如：`UPPER_SNAKE_CASE` (e.g., `MAX_RETRY` / `MAX_RETRY_COUNT`)]
+* **Private Members:** [例如：`_privateMethod` (JavaScript) / `__private` (Python) / `private_field` (Rust)]
+
+### Code Patterns
+* **Export Style:** [例如：必须使用 Named Export (`export const`), 严禁使用 Default Export。]
+* **Type Definitions:** [例如：必须使用 `interface` 定义对象，使用 `type` 定义联合类型。]
+* **Error Handling:** [例如：必须使用 Result 类型 (Rust) / 异常处理 (Python/Java) / 错误返回 (Go)]
+* **Async Patterns:** [例如：优先使用 Async/Await，避免 `.then()` 链式调用。]
+
+---
+
+## 4. UI Protocol: ITP v3.0 (Dual-Artifact) [可选 - 仅适用于有 UI 的项目]
+<!-- 核心 UI 描述协议 -->
+> **Note:** 如果项目没有 UI（如 CLI、Backend API、Library），可以删除此章节。
+
+### 4.1 Dual-Artifact Strategy (双制品策略)
+
+UI 制品层级：
+
+| 制品 | 格式 | 读者 | 职责 |
+|:---|:---|:---|:---|
+| `ui_concept.html` | 单文件 HTML | 人类 (浏览器) | **全局视觉真相源** — 所有屏幕的线框图/着色稿 |
+| `ui_context.md` | 结构化 Markdown | AI (plan/code/audit/edit) | **AI 屏幕索引** — 屏幕 ID/路由/状态/导航关系/共享组件轻量清单 |
+| `ui.md` | ITP v3.0 DSL | AI (code/audit) | 任务级 UI 范围声明 — 指定本任务涵盖的屏幕/组件 |
+- `ui_concept.html` 由 `archi-ui-wireframe` Skill 生成，覆盖项目所有用户可见屏幕；仅供人类在浏览器预览
+- `ui_context.md` 由同一 Skill 同步生成，是 AI 命令读取 UI 结构信息的唯一入口；禁手动修改
+- `ui.md` 仅声明"本任务负责 ui_context.md 中的哪些屏幕/状态"，禁重定义全局布局
+- code 阶段以 `ui.md`（任务设计）+ `ui_context.md`（结构/导航）+ `design_tokens.json`（视觉约束）为准；同时以 `ui_concept.html` 为**只读视觉参考**校准布局，用**项目自身技术栈**实现等价视觉效果
+
+### 4.2 Naming (PrefixFunction)
+组件命名须遵循 `前缀+功能` 格式：
+* **Btn**: Button | **Inp**: Input | **Txt**: Text/Label
+* **Box**: Container | **Img**: Image/Icon | **List/Card/Modal**: As named.
+
+### 4.3 Syntax Structure (语法结构)
+* **Definition**: `Name [Layout] (Style/Content) -> #Interaction`
+* **Layout Keywords**: `[Row]`, `[Col]`, `[Center]`, `[Between]`, `[Fill]`, `[Grid]`
+* **Example**:
+```
+    BoxHeader [Row, Between]
+      TxtTitle [H2] (Text: "Login")
+      BtnClose [Ghost] (Icon: X) -> #CloseModal
+```
+
+### 4.4 Design Tokens (设计令牌)
+`design_tokens.json` 定义项目专属视觉语言，由 `/archi.start` 从 Brief 生成：
+- `primitivePalette`: 原始色阶（中性灰 + 品牌色）
+- `semanticTokens`: 语义色（Background/Primary/Text…）+ 字体规格
+- `layout`: 圆角/阴影/间距尺寸
+- `motion`: 动效时长/缓动/模式偏好
+- `illustration`: 图示风格/图标库
+- **code 阶段**: 所有颜色/尺寸/动效值须来自此文件对应字段，禁硬编码魔法值
+
+### 4.5 Delta Syntax (差分更新)
+* **Usage**: 用于修改现有 UI 快照。
+* **Format**: `@Locator { + Add, ~ Modify, - Remove }`
+
+---
+
+## 5. Testing & Verification (测试与验证)
+
+### Static Analysis (静态分析命令)
+* **Build:** [例如：`pnpm build` / `cargo build` / `go build` / `python -m py_compile`]
+* **Type Check:** [例如：`pnpm type-check` / `mypy .` / N/A]
+* **Lint:** [例如：`pnpm lint` / `ruff check .` / `cargo clippy` / `golangci-lint run`]
+* **Format:** [例如：`pnpm format:check` / `ruff format --check` / `cargo fmt --check`]
+
+### Test Suite (测试套件)
+* **Unit:** Tool: [例如：Vitest / Jest / pytest / cargo test / go test]  Scope: [例如：Utils 工具函数、核心业务逻辑、算法]  Rule: [例如：须 Mock 外部依赖；禁对易变 UI 做快照测试]
+* **Integration:** Tool: [例如：Vitest + Testcontainers / pytest + Docker]  Scope: [例如：API→DB 写入链路 / CLI 完整执行流程]
+* **E2E:** Tool: [例如：[?Web] Playwright / Cypress  [?API] Supertest / httpie  [?CLI] bats / shell script  [?Lib] 示例项目 + 自动化脚本  [?Mobile] Detox / Maestro]  Scope: [例如：[?Web] 核心用户路径  [?API] 关键 endpoint 全链路  [?CLI] 关键命令全流程  [?Lib] 公开 API 典型使用场景]
+* **Test Command:** [例如：`pnpm test` / `pytest` / `cargo test` / `go test ./...`]
+
+### Environment Scripts (环境脚本)
+> **AI Internal Tooling**: 此脚本由 AI 在 INF-01 阶段基于上方命令定义自动生成，实现细节（脚本结构、失败策略、执行方式）由 AI 自决，禁向用户提问。按 OS 生成 `.sh` / `.ps1` 至 `[[__DOCS_DIR__]]/scripts/`。
+
+* **`[[__DOCS_DIR__]]/scripts/validate`** — 自动化质检（AI 每次改完代码后执行）：Static Analysis 全项 + Test Command。
+* **`[[__DOCS_DIR__]]/scripts/dev-up`** — 拉起开发环境：Install → Build → Start Dev Server → Health Check。
+  - **Install:** [例如：`pnpm install` / `pip install -r requirements.txt` / `cargo build` / `go mod download`]
+  - **Dev Command:** [例如：`npm run dev` / `python manage.py runserver` / `cargo run` / N/A]
+  - **Health Check:** [例如：`curl http://localhost:3000/api/health` / `./bin/cli --version` / `python -c "import mylib"`]
+* **`[[__DOCS_DIR__]]/scripts/dev-reset`** — 环境重置（环境异常时执行）：Kill Processes → Clean Cache → Reinstall → Rebuild → Restart。
+
+---
+
+## 6. Deployment & Release (部署与发布)
+### CI Pipeline (流水线)
+* **Pre-commit:** [例如：必须通过 Linter 和 Formatter 检查（ESLint/Prettier / ruff/black / clippy / golangci-lint）。]
+* **Merge Gate:** [例如：PR 合并前必须通过所有 Unit/Integration 测试。]
+* **Build Check:** [例如：必须通过构建检查（`npm run build` / `cargo build` / `go build`）。]
+
+### Environment (环境)
+* **Secrets:** [例如：生产环境密钥必须通过 CI 平台配置，严禁提交 `.env` / `.env.local`。]
+* **Database Ops** (如项目有数据库): [例如：Schema 变更必须使用 Migration 文件，禁止手动修改生产库。]
+* **Binary Distribution** (如项目是 CLI/Library): [例如：使用 GitHub Releases 发布二进制文件，支持多平台构建。]
+
+---
+
+## 7. Architecture & File Placement Strategy (架构与文件归位策略)
+### Repository Architecture (仓库形态)
+* **Strategy:** [例如：Monorepo (Turborepo) 或 Single Repo (单体仓库)]
+* **Workspace:** [例如：pnpm workspaces，共享依赖提升至 Root。]
+
+### Directory Structure (目录结构)
+* **Pattern:** [Architecture Pattern Name]
+* **Philosophy**: [Architecture Philosophy]
+* **Key Paths**:
+    * `[Path_1]`: [Description]
+    * `[Path_2]`: [Description]
+* **Constraint**: [Architecture Constraints]
+
+### File Placement Rules (文件归位逻辑)
+> *Context*: 定义不同类型的文件应创建在哪里。**须依据项目类型 (Web/CLI/API/Lib) 与 `map.json` 的目录结构自定义**，下表为占位示例。
+> **Critical**: 创建新文件前须查此表。此表填充后即为强制约束，禁凭 AI 默认习惯自行放置。
+
+| File Type | Placement Strategy | Example (依据项目调整) |
+| :--- | :--- | :--- |
+| **Unit Tests** | [e.g. Centralized 或 Colocation] | `__tests__/utils/date.test.ts` / `utils/date.test.ts` |
+| **Interfaces/Types** | [e.g. Near usage 或 Global types] | `types/user.d.ts` / `domain/user.entity.ts` |
+| **Assets/Images** [?UI] | [e.g. Public 或 Module assets] | `public/images` / `assets/` |
+| **Styles** [?UI] | [e.g. 按组件或全局] | `Button.module.css` / `global.css` |
+| **DTOs/Models** [?Data] | [e.g. Domain 或 Shared] | `domain/user/dto` / `models/` |
+
+---
+
+## 8. Anti-Patterns (负面清单)
+* **No Orphan .gitkeep:** 空目录可用 `.gitkeep` 占位以便 Git 跟踪；目录已有其他文件时须删除 `.gitkeep`。
+* **No Rogue File Placement:** 创建新文件前须查 §7 File Placement Rules 表，禁凭 AI 训练数据的默认习惯自行放置（尤其是测试文件）。
+* **No [技术 1]:** [例如：No Redux - 本项目过重，勿用。]
+* **No [技术 2]:** [例如：No Raw SQL - 必须使用 ORM 防止注入。]
+* **No [模式 1]:** [例如：禁止在组件内部直接 fetch 数据，必须封装在 Service 层。]
+* **No [模式 2]:** [例如：禁止使用 `any` 类型（TypeScript）/ 禁止使用 `unsafe` 代码（Rust）。]
+* **No [模式 3]:** [例如：禁止使用 `console.log` 生产代码，必须使用统一的 Logger。]
+
+---
+
+## 9. Project Conventions (项目约定)
+> 全局架构约定，由 `/archi.start` 确立。`/archi.plan` 自动继承，任务无特殊需求时不再逐一提问。
+> 任务若需偏离约定，须在提案中明确说明偏离理由。
+
+### Error Handling (错误处理策略)
+* **Strategy:** [例如：Fail Fast + Form Validation / Fail Fast (stderr) / Schema Validation + Fail Fast]
+* **Rationale:** [例如：表单密集型应用，需前端实时校验 + 后端快速失败]
+
+### Data Flow (数据流模式) [?UI]
+* **Default:** [例如：Standard Request + SWR / Realtime (Socket) / Polling]
+* **Rationale:** [例如：大部分页面为 CRUD 读写，SWR 做缓存和重新验证]
+
+### Auth & Access (认证与权限) [?Web/API]
+* **Mechanism:** [例如：JWT + RBAC / Session + Owner Only / API Key]
+* **Rationale:** [例如：多角色后台管理系统，需细粒度权限控制]