architext 0.0.2

package/dist/templates/zh/docs/global/design_tokens.json

@@ -0,0 +1,135 @@
+{
+  "_comment": "由 /archi.start 基于 Brief「风格与调性」和「视觉参考」生成。所有值须从 Brief 推导，禁直接复用任何模板默认值。",
+  "scope": "[?UI]",
+  "status": "drafting",
+
+  "aestheticDirection": {
+    "preset": "",
+    "_presetOptions": "saas-dark | saas-light | dashboard | marketing | mobile-app | editorial | brutalist | custom",
+    "customDescription": ""
+  },
+
+  "primitivePalette": {
+    "neutral": {
+      "50": "",
+      "100": "",
+      "200": "",
+      "300": "",
+      "400": "",
+      "500": "",
+      "600": "",
+      "700": "",
+      "800": "",
+      "900": "",
+      "950": ""
+    },
+    "brand": {}
+  },
+
+  "semanticTokens": {
+    "colors": [
+      { "token": "Background", "light": "", "dark": "", "usage": "页面背景" },
+      {
+        "token": "Surface",
+        "light": "",
+        "dark": "",
+        "usage": "卡片, 弹窗, 侧边栏"
+      },
+      {
+        "token": "Primary",
+        "light": "Brand-?00",
+        "dark": "Brand-?00",
+        "usage": "主按钮, 激活状态"
+      },
+      { "token": "Text-Main", "light": "", "dark": "", "usage": "正文, 标题" },
+      {
+        "token": "Text-Muted",
+        "light": "",
+        "dark": "",
+        "usage": "次要信息, 注释"
+      },
+      { "token": "Border", "light": "", "dark": "", "usage": "边框, 分割线" },
+      {
+        "token": "Destructive",
+        "light": "",
+        "dark": "",
+        "usage": "删除, 错误提示"
+      }
+    ],
+    "typography": [
+      {
+        "role": "H1",
+        "fontFamily": "",
+        "size": "",
+        "weight": "",
+        "lineHeight": ""
+      },
+      {
+        "role": "H2",
+        "fontFamily": "",
+        "size": "",
+        "weight": "",
+        "lineHeight": ""
+      },
+      {
+        "role": "Body",
+        "fontFamily": "",
+        "size": "",
+        "weight": "",
+        "lineHeight": ""
+      },
+      {
+        "role": "Small",
+        "fontFamily": "",
+        "size": "",
+        "weight": "",
+        "lineHeight": ""
+      }
+    ]
+  },
+
+  "layout": {
+    "radius": {
+      "sm": "",
+      "md": "",
+      "lg": "",
+      "full": "9999px"
+    },
+    "shadow": {
+      "sm": "",
+      "md": ""
+    },
+    "spacing": {
+      "unit": "4px",
+      "scale": [1, 2, 3, 4, 6, 8, 12, 16]
+    }
+  },
+
+  "mode": {
+    "default": "",
+    "support": []
+  },
+
+  "motion": {
+    "preference": "",
+    "easing": {
+      "standard": "",
+      "decelerate": "",
+      "accelerate": ""
+    },
+    "duration": {
+      "instant": "",
+      "fast": "",
+      "normal": "",
+      "slow": "",
+      "pageTransition": ""
+    },
+    "patterns": {}
+  },
+
+  "illustration": {
+    "style": "",
+    "iconLibrary": "",
+    "emptyStateAsset": ""
+  }
+}

package/dist/templates/zh/docs/global/dictionary.json

@@ -0,0 +1,35 @@
+{
+  "entities": [
+    {
+      "term": "[业务术语]",
+      "definition": "[一句话定义]",
+      "codeName": "[PascalCase / camelCase]",
+      "forbiddenSynonyms": [],
+      "reference": "[来源: spec / vision / task ID]"
+    }
+  ],
+  "verbs": [
+    {
+      "verb": "[业务动作]",
+      "definition": "[一句话定义]",
+      "codeName": "[camelCase]",
+      "context": "[使用场景]",
+      "reference": "[来源]"
+    }
+  ],
+  "utilities": [
+    {
+      "name": "[工具名, 如 logger]",
+      "path": "[文件路径, 如 src/utils/logger.ts]",
+      "purpose": "[用途说明]",
+      "replaces": "[替代的原始 API, 如 console.log]"
+    }
+  ],
+  "components [?UI]": [
+    {
+      "name": "[组件名]",
+      "path": "[文件路径]",
+      "purpose": "[用途说明]"
+    }
+  ]
+}

