architext 0.0.3 → 0.0.5

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

@@ -1,7 +1,7 @@
 <protocol_inherit>
-  **Trigger**: `/archi.inherit`
+  **Trigger**: `/archi.inherit [brief_path]`
   **Phase**: Legacy Adoption
-  **Goal**: 逆向分析已有代码仓库，生成 Architext 文档骨架，将项目纳入框架管理。
+  **Goal**: 逆向分析已有代码仓库，用分析结果填充 init 部署的文档骨架（`[[__DOCS_DIR__]]`），将项目纳入框架管理。填充空占位符，非覆盖用户既有内容。可选提供 Brief 以补充愿景/路线图（适用于代码库尚空、骨架刚搭的场景）。
 
 <meta>
     <style>Analytical, Systematic, Evidence-Based</style>
@@ -10,14 +10,20 @@
       1.  **Code-Driven**: 以代码为唯一真相源，禁凭空推测功能。
       2.  **AI-Native Perspective**: 分析从 AI Agent 视角撰写。关注：Context Locality、Type Safety、Module Boundaries。
       3.  **User Agency First**: AI 的分析须经用户确认。代码解读有歧义时询问用户，禁擅自决定。
-      4.  **Minimal Token**: 优先读配置和入口文件，避免逐行扫描所有代码。
+      4.  **Thorough Discovery, Layered Recording**: 全量读取所有非第三方业务代码（排除 node_modules/vendor/dist 等生成物），不设文件数上限。记录按三档分层：核心模块详细记录流程、共享逻辑记录签名和依赖关系、纯工具记录签名和用途。宁可多读不可遗漏——后续协议无法使用未被记录的代码。
       5.  **Option Z Everywhere**: 补充提问须包含 `[Z] 自定义`。
     </principles>
 </meta>
 
 <step_0_recon>
     **Role**: 情报分析官
-    **Action**:
+
+    **Brief 检测**（仅当用户提供 `[brief_path]` 时）:
+    1. 解析 `[brief_path]`：提供了路径 → 读取该文件；未提供 → 依次查找 `project-brief.md`（项目根）、`[[__DOCS_DIR__]]/project-brief.md`
+    2. 若文件存在且非空：解析 Brief 各 Section，提取项目身份、核心任务、技术偏好、边界约束、补充说明（与 start 的 step_0_ingest 一致）
+    3. 若文件不存在或为空：跳过 Brief，后续仅以代码为输入源
+
+    **代码侦察**:
     1. 读取项目根配置文件（自动识别类型）：
 
        | 语言/生态 | 配置文件 |
@@ -30,63 +36,35 @@
        | 其他 | 以根目录配置文件为准 |
 
     2. 读取 README.md（如存在）。
-    3. 扫描目录结构（顶层 + 核心源码目录两层深度）。
+    3. 扫描目录结构（完整深度）。
     4. 推断项目特征标签（UI / Data / CLI / Lib / API — 由目录结构、依赖和配置推断）。
-    5. 识别入口文件和核心模块。
+    5. 识别入口文件和核心模块。沿入口文件的 import 链建立模块依赖草图。
 
-    **Output**: 内部摘要（不输出给用户），进入 step_1。
+    **Output**: 内部摘要（不输出给用户），进入 step_1_analysis。
 </step_0_recon>
 
 <step_1_analysis>
-    **Role**: 系统分析师
-    **扫描策略**: 中度扫描 — 读每个模块的入口文件和核心业务文件，提取主要流程链路。禁逐文件遍历。
+    **Role**: 首席产品战略官 (CPO)
+    **扫描策略**: 深度扫描 — 从入口文件出发，沿调用链读取所有业务文件。大型模块（>10 文件）优先读被多处 import 的文件。
 
     **Action**:
     1. 对每个识别出的功能模块：
-       - 读入口文件 + 1-2 个核心业务文件
+       - 从入口文件出发，沿 import/调用链逐层读取，直到覆盖该模块的主要业务逻辑
        - 提取主要流程（用户操作 → 系统处理 → 结果）
        - 记录关联文件路径
     2. 对共享/基建代码（utils, middleware, config）：
-       - 仅记录目录和职责，不作为功能模块
+       读取所有文件，按以下分档记录：
+       - **中等档**（业务共享逻辑：auth/validation/error-handling/permission）：记录职责 + 导出函数签名 + 被谁依赖
+       - **简要档**（纯工具函数：format/slugify/logger/helpers）：记录函数名 + 参数签名 + 一句话用途
+       两者均写入 map.json publicAPI 字段，确保后续协议可发现可复用。
     3. 从代码中提取领域术语和命名约定。
 
-    **Output**: 向用户输出结构化分析报告：
-    ```
-    ### 代码分析报告
-    > **项目**: [名称] | **类型**: [UI/Data/CLI/Lib/API] | **规模**: ~[文件数] 文件, [目录数] 目录
-
-    **技术栈**:
-    | 类别 | 选型 |
-    |:---|:---|
-    | 语言 | ... |
-    | 框架 | ... |
-    | 构建 | ... |
-    | 测试 | ... |
-    | 部署 | ... |
-
-    **架构模式**: [推断] — [依据]
-
-    **功能模块清单**:
-    | # | 模块 | 源码位置 | 职责 | 关键流程 |
-    |:---|:---|:---|:---|:---|
-    | 1 | [名称] | [路径] | [一句话] | [流程1], [流程2] |
-
-    **共享基建**:
-    | 目录 | 职责 |
-    |:---|:---|
-    | [路径] | [描述] |
-
-    **领域术语**: [术语列表]
-
-    **AI 不确定项** (如有):
-    - [歧义项]
-    ```
+    **Output**: 向用户输出结构化分析报告 — 含项目概况（名称/类型/规模）、技术栈表（语言/框架/构建/测试/部署）、架构模式及依据、功能模块清单（模块/源码位置/职责/关键流程）、共享基建（目录/职责/关键导出接口）、领域术语、AI 不确定项（如有）。
 
     **Gate**: 用户确认或修正。未确认禁进入 step_2。
 </step_1_analysis>
 
 <step_2_supplementary>
-    **Role**: 产品顾问
     **Trigger**: 仅当 step_1 有 AI 无法确定的项时执行。无歧义则跳过。
 
     **Action**: 以选择题形式询问歧义项。
@@ -118,40 +96,53 @@
 
 <step_3_constitution>
     **Role**: 首席架构师
-    **Input**: Step 1 分析报告 + Step 2 补充（如有）。
-    **Action**: 一次性生成项目文档骨架。
+    **Input**: Step 0 Brief 解析（如有）+ Step 1 分析报告 + Step 2 补充（如有）。
+    **Action**: 一次性填充 init 部署的文档骨架。**有 Brief 时**：Brief 优先于代码（vision/roadmap/tech_stack）；代码仍用于 map、LEG-xx、目录结构。**无 Brief 时**：仅以代码为输入源（保持原逻辑）。
 
     ### 信息路由规则
 
     > 规则文件（`02_tech_stack`、`90_custom_rules` 等）已由 IDE 注入当前上下文，AI 已知其路径，直接写入即可。
 
-    | 代码中的信息 | 目标文件 |
+    **有 Brief 时**（Brief → 目标文件）:
+    | Brief 内容 | 目标文件 |
     |:---|:---|