package/dist/templates/zh/docs/global/error_codes.json

@@ -0,0 +1,19 @@
+{
+  "protocolMapping [?API]": [
+    {
+      "statusCode": "[400 | EXIT_1 | ...]",
+      "code": "[ERR_VALIDATION]",
+      "meaning": "[含义]",
+      "action": "[调用方行为: Toast / Exit / Retry / ...]"
+    }
+  ],
+  "businessErrors": [
+    {
+      "module": "[MODULE]",
+      "code": "ERR_[MODULE]_[REASON]",
+      "statusCode": "",
+      "message": "[用户/开发者可见的错误描述]",
+      "recovery": "[恢复建议]"
+    }
+  ]
+}

package/dist/templates/zh/docs/global/map.json

@@ -0,0 +1,94 @@
+{
+  "governance": {
+    "coreRules": [
+      {
+        "file": "00_system.md",
+        "role": "System Role",
+        "when": "每次对话开始时 (身份设定, 核心原则)"
+      },
+      {
+        "file": "01_workflow.md",
+        "role": "SOP",
+        "when": "决定当前任务流程 (Task vs Fix) 与验收标准"
+      },
+      {
+        "file": "02_tech_stack.md",
+        "role": "Tech Stack",
+        "when": "技术选型、代码规范、工程治理标准"
+      },
+      {
+        "file": "03_data_governance.md",
+        "role": "Data Governance",
+        "when": "读写全局 JSON 数据文件时"
+      },
+      {
+        "file": "04_cli_tools.md",
+        "role": "CLI Reference",
+        "when": "执行 Terminal Gate 命令时 (npx archi task/plan/render 语法速查)"
+      },
+      {
+        "file": "99_context_glue.md",
+        "role": "Context Bridge",
+        "when": "触碰代码时，自动关联上下文文档"
+      }
+    ],
+    "globalReference": [
+      {
+        "file": "roadmap.json",
+        "role": "Roadmap",
+        "content": "进度追踪、里程碑、技术债管理"
+      },
+      {
+        "file": "vision.md",
+        "role": "Vision",
+        "content": "愿景、北极星指标、设计哲学"
+      },
+      {
+        "file": "map.json",
+        "role": "Map (本文件)",
+        "content": "目录结构、文件索引、逻辑拓扑"
+      },
+      {
+        "file": "dictionary.json",
+        "role": "Dictionary",
+        "content": "业务术语、公共组件注册表"
+      },
+      {
+        "file": "design_tokens.json",
+        "role": "Visuals [?UI]",
+        "content": "颜色、字体、间距变量"
+      },
+      {
+        "file": "data_snapshot.json",
+        "role": "Data [?Data]",
+        "content": "数据库 Schema 镜像"
+      },
+      {
+        "file": "error_codes.json",
+        "role": "Errors",
+        "content": "错误码与协议契约"
+      }
+    ]
+  },
+  "featureDocs": [
+    {
+      "file": "spec.md",
+      "category": "Specification",
+      "purpose": "业务逻辑、算法、验收标准 (Logic)"
+    },
+    {
+      "file": "ui.md",
+      "category": "UI/UX",
+      "purpose": "任务级 UI 范围声明 — 引用 ui_context.md 中的屏幕 ID，指定本任务涵盖的屏幕/组件范围"
+    },
+    {
+      "file": "plan.json",
+      "category": "Plan",
+      "purpose": "详细步骤拆解与测试用例 (Execution)"
+    }
+  ],
+  "directoryMapping": [],
+  "logicalTopology": [],
+  "criticalUserJourneys": [],
+  "featureRelations": []
+}

package/dist/templates/zh/docs/global/roadmap.json

@@ -0,0 +1,39 @@
+{
+  "version": 1,
+  "projectStatus": "planning",
+  "lastUpdated": "YYYY-MM-DD",
+  "phases": [
+    {
+      "id": "phase-1",
+      "name": "Infrastructure",
+      "tasks": [
+        {
+          "id": "INF-01",
+          "title": "Project Scaffolding",
+          "status": "pending",
+          "description": "",
+          "goal": "",
+          "deps": [],
+          "tag": "Infra",
+          "slug": "Project_Scaffolding"
+        }
+      ]
+    },
+    {
+      "id": "phase-2",
+      "name": "Core Features",
+      "tasks": [
+        {
+          "id": "FEAT-01",
+          "title": "Example Task",
+          "status": "blocked",
+          "description": "",
+          "goal": "",
+          "deps": ["INF-01"],
+          "tag": "Core",
+          "slug": "Example_Task"
+        }
+      ]
+    }
+  ]
+}