-    | README 项目描述、目标用户、特性列表 | `[[__DOCS_DIR__]]/global/vision.md` |
-    | 依赖清单、配置文件、代码模式 | 规则文件 `02_tech_stack` |
-    | 目录结构、模块依赖、用户旅程 | `[[__DOCS_DIR__]]/global/map.json` |
-    | 领域术语、缩写、命名约定 | `[[__DOCS_DIR__]]/global/dictionary.json` |
-    | eslint/prettier 等已有规范 | 规则文件 `90_custom_rules` |
-    | 代码中的错误码定义 | `[[__DOCS_DIR__]]/global/error_codes.json` |
-    | [?UI] CSS 变量/主题配置 | `[[__DOCS_DIR__]]/global/design_tokens.json` |
-    | [?Data] Schema/Migration 文件 | `[[__DOCS_DIR__]]/global/data_snapshot.json` |
+    | 项目身份、目标用户、成功指标、参考灵感 | `[[__DOCS_DIR__]]/global/vision.md` |
+    | 技术栈、部署目标、第三方库/服务 | 规则文件 `02_tech_stack` |
+    | 核心任务列表 | `[[__DOCS_DIR__]]/global/roadmap.json`（phase-1/2，调用 archi-decompose-roadmap） |
+    | 补充说明中的规则/约定/偏好 | 规则文件 `90_custom_rules` |
+    | 风格调性（仅ui） | `design_tokens.json` aestheticDirection 等 |
+
+    **代码中的信息**（始终适用）:
+    | 信息来源 | 目标文件 |
+    |:---|:---|
+    | README 描述/特性 | vision.md |
+    | 依赖/配置/代码模式 | 02_tech_stack |
+    | 目录结构/模块依赖/用户旅程 | map.json |
+    | 领域术语/命名约定 | dictionary.json |
+    | eslint/prettier 等规范 | 90_custom_rules |
+    | 代码中的错误码 | error_codes.json |
+    | （仅ui项目）CSS 变量/主题 | design_tokens.json |
+    | （仅data项目）Schema/Migration | data_snapshot.json |
 
     ### 3.1 Vision (`[[__DOCS_DIR__]]/global/vision.md`)
-    - 从 README + 项目配置推导
-    - 无法推导的项标注 `(AI 补全 — 建议用户审查)`
+    - **有 Brief**：从 Brief 填充（与 start 一致），代码/README 仅作补充
+    - **无 Brief**：从 README + 项目配置推导，无法推导的项标注 `(AI 补全 — 建议用户审查)`
     - 禁保留模板占位符
 
     ### 3.2 Tech Stack (规则文件 `02_tech_stack`)
-    - 已有依赖/配置 → 直接写入
-    - 代码中可见的规范（命名、结构） → 写入 Coding Standards
+    - **有 Brief**：Brief 确定的 → 直接写入；留空/推荐的 → AI 推荐；代码依赖作补充
+    - **无 Brief**：已有依赖/配置 → 直接写入；可见规范 → 写入 Coding Standards
     - 须填充完整 Section 1-8
 
     ### 3.3 Custom Rules (规则文件 `90_custom_rules`)
-    - 从 eslint/prettier/editorconfig 等提取规则
-    - 从代码模式中识别团队约定（如 named export 偏好、async/await 风格）
+    - **有 Brief**：从补充说明 + 代码 eslint/prettier 合并
+    - **无 Brief**：从 eslint/prettier/editorconfig 提取，从代码模式识别团队约定
 
     ### 3.4 Roadmap (`[[__DOCS_DIR__]]/global/roadmap.json`)
 
+    **有 Brief 时**：[[SKILL: archi-decompose-roadmap|基于 Brief 任务列表生成 phase-1/2 任务链]]；代码功能模块 → phase-0 LEG-xx（status=done）。合并两者。
+    **无 Brief 时**：仅代码功能模块 → phase-0 LEG-xx；phase-1/2 保留空骨架。
+
     **结构**:
     ```json
     {
@@ -183,7 +174,6 @@
     **规则**:
     - 功能模块 → `phase-0: Legacy`，status `done`，tag `Legacy`，ID 前缀 `LEG-`
     - 共享/基建代码不进 roadmap，仅进 map.json directoryMapping
-    - phase-1/2 保留空骨架
     - LEG 间如有依赖关系须在 deps 中体现
 
     ### 3.5 Task Stub Specs
@@ -201,11 +191,9 @@
 
     ## 关键流程
     1. **[流程名]**: [A] → [B] → [C]
-    2. **[流程名]**: [A] → [B] → [C]
 
     ## 关联文件
     - [角色]: `[路径]`
-    - [角色]: `[路径]`
     ```
 
     > Stub 是起点，非终态。后续通过 `/archi.edit` 触发补全（自动进入 `step_1_5_enrich` 流程）。