package/dist/templates/zh/docs/global/vision.md

@@ -0,0 +1,82 @@
+---
+description: Project Constitution: Vision, Personas, Principles & Boundaries.
+---
+
+# Product Vision: [项目名称]
+
+> **Version:** 1.0.0
+> **Status:** Active
+> **Role:** The "Constitution" of the project. All Tasks and Specs must align with this.
+
+## 1. Core Vision (核心愿景)
+
+**Elevator Pitch:**
+[产品名称] 是一个 [目标市场/类别] 平台，旨在帮助 [目标用户] 解决 [核心痛点]，通过 [核心解决方案/独特点] 实现 [最终价值]。
+
+**North Star Metric (北极星指标):**
+
+* [指标名称]: [描述 - 例如：用户每日专注时长]
+
+---
+
+## 2. Target Audience (目标用户与画像)
+
+### Primary Persona (核心用户)
+
+* **Role:** [例如：备考的学生]
+* **Key Traits:** [关键词]
+* **Pain Points:**
+  * [痛点 1]
+  * [痛点 2]
+* **Goals:**
+  * [希望达成的结果]
+
+---
+
+## 3. Product Principles (产品原则)
+
+* **[原则 1]:** [例如：极简优先 - 任何增加点击的操作都需要额外理由]
+* **[原则 2]:** [例如：鼓励而非惩罚 - 完不成任务时给鼓励，而不是红色的警告]
+
+---
+
+## 4. Design & Experience (设计与体验语言) [?UI]
+
+> **Note:** 本节仅适用于有 UI 的项目。具体色值和圆角定义请严格参阅 `[[__DOCS_DIR__]]/global/design_tokens.json`。
+
+### Visual Style (视觉风格)
+
+* **Keywords:** [例如：温暖、专注、无干扰]
+* **Density:** [例如：大留白，沉浸式]
+* **Animation:** [例如：轻微的微交互，不要花哨的转场]
+
+### Tone of Voice (文案语调)
+
+* **Personality:** [例如：像一个陪读的伙伴，而不是严厉的老师]
+* **Do's:** [例如：用"我们一起"代替"你应该"]
+* **Don'ts:** [例如：不要使用机械的错误码报错]
+
+---
+
+## 5. Boundaries (边界与反目标)
+
+### In Scope (核心范围)
+
+* [核心功能 A]
+* [核心功能 B]
+
+### Out of Scope (明确不做)
+
+* **[反目标 1]:** [例如：不做社交排行榜]
+* **[反目标 2]:** [例如：不提供深色模式切换（默认即深色）]
+
+---
+
+## 🤖 AI Maintenance Guide
+
+**Trigger**: 仅在项目初始化 (`/archi.start`) 或重大战略转型 (`/archi.revise`) 时修改。
+
+**Action**:
+1.  **Alignment**: 确保 Section 3 (Principles) 与 `02_tech_stack.md` 中的技术选型不冲突。
+2.  **Completeness**: 必须填满所有 `[ ]` 占位符，严禁保留 "Example" 字样。
+3.  **Consistency**: 所有的 Task Spec (`.spec.md`) 都必须引用此文件的 Vision 以确保不跑题。

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