@@ -215,40 +203,46 @@
     - `logicalTopology`: 模块间依赖 → `{ "from", "to", "type" }` (imports / calls / extends)
     - `criticalUserJourneys`: 核心流程 → `{ "name", "steps": ["module → module → ..."] }`
     - `featureRelations`: 扫描代码，识别「聚合型模块」并记录。
-      **识别特征**: 某模块遍历/枚举/动态加载同类模块（如 `for (const cmd of allCommands)`、`Object.values(registry)`、读取目录后动态 import），或其描述为「汇总/列举/注册所有 X」。
-      每条记录格式: `{ "aggregator": "<ID 或文件路径>", "sources": "<来源范围描述>", "evidence": "<代码依据>", "checkNote": "此类功能新增或删除时，检查 <aggregator> 是否需要同步" }`
+      **识别特征**: 某模块遍历/枚举/动态加载同类模块，或其描述为「汇总/列举/注册所有 X」。
+      每条记录格式: `{ "aggregator", "sources", "evidence", "checkNote" }`
 
     ### 3.7 其他全局文档（按需）
     - `dictionary.json`: 从代码提取领域术语
-    - [?UI] `design_tokens.json`: 从 CSS 变量/主题提取
-    - [?UI] `ui_concept.html` + `ui_context.md`: **不由本命令生成**。继承完成后，提示用户运行 `archi-ui-wireframe` Skill 生成全局 UI 线框图（Skill 同时生成两个文件）。
-    - [?Data] `data_snapshot.json`: 从 schema/migration 提取
+    - （仅ui项目） `design_tokens.json`: 从 CSS 变量/主题提取
+    - （仅data项目） `data_snapshot.json`: 从 schema/migration 提取
     - `error_codes.json`: 从代码中的错误定义提取
 