@@ -0,0 +1,150 @@
+<protocol_audit>
+  **Trigger**: `/archi.audit [id]`
+  **Goal**: 独立深度代码审查。带 `<id>` 审查该任务的代码实现；无 `<id>` 执行项目级体检。不修改代码，仅输出审查报告与修复工单。
+
+<meta>
+    <style>Investigative, Thorough, Evidence-Based</style>
+    <language>简体中文</language>
+    <principles>
+      1.  **Read-Only**: 禁改任何代码文件。审查 ≠ 修复。
+      2.  **Evidence-Based**: 每个发现须附文件路径、行号、代码片段。
+      3.  **Actionable Output**: 每个问题须附推荐修复命令（`/archi.fix`, `/archi.edit` 等）。
+      4.  **Vision Anchored**: 始终以 `vision.md` 为方向基准，检测偏离。
+      5.  **Report Persistence**: 审查结果须写入文件 — 任务级 → `tasks/<id>_*/audit.md`（覆盖），项目级 → `audits/YYYY-MM-DD.md`（按日期存档，同日覆盖）。
+    </principles>
+</meta>
+
+<step_1_resolve>
+    **Role**: 系统分析师
+    **Mode Gate**:
+
+    | 输入 | 模式 | 后续步骤 |
+    |:---|:---|:---|
+    | `/archi.audit <id>` | 任务级深度审查 | step_2_task → step_3_report |
+    | `/archi.audit` | 项目级体检 | step_2_project → step_3_report |
+
+    **任务级 — Resolve ID**:
+    1.  从 `[[__DOCS_DIR__]]/global/roadmap.json` 解析 `<id>` → Task Name、Slug、状态。
+    2.  **Status Gate** — 仅 `active` 或 `done` 可审查:
+
+        | 状态 | 处理 |
+        |:---|:---|
+        | `active` / `done` | 通过 |
+        | `pending` | 拒绝 — 无代码可审查，先运行 `/archi.plan` + `/archi.code` |
+        | `blocked` | 拒绝 — 前置依赖未完成 |
+
+    3.  **Load Context**:
+        - `[[__DOCS_DIR__]]/global/vision.md` — 项目方向基准
+        - `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/spec.md` — 功能逻辑
+        - `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/plan.json` — 任务清单
+        - `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/ui.md` — 任务 UI 范围声明(如存在)
+        - [?UI] `[[__DOCS_DIR__]]/global/ui_context.md` — AI 屏幕索引（定位对应屏幕 ID）
+        - [?UI] `[[__DOCS_DIR__]]/global/ui_concept.html` — 只读视觉参考（#10 合规对比的视觉标准源）
+        - `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/audit.md` — 上次审计报告(如存在，用于对比)
+        - `02_tech_stack.md` — 技术红线
+        - [?UI] `[[__DOCS_DIR__]]/global/design_tokens.json`
+        - [?Data] `[[__DOCS_DIR__]]/global/data_snapshot.json`
+    4.  读取该任务对应的所有代码文件。
+
+    **项目级 — Load Overview**:
+    1.  读取 `[[__DOCS_DIR__]]/global/vision.md`、`roadmap.json`、`map.json`。
+    2.  读取 `02_tech_stack.md`。
+    3.  扫描 `[[__DOCS_DIR__]]/tasks/` 目录结构。
+    4.  读取项目代码入口文件与关键模块。
+
+    **Output**: 审查范围与上下文清单。
+</step_1_resolve>
+
+<step_2_task>
+    **Role**: 首席审计官
+    **Scope**: 任务级深度代码审查（仅 `/archi.audit <id>` 时执行）。
+
+    逐维度审查，每个发现须附 `文件:行号` + 代码片段 + 严重级别：
+
+    | # | 维度 | 审查要点 |
+    |:---|:---|:---|
+    | 1 | **Vision 对齐** | 实现方向与 `vision.md` 有无冲突或偏离 |
+    | 2 | **Spec 完整性** | 代码是否覆盖 `spec.md` 全部场景与边界 |
+    | 3 | **Plan 真实性** | 标记 `done` 的任务是否在代码中落地（防虚标） |
+    | 4 | **逻辑正确性** | 业务逻辑错误、矛盾、遗漏分支、状态机缺陷 |
+    | 5 | **Bug 猎杀** | 空值/undefined、竞态、资源泄漏、死循环、off-by-one |
+    | 6 | **错误处理** | 吞错、静默失败、错误传播链完整性、用户可见反馈 |
+    | 7 | **Tech Stack 合规** | 对照 `02_tech_stack.md`：违禁模式、过时 API、硬编码 |
+    | 8 | **安全性** | 敏感信息泄露、输入未校验、注入风险、权限检查 |
+    | 9 | **性能** | 不必要全量导入/大循环/无用计算/内存泄漏/N+1 查询 |
+    | 10 | [?UI] **Design 合规** | 样式是否用 Token 定义的视觉模式；无硬编码魔法值；实现与 `ui_concept.html` 对应屏幕视觉一致 |
+    | 11 | [?Data] **数据一致性** | 字段名/类型与 `data_snapshot.json` 是否一致 |
+    | 12 | [?I18n] **I18n 合规** | 无硬编码字符串；须用 Key/字典引用 |
+    | 13 | **Orphan .gitkeep** | 目录已有其他文件时仍存在 `.gitkeep` — 须删除 |
+    | 14 | **Spec-Code 漂移** | 代码中的接口/类型/行为是否与 `spec.md` 一致；手动变更是否已同步到文档 |
+    | 15 | [?UI] **UI 引用完整性** | `ui.md` 中的 `ref: ui_concept.html#S-XX` 指针是否仍然有效；被引用的屏幕/组件是否因 edit/revise 后已改名或删除 |
+
+    **Output**: 按维度分组的发现列表，每项含级别、位置、描述。
+</step_2_task>
+
+<step_2_project>
+    **Role**: 首席审计官
+    **Scope**: 项目级健康体检（仅 `/archi.audit` 无参数时执行）。
+
+    | # | 检查项 | 说明 |
+    |:---|:---|:---|
+    | 1 | **Vision 漂移** | `roadmap.json` 任务方向与 `vision.md` 是否一致 |
+    | 2 | **架构一致性** | `map.json` vs 实际目录结构，有无漂移或未注册模块 |
+    | 3 | **Roadmap 健康度** | 一致性 + 进度统计 + 长期 blocked 任务 + 依赖环检测 |
+    | 4 | **文档完整度** | 各 Task 是否有 spec.md + plan.json；有无孤儿目录 |
+    | 5 | **Tech Stack 全局合规** | 抽查关键入口与模块，检测全局性违规 |
+    | 6 | **跨 Task 一致性** | 重复逻辑、命名冲突、接口不一致 |
+    | 7 | **Orphan .gitkeep** | 目录已有其他文件时仍存在 `.gitkeep` — 须删除 |
+
+    扫描后标注优先级，推荐需深度审查的 Task：
+    - `done` 但 plan 未全部完成的
+    - 代码量大但无测试的
+    - 长期 `active` 未推进的
+
+    **Output**: 项目健康概览 + 深度审查推荐列表。
+</step_2_project>
+
+<step_3_report>
+    **Role**: 报告撰写员
+    **Action**:
+
+    **Issue Classification**:
+
+    | 级别 | 含义 | 示例 |
+    |:---|:---|:---|
+    | `CRITICAL` | 须修复，阻塞发布 | 逻辑错误、安全漏洞、数据损坏风险 |
+    | `WARNING` | 应修复，有风险 | 缺少错误处理、性能隐患、Spec 覆盖不全 |
+    | `INFO` | 建议优化 | 命名不规范、缺少注释、可简化的代码 |
+
+    **Issue Format** (每项须包含):
+    ```
+    [LEVEL] 文件路径:行号 — 维度名
+      描述：具体问题
+      -> 推荐修复：/archi.fix <ID> <描述> 或 /archi.edit <ID> <描述>
+    ```
+
+    **Action Routing** (根据问题类型推荐命令):
+
+    | 问题类型 | 推荐命令 |
+    |:---|:---|
+    | Bug（逻辑错误、边界遗漏） | `/archi.fix <ID> <描述>` |
+    | Spec 缺漏（功能未完整实现） | `/archi.edit <ID> <补充描述>` |
+    | 架构级问题（全局违规） | `/archi.revise <描述>` |
+    | 功能未完成（plan 虚标 done） | `/archi.code <ID>` |
+    | 小问题（命名、注释、简化） | 下次 `/archi.code` 时一并处理 |
+
+    **Report Structure**:
+    1.  审查概要（模式、范围、日期）
+    2.  发现列表（按级别排序：CRITICAL → WARNING → INFO）
+    3.  统计摘要（各级别数量）
+    4.  修复工单汇总（可直接执行的命令列表）
+    5.  Next Steps 表格
+
+    **Write Report File**:
+    - 任务级 → `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/audit.md`（覆盖式）
+    - 项目级 → `[[__DOCS_DIR__]]/audits/YYYY-MM-DD.md`（按日期存档，同日覆盖）
+
+    **Output**: 完整审查报告（同时输出到对话和写入文件）。
+</step_3_report>
+
+</protocol_audit>