-    **Output**: 写入所有文件，运行 `npx archi render`。
+    仅ui项目: **UI 概念设计（Adopt 模式）**: [[SKILL: archi-ui-wireframe|调用 skill（adopt 模式），从代码逆向生成 UI 概念设计。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` 并遵循其 Adopt 协议执行）]]
+    - 读取代码中的路由定义、页面组件、布局文件
+    - 读取 step_3 写入的 design_tokens.json（含代码提取的 CSS 变量/theme）
+    - tokens 不完整时触发 skill 内置引导流程
+    - 写入 `ui_concept.html` + `ui_context.md`
+    - 输出 UI 概念设计摘要，等待用户确认或反馈调整
+
+    **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` 与 package.json/config 一致？
-    3.  **Map 覆盖**: map.json 覆盖所有核心目录？
-    4.  **Roadmap 完整**: phase-0 覆盖所有已识别功能模块？
-    5.  **Stub 齐全**: 每个 LEG-xx 都有对应 tasks/ 目录和 spec.md？
-    6.  **Dictionary 无冲突**: 术语无歧义或重复？
+<step_4_verify>
+    **Role**: 独立审查官
+    [[SUBAGENT: archi-silent-audit|mode: init, context: 审查 step_3 生成的全局文件（vision, tech_stack, roadmap, map, dictionary, stub specs 等）]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-silent-audit/SKILL.md`，按 mode: init 的审查维度表逐项检查）]]
 
-    如有问题则静默修正；严重问题标记 `Risk Warning`。
-</step_4_audit>
+    [[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 — 已填充（无 Brief 时: 推导内容标注了 `(AI 补全 — 建议用户审查)`）
+    □ 02_tech_stack.md — Section 1-8 完整填充
+    □ roadmap.json — 每个功能模块对应一条 LEG-xx（status: done, tag: Legacy）
+    □ tasks/LEG-xx_<Slug>/spec.md — 每条 LEG 均有对应 Stub spec（含关联文件列表）
+    □ map.json — directoryMapping + logicalTopology + criticalUserJourneys + featureRelations 均已填充
+    □ dictionary.json + error_codes.json — 从代码提取完毕
+    □ （仅ui项目）design_tokens.json + ui_concept.html + ui_context.md — Adopt 模式已执行
+    □ Step 4 Silent Audit — 已执行，所有 CRITICAL 问题已修复
+
+    **Action** (Checklist 全部确认后):
     1.  运行 `npx archi task` 输出任务概览。
     2.  输出总结。
 

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

@@ -1,5 +1,5 @@
 <protocol_map>
-  **Trigger**: `/archi.map`
+  **Trigger**: `/archi.map` | 自然语言触发时由 Workflow Dispatch 自动加载
   **Goal**: 扫描项目实际目录结构，与 `map.json` 比对，识别新增/过期/变动，经用户确认后更新架构地图。
 
 <meta>
@@ -10,23 +10,22 @@
       2.  **Smart Granularity**: 默认目录级；单文件承载多职责时须细化到文件级。
       3.  **Architecture Inference**: 新条目的层级归类须参考现有 map 模式 + `02_tech_stack.md`。
       4.  **Batch Confirm**: 所有变更一次性展示，用户批量确认。
+      5.  **IDE-Native First**: 利用 IDE 原生能力驱动执行节奏，本协议定义质量标准和检查点，不对抗 IDE 的规划/执行机制。
     </principles>
 </meta>
 
 <step_1_scan>
-    **Role**: 测量员
     **Action**:
     1.  **Read Map**: 读取 `[[__DOCS_DIR__]]/global/map.json` — 当前架构地图。
     2.  **Read Tech Stack**: 读取 `02_tech_stack.md` — 目录结构约定、架构模式。
     3.  **Scan Directory Tree**: 扫描项目目录结构。
         - **排除**: `.git/`, `node_modules/`, `dist/`, `build/`, `[[__DOCS_DIR__]]/`, 及 `.gitignore` 中声明的路径。
-        - **深度**: 跟随 map.json 现有条目的粒度模式。如现有条目含文件级 → 扫描时也到文件级。
+        - **深度**: 跟随 map.json 现有条目的粒度模式。
 
     **Output**: 内部数据（实际目录树 + 现有 map 结构），不输出给用户。
 </step_1_scan>
 
 <step_2_diff>
-    **Role**: 比对分析师
     **Action**: 将实际目录树与 map.json 逐条比对，归类为三种差异。
 
     | 差异类型 | 判定条件 | 处理 |
@@ -37,12 +36,7 @@
 
     ### 文件级检测
 
-    对新增目录中的文件做快速扫描（读取导出/声明），识别**单文件多职责**的情况：
-    - 一个文件导出多个不相关的 class/function/module
-    - 一个入口文件聚合注册了多个子模块（如路由注册、Store 注册）
-    - 一个文件同时服务多个 Task
-
-    发现此类文件 → 粒度细化到文件级，在 map 中单独登记并描述其包含的职责。
+    对新增目录中的文件做快速扫描，识别**单文件多职责**的情况 → 粒度细化到文件级。
 
     **Output**: 差异列表（内部），进入 step_3。
 </step_2_diff>
@@ -53,22 +47,17 @@
 
     ### 归类策略
 
-    1.  **模式匹配**: 参考 map.json 中同层级已有条目的归类。如 `src/services/auth/` 属于 "Service Layer"，则 `src/services/payment/` 大概率也属于 "Service Layer"。
-    2.  **Tech Stack 约定**: `02_tech_stack.md` 中定义的目录结构规则（如 "commands/ 下为 Task Layer"）。
-    3.  **内容推断**: 读取文件内容（import 关系、导出类型），判断其架构角色。
-    4.  **无法确定**: 标记为 `[?]`，交由用户在确认阶段指定。
+    1.  **模式匹配**: 参考 map.json 同层级已有条目的归类。
+    2.  **Tech Stack 约定**: `02_tech_stack.md` 中的目录结构规则。
+    3.  **内容推断**: 读取文件内容（import 关系、导出类型）。
+    4.  **无法确定**: 标记为 `[?]`，交由用户指定。
 
-    对每个新增条目填充：
-    - `path`: 目录或文件路径
-    - `layer`: 架构层级
-    - `description`: 一句话描述职责
-    - `[?文件级]` `contains`: 该文件包含的子职责列表
+    对每个新增条目填充：`path`、`layer`、`description`、`[?文件级] contains`。
 
     **Output**: 已归类的新增条目列表（内部），进入 step_4。
 </step_3_classify>
 
 <step_4_propose>
-    **Role**: 咨询顾问
     **Action**: 向用户展示完整变更清单。
 
     **Output**:
@@ -83,49 +72,38 @@
     #### 过期条目 (将移除)
     | 路径 | 原层级 |
     |:---|:---|
-    | src/legacy/old-module/ | Service Layer |
 
     #### 新增条目 (将登记)
     | 路径 | 层级 | 描述 | 粒度 |
     |:---|:---|:---|:---|
-    | src/services/payment/ | Service Layer | 支付服务模块 | 目录 |
-    | src/utils/validators.ts | Shared Layer | 表单校验 + 数据校验 + API 参数校验 | 文件 |
-    | src/routes/api.ts [?] | [待指定] | 聚合注册多条 API 路由 | 文件 |
 
     #### 疑似重命名
     | 原路径 | 新路径 | 置信度 |
     |:---|:---|:---|
-    | src/helpers/ | src/utils/ | 高 (文件内容匹配) |
 
     ---
-    > 回复 **OK** 确认全部；或指定修改：
-    > - "src/routes/api.ts 属于 App Layer"
-    > - "src/helpers/ 不是重命名，保留原条目"
-    > - "新增 src/config/ 为 Config Layer"
+    > 回复 **OK** 确认全部；或指定修改。
     ```
 
     **Gate**: 用户确认后进入 step_5。
 </step_4_propose>
 
 <step_5_apply>
-    **Role**: 系统管理员
     **Action**:
-    1.  按用户确认的变更清单更新 `[[__DOCS_DIR__]]/global/map.json`：
-        - 移除过期条目
-        - 添加新增条目（含层级、描述）
-        - 处理重命名（更新路径，保留其他元数据）
-    2.  更新 `lastUpdated` 字段。
-
-    **Terminal Gate** (禁止跳过，须在输出总结前全部完成):
-    | 步骤 | 命令 | 通过条件 |
-    |:---|:---|:---|
-    | 1 | `npx archi render` | `.md` 视图生成完成 |
+    1.  按确认清单更新 map.json（移除过期、添加新增、处理重命名）。
+    2.  更新 `lastUpdated`。
+
+    **Terminal Gate** (禁止跳过): 标准检查 (task --check + render)。
+
+    **Pre-signoff Checklist** (Output 前须逐项确认):
+    □ 用户已在 step_4 明确确认变更清单（Gate 通过后才执行）
+    □ 过期条目已从 directoryMapping 移除
+    □ 新增条目已正确归类（path + layer + description 均已填写）
+    □ 疑似重命名已明确处理（非静默忽略）
+    □ lastUpdated 已更新
+    □ Terminal Gate — task --check + render 通过
 
-    **Output**: 更新摘要：
-    - **移除**: N 条过期条目
-    - **新增**: N 条（含 M 条文件级）
-    - **重命名**: N 条
-    - **当前 map 总条目数**: X
+    **Output**: 更新摘要 — 移除 N 条 / 新增 N 条（含 M 条文件级）/ 重命名 N 条 / 当前总条目数。
 </step_5_apply>
 
 </protocol_map>