architext 0.0.2 → 0.0.4

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

@@ -28,44 +28,64 @@
     2.  **Read Vision**: 读取 `[[__DOCS_DIR__]]/global/vision.md` — 仅提取北极星指标和设计哲学段落；其余章节跳过。
     3.  **Read Tech Stack**: `02_tech_stack.md` (技术红线 + **Section 9 项目约定**)。
         - 提取 Section 9 中的全局架构约定（Error Handling / Data Flow / Auth & Access），供 step_2 约定继承使用。
-    4.  [?UI] **Read Design Tokens**: `[[__DOCS_DIR__]]/global/design_tokens.json`。
-    4.5 [?UI] **Read UI Context**: `[[__DOCS_DIR__]]/global/ui_context.md`（如存在）。
+    4.  （仅ui项目） **Read Design Tokens**: `[[__DOCS_DIR__]]/global/design_tokens.json`。
+    4.5 （仅ui项目） **Read UI Context**: `[[__DOCS_DIR__]]/global/ui_context.md`（如存在）。
         - 从屏幕索引中定位本功能对应的屏幕 ID（如 S-03）及其负责的状态。
         - 锁定屏幕范围，供 step_4 生成 `ui.md §1` 时直接填入，禁自行发明新屏幕 ID。
         - 若 `ui_context.md` 不存在 → 跳过，`ui.md` 按完整 ITP 格式填写。
-    5.  [?Data] **Read Data Model**: `[[__DOCS_DIR__]]/global/data_snapshot.json`。
+    5.  （仅data项目） **Read Data Model**: `[[__DOCS_DIR__]]/global/data_snapshot.json`。
     6.  **Read Dependency Context** (如有依赖任务):
         - 仅读依赖任务 `spec.md` 的 Interface/Type 定义段（`## Interface` 或 `## Types` 章节）；不读 Scenarios 等其余内容。
         - 仅当当前 spec/plan 出现 `ref: tasks/<dep_id>/spec.md#X` 引用时执行；无引用时跳过。
         - **Stub 兼容**: 如依赖任务的 Spec-Status 为 Stub，从 stub"关联文件"提取源码，读入口文件提取公共接口/导出类型，作为上游接口参考。
         - 避免重复定义上游接口，确保对接点精确对齐。
+    7.  **Read Refs** (如有): 读取 `[[__DOCS_DIR__]]/refs/index.json`（如存在）。
+        - 根据 tags 与当前任务描述语义匹配相关 ref 条目。
+        - 仅读取命中的 ref 文件（`[[__DOCS_DIR__]]/refs/{id}.{ext}`），忽略无关条目。
+        - 若 `refs/index.json` 不存在或 refs 为空 → 跳过。
 
     **Output**: 向用户输出 **Task Context Brief**：
     ```
     ### Task Context: [功能名称] ([ID])
 
+    **任务类型**: [从 ID 前缀推断: Infrastructure / Feature / Quality / Edit]
     **目标**: [roadmap task 的 goal，如含 [用户预设] 须高亮标注]
     **上游依赖**: [已完成的依赖任务及其关键接口/类型，无则写"无"]
     **项目特征**: [已激活的 UI/Data/CLI/Lib/API 标签]
     **技术约束**: [来自 02_tech_stack.md 的关键红线]
     **设计哲学**: [来自 vision.md 的北极星指标和设计原则]
     **项目约定**: [来自 02_tech_stack.md §9 — Error Handling: X | Data Flow: X | Auth: X，无则写"未设置"]
+    **外部知识引用**: [命中的 ref id 列表，如 `wechat-pay`, `company-sdk`；无则写"无"]
     ```
     内部保留完整上下文素材，进入 step_2。
 </step_1_load>
 
 <step_1_5_complexity>
     **Role**: 产品顾问
-    **Action**: 评估功能复杂度，决定是否走完整 step_2 流程：
+    **Action**: 检测任务类型，评估复杂度，决定流程路径。
 
-    **① 粒度红线检查（优先于复杂度判定）**：
+    **⓪ Task Type 检测（最先执行）**：
 
-    | 指标 | 上限 |
-    |:---|:---|
-    | 预估 spec.md Scenario 数 | ≤ 6 个 |
-    | 预估 plan.json Phase 数 | ≤ 4 个 |
+    从 `<ID>` 前缀推断任务类型，贯穿后续所有 step：
+
+    | ID 前缀 | Task Type | spec § 2 主维度 | spec § 4 Interface Exports |
+    |:---|:---|:---|:---|
+    | `INF-` | Infrastructure | Structural（配置契约） | **必填**（下游基础设施） |
+    | `FEAT-` | Feature | Behavioral（行为场景） | 有下游 deps 时必填 |
+    | `POLISH-` | Quality | Quantitative（量化目标） | 通常省略 |
+    | `EDIT-` | Edit | 继承原任务类型 | 继承 |
 
-    > 预估方法：根据 step_1 加载的 roadmap task goal 和依赖上下文，快速列举核心行为路径数量。超出上限即触发，无需精确计算。
+    > 混合型任务（如 INF 任务含行为面）可在 § 2 中组合多个维度，用子标题区分。
+
+    **① 粒度红线检查（按 Task Type 调整上限）**：
+
+    | Task Type | Acceptance Criteria 条目上限 | plan.json Phase 上限 |
+    |:---|:---|:---|
+    | Feature | ≤ 6 个 Scenarios | ≤ 4 个 |
+    | Infrastructure | ≤ 8 个 Contracts | ≤ 5 个 |
+    | Quality | ≤ 4 个 Targets | ≤ 3 个 |
+
+    > 预估方法：根据 step_1 加载的 roadmap task goal 和依赖上下文，快速列举核心路径数量。超出上限即触发，无需精确计算。
 
     **② 复杂度判定（粒度通过后执行）**：
 
@@ -76,9 +96,21 @@
 
     **Simple 模式**:
     - 跳过 5 维度架构建议和 User Confirm Gate
-    - spec 精简为 1-2 个 Gherkin 场景
+    - spec 精简为 1-2 个 Acceptance Criteria 条目（按 Task Type 选格式）
     - plan 精简为单 Phase
     - signoff 时确认（替代 step_2 的 Gate）
+
+    **③ Design 信号检测（Standard 判定后执行）**：
+
+    Standard 任务中，检测是否需要生成 `design.md`（技术方案设计）：
+
+    | 信号 | 判定 |
+    |:---|:---|
+    | 架构建议选型的 AI- 含复杂度警告（如"极难正确实现"、"状态管理复杂"、"连接泄漏"） | **Standard + Design** |
+    | 涉及自定义状态机、非平凡算法、多组件协调协议、重试/恢复策略 | **Standard + Design** |
+    | 标准 CRUD / 配置 / 简单集成 | **Standard**（无 design.md） |
+
+    > Standard + Design 时，step_2 须输出机制预览（Part 1.5），step_4 须额外生成 `design.md`。
 </step_1_5_complexity>
 
 <step_2_interview>
@@ -113,9 +145,22 @@
 
     #### Part 2: Architecture Recommendations (架构建议)
 
-    [[SKILL: 按 `archi-plan-options` Skill 的三步选用逻辑（约定继承 → 标签路由 → 推荐 vs 展开），从五个维度的选项库中为本功能生成架构建议]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-plan-options/SKILL.md` 并遵循其三步选用逻辑执行）]]
+    [[SKILL: archi-plan-options|按 skill 的三步选用逻辑（约定继承 → 标签路由 → 推荐 vs 展开），从五个维度的选项库中为本功能生成架构建议。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-plan-options/SKILL.md` 并遵循其三步选用逻辑执行）]]
+
+    展开 Q-table 时，格式遵循 [[SKILL: archi-interview-protocol|skill 的标准输出格式]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` 并遵循其规则执行）]]。
+
+    #### Part 1.5: Mechanism Preview (机制预览) 仅Complex任务:
 
-    展开 Q-table 时，格式遵循 [[SKILL: `archi-interview-protocol` Skill 的标准输出格式]][[NO-SKILL: `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md`]]。
+    仅当 step_1_5 判定为 **Standard + Design** 时输出。列出需要技术方案设计的核心机制及拟用模式：
+
+    ```
+    ### 机制预览 (将生成 design.md)
+    | 机制 | 模式 | 简述 |
+    |:---|:---|:---|
+    | [机制名称] | [State Machine / Pipeline / Decision Matrix / Protocol] | [一句话描述] |
+    ```
+
+    > 用户可在此增删机制或修改模式选择。
 
     #### Output Format
 
@@ -133,6 +178,12 @@
     | 错误处理 | [项目约定值] | 项目约定 | ref: 02_tech_stack.md §9 |
     | ... | ... | ... | ... |
 
+    [仅 Standard + Design]:
+    ### 机制预览 (将生成 design.md)
+    | 机制 | 模式 | 简述 |
+    |:---|:---|:---|
+    | ... | ... | ... |
+
     [仅对需要用户裁决的维度展开选项表]:
     **[Q<n>] 问题标题**
     > 为什么需要用户决定（一句话）
@@ -148,6 +199,7 @@
     > - 设计修正: "注册不需要邮箱验证步骤"
     > - 维度覆写: "核心结构=C, 错误处理=B D"
     > - 问题回答: "Q1=B"
+    > - 机制修改: "去掉 Pipeline，重连不需要那么复杂"
     ```
 
     **Goal**: 锁定 `spec`, `ui`(如适用), `data_snapshot.json`(如适用)。
@@ -172,77 +224,118 @@
 
     **Action Checklist**:
     1.  **`map.json`**: 在 `directoryMapping` 注册 `[[__DOCS_DIR__]]/tasks/<ID>_<Slug>`；在 `logicalTopology` 定义模块职责与依赖。
-    2.  **`dictionary.json`**: 提取提案中的**项目业务**新术语填入 `entities`/`verbs`；注册新共享工具到 `utilities`；注册新公共组件到 `components`。
-    3.  [?Data] **`data_snapshot.json`**: 根据架构建议中核心结构的选择新增/修改 Schema。禁写"待定"，须写出字段名和类型。
-    4.  **`error_codes.json`**: 根据架构建议中错误处理的选择注册新**业务**错误码。框架脚本错误由 exit code + stderr 处理，禁注册。
-    5.  **`map.json` featureRelations**: 判断本 Task 是否属于「聚合型 Task」——即其核心职责是**列举、汇总或动态反映**其他一类 Task（如「列出所有命令」「汇总所有页面入口」「注册所有路由」）。若是，在 `featureRelations` 中追加一条记录：
-        ```json
-        {
-          "aggregator": "<本 Task ID 或文件路径>",
-          "sources": "<一句话描述聚合来源范围，如'所有 CLI 命令类 Task'>",
-          "evidence": "<依据，如'spec.md §X 描述本 Task 会动态列出所有 Y 类 Task'>",
-          "checkNote": "此类 Task 新增或删除时，检查 <aggregator> 是否需要同步"
-        }
-        ```
-        若非聚合型 Task，跳过此步。
+    2.  **数据治理同步** (`dictionary.json` / `error_codes.json` / `data_snapshot.json` 等): 按 `03_data_governance.md` 规则，将提案中涉及的新业务术语、错误码、Schema 增量同步至对应全局文件。
+    3.  **`map.json` featureRelations**: [[SUBAGENT: archi-feature-relations|mode: register, context: 判断本 Task 是否为聚合型，若是则注册 featureRelations 条目]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-feature-relations/SKILL.md`，按 mode: register 的逻辑执行）]]
 
     **Output**: 上述文件的变更 Diff (简要)。
 </step_3_global_sync>
 
 <step_4_generate>
     **Role**: 文档工程师
-    **Input**: 确认的 Unified Proposal（功能设计 + 架构建议）+ 已更新的全局上下文。
+    **Input**: 确认的 Unified Proposal（功能设计 + 架构建议）+ 已更新的全局上下文 + step_1_5 检测的 Task Type。
     **Action**: 在 `[[__DOCS_DIR__]]/tasks/<ID>_<Slug>/` 下生成标准文档。
 
     **1. `spec.md`** (必须):
     - 模板: `templates/spec.template.md`。
-    - 基于确认的功能设计和架构建议，转化为 Gherkin Scenarios。
-    - 每个 Scenario 须对应功能设计中的具体流程步骤或异常路径，禁凭空编造场景。
-    - 若为上游任务，须包含明确的 Interface/Type 定义。
 
-    **2. `ui.md`** [?UI]:
+    **spec § 2 按 Task Type 选择维度格式**：
+
+    | Task Type | § 2 主维度 | 格式要求 |
+    |:---|:---|:---|
+    | Feature | Behavioral | Gherkin (Given/When/Then)，每个 Scenario 对应功能设计中的具体流程步骤或异常路径 |
+    | Infrastructure | Structural | Configuration Contract，每个配置文件/服务一个 Contract（Path + Key Settings + Constraints + Verify）。Key Settings **须写出具体值**，禁泛化描述（如"配置 X"） |
+    | Quality | Quantitative | Quality Target，每个优化目标含 Metric + Baseline + Target + Verify |
+    | Edit | 继承原任务 | 同原任务类型 |
+
+    > 混合型任务在 § 2 内用子标题区分维度（如 INF 任务含 Behavioral 子节描述热键行为）。
+
+    **spec § 4 Interface Exports**：INF 任务**必填**（下游基础设施须声明导出约定），FEAT 任务有下游 deps 时必填。
+    **spec § 5 Constraints**：**必填** — 从 vision.md + 02_tech_stack.md 提取与本任务相关的红线。
+
+    **通用规则**:
+    - 禁凭空编造 Acceptance Criteria 条目，须对应功能设计中的具体内容。
+    - 若为上游任务，须在 § 4 包含明确的 Interface/Type 定义。
+
+    **2. `ui.md`** （本任务涉及UI时）:
     - 模板 `templates/ui.template.md`。
     - **有 `ui_context.md`（主路径）**:
-      1. **UI 偏差检查**（写 `ui.md` 前必须执行）：对比 step_2 确认的功能设计与 `ui_context.md` 中的屏幕索引，识别偏差：
+      1. **UI 偏差检查**（写 `ui.md` 前必须执行）：对比 step_2 确认的功能设计与 `ui_context.md` 中的屏幕索引，识别偏差。[[SKILL: archi-ui-wireframe|按 skill 的协议处理 UI 偏差]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` 并遵循其协议执行）]]。判定标准与处理方式：
 
          | 偏差类型 | 判定标准 | 处理方式 |
          |:---|:---|:---|
          | 无偏差 | 屏幕索引与设计一致 | 直接写 `ui.md`，引用屏幕 ID |
-         | 轻微增量 | 新增状态/弹窗/局部区域，不改整体布局 | 调用 `archi-ui-wireframe` Skill（Plan 细化模式）更新 `ui_concept.html` + `ui_context.md`，在 `ui.md` 注明 `MODIFIED: S-XX` |
-         | 结构性偏差 | 布局重构、新增独立屏幕、流程路径变化 | **暂停**，向用户输出偏差说明，等待 **OK** 后调用 Skill 更新 `ui_concept.html` + `ui_context.md`，再写 `ui.md` |
+         | 轻微增量 | 新增状态/弹窗/局部区域，不改整体布局 | 调用 skill（Plan 细化模式）更新 `ui_concept.html` + `ui_context.md`，在 `ui.md` 注明 `MODIFIED: S-XX` |
+         | 结构性偏差 | 布局重构、新增独立屏幕、流程路径变化 | **暂停**，向用户输出偏差说明，等待 **OK** 后调用 skill 更新 `ui_concept.html` + `ui_context.md`，再写 `ui.md` |
 
       2. 完成偏差处理后，按 `ui.template.md` 填写屏幕范围声明和差异组件。
     - **无 `ui_context.md`（降级路径）**: 按完整 ITP v3.0 描述组件树，引用 `design_tokens.json` Token 定义。
 
-    **3. `plan.json`** (必须):
+    **3. 仅Complex任务: `design.md`**:
+    - 模板: `templates/design.template.md`。
+    - 仅在 step_1_5 判定为 **Standard + Design** 时生成。
+    - § 2 Core Mechanisms: 按 step_2 确认的机制预览，调用 [[SKILL: archi-design-patterns|skill 的模式选择指南和标准格式生成机制描述并执行自检]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-design-patterns/SKILL.md` 并遵循其模式格式和自检清单执行）]]。
+    - § 3 Parameters: 所有机制中的数值须具体化，禁模糊描述。
+    - § 4 Invariants: 每条须可测试，须对应 plan.json 的 test 条目。
+    - § 5 Failure Modes: 每个故障须有检测方式 + 降级行为。
+    - § 6 Trace Verification: 从 spec § 2 每条 AC 追踪设计路径，有 Gap 须回补。
+
+    **4. `plan.json`** (必须):
     - 模板: `templates/plan.template.json`。
     - 根据项目类型动态调整 Phase；确保每个 Task 上下文自包含。
     - 任务描述中明确 "Additive Only" + "Respect Unknowns"。
-    - **`decisions`**: 按各维度填写；`choice` 支持多选（如 `A B`，空格分隔）、自定义（`Z: …`）；`rationale` 须填写理由，供 code 阶段参照，禁留空。
-    - **`notes`**: 每个 task 的 `notes` 须填写：`[范围] · [spec 引用] · [关键约束] · 验证: [具体操作]`；供 `/archi.code` step_4 精确定位并执行 e2e，禁留空。
-      > 示例：`实现 POST /auth/login · spec §3.1 · JWT 禁含 password · 验证: curl POST /auth/login 返回 200 + token 字段`
+
+    **WBS 分解三原则（生成 plan.json 时须遵循）**：
+
+    **原则 1 — 交付物导向**: 每个 task 的 `title` 描述**产出物**而非活动。
+    > ✅ 好: `apps/web/tsconfig.json — strict + path aliases`
+    > ❌ 差: `配置 TypeScript`
+
+    **原则 2 — 100% 覆盖**: 生成后须逐项确认覆盖度：
+    | 检查项 | 规则 |
+    |:---|:---|
+    | spec § 2 每个 Acceptance Criteria 条目 | 须有 ≥1 个 task 覆盖 |
+    | spec § 4 每个 Interface Export | 须有 task 负责创建/暴露该接口 |
+    | spec § 5 每个 Constraint | 须有 task 的 notes 中引用该约束 |
+    遗漏则补充 task 直到 100%。
+
+    **原则 3 — 粒度与互斥**:
+    | 信号 | 判定 |
+    |:---|:---|
+    | task 涉及 ≥3 个不相关文件 | 太粗 — 须拆分 |
+    | task 的 title 无法对应到具体产出文件 | 太抽象 — 须具体化 |
+    | 两个 task 修改同一文件同一区域 | 违反互斥 — 合并或重划边界 |
+    | task 的 notes 只有一句话且无验证项 | 信息量不足 — 须补充 |
+
+    **`decisions` 质量标准**:
+    - `rationale` **须含实施指导**，不仅说明"为什么选"，须说明"选了怎么配"。
+    > ✅ 好: `pnpm workspace 管理 apps/ + packages/；Turborepo pipeline: build→lint→type-check 三级缓存；root scripts 统一入口`
+    > ❌ 差: `Brief 明确要求` ← 零实施指导
+
+    **`notes` 质量标准**:
+    - 格式: `[产出文件路径或操作对象] · [spec 引用] · [关键约束] · 验证: [可执行命令 + 期望结果]`
+    - 供 `/archi.code` step_4 精确定位并执行 e2e，禁留空。
+    > ✅ 好: `创建 apps/web/next.config.ts · spec §2.2 · transpilePackages: ['@repo/ui'], output: 'standalone' · 禁 CSS-in-JS · 验证: pnpm --filter web build 成功 (exit 0)`
+    > ❌ 差: `配置 Next.js · spec §2.2` ← 无具体内容、无约束、无验证
+    > ❌ 差: `创建文件 · spec §2.1 · 验证: 检查文件存在` ← "检查文件存在" 不可执行
+    > **Red Flag**: notes 退化为 title 同义重复。每个 notes 须包含 title 中**不存在**的信息量。
+
     - 生成后运行 `npx archi render` 生成可读的 `.md` 视图。
 </step_4_generate>
 
-<step_5_audit>
-    **Role**: 首席审计官
-    **Checklist**:
-    1.  **Design Fidelity**: Spec 中的 Scenarios 是否完整覆盖确认的功能设计（流程步骤和异常路径）？
-    2.  **Tech Consistency**: 是否用了未声明技术？
-    3.  **Data Integrity**: Scenario 中的实体和字段是否与确认的核心实体一致？
-    4.  **Error Handling**: 是否覆盖架构建议中错误处理的选择？
-    5.  **AX Compliance**: 是否遵守 Anti-Clobbering 和 Interface Stability？
+<step_5_verify>
+    **Role**: 独立审查官
+    [[SUBAGENT: archi-silent-audit|mode: plan-docs, context: 审查 step_4 生成的文档（spec.md, ui.md, plan.json, design.md）]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-silent-audit/SKILL.md`，按 mode: plan-docs 的审查维度表逐项检查）]]
 
-    如有问题则静默修正；严重问题标记 `⚠️ Risk Warning`。
-</step_5_audit>
+    [[INCLUDE: shared/verify-result-handling.md]]
+</step_5_verify>
 
 <step_6_signoff>
     **Terminal Gate** (禁止跳过，须在输出总结前全部完成):
     | 步骤 | 命令 | 通过条件 |
     |:---|:---|:---|
     | 1 | `npx archi task --check` | 无 ERROR 级问题 |
-    | 2 | `npx archi task <ID> --status active` | 任务已标记为进行中 |
-    | 3 | `npx archi render` | `.md` 视图生成完成 |
+    | 2 | `npx archi render` | `.md` 视图生成完成 |
+    | 3 | `npx archi task <ID> --status active` | 任务已标记为进行中 |
 
     **Action** (Gate 通过后):
     1.  输出总结。

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

@@ -0,0 +1,63 @@
+<protocol_recover>
+**Trigger**: `/archi.recover <pack-file>`
+**Goal**: 读取 pack 文件，将其中所有用户数据（文档、任务、自定义规则）写入当前项目对应路径，完成框架升级后的数据还原。
+
+<meta>
+  <style>Precise, Efficient, Non-interactive</style>
+  <language>简体中文</language>
+  <principles>
+    1. **User Data Only**: pack 文件仅含用户数据（`global/`、`tasks/`、`scripts/`、`refs/`、自定义规则），无框架文件，全部写入，无需过滤。
+    2. **Overwrite Always**: 目标路径已存在文件时直接覆盖，无需询问（框架升级场景下旧数据即为空模板，可安全替换）。
+    3. **Delta Notation**: 输出须以 `ADDED` / `MODIFIED` 标注每个写入文件。
+    4. **No Partial Write**: 若任一文件写入失败，立即停止并报告；已写入文件不回滚（幂等，重跑安全）。
+  </principles>
+</meta>
+
+<step_1_ingest>
+  **Role**: 情报分析官
+  **Action**:
+  1. 读取 `<pack-file>` 路径的文件内容。
+  2. 解析 XML，提取 `<files>` 下每个 `<file>` 元素的 `path` 属性与 CDATA 内容。
+
+  | 情况 | 处理 |
+  |:---|:---|
+  | 文件不存在或无法读取 | 停止 — 告知用户检查路径，提示先运行 `archi pack` 生成 |
+  | XML 格式错误 | 停止 — 提示文件可能损坏，重新运行 `archi pack` |
+  | `<files>` 为空 | 停止 — 告知 pack 为空 |
+
+  **Output**: 内部文件列表（路径 + 内容），不直接输出给用户。
+</step_1_ingest>
+
+<step_2_apply>
+  **Role**: 资深工程师
+  **Action**:
+  1. 对每个 `<file>` 条目：
+     - 以 `path` 属性（相对项目根目录）为写入目标。
+     - 若目标文件已存在 → 覆盖（标记 `MODIFIED`）。
+     - 若目标文件不存在 → 新建（标记 `ADDED`）。
+     - 写入 CDATA 中的完整内容，保留原始换行与编码。
+  2. 注意：pack 中的路径可能含嵌套子目录（如 `tasks/FEAT-001_auth/spec.md`），须确保父目录存在。
+
+  **Output**:
+  ```
+  ADDED     .architext/global/vision.md
+  ADDED     .architext/global/roadmap.json
+  ADDED     .architext/tasks/FEAT-001_auth/spec.md
+  MODIFIED  .cursor/rules/90_custom_rules.mdc
+  ...
+  ```
+</step_2_apply>
+
+<step_3_signoff>
+  **Action**:
+  1. 输出还原摘要：
+     - 总计写入文件数（ADDED + MODIFIED 分别统计）
+  2. Next Steps：
+
+  | 步骤 | 说明 |
+  |:---|:---|
+  | 确认框架状态 | 运行 `/archi.help` 查看项目当前状态与建议下一步 |
+  | 清理 pack 文件 | 可删除 `<pack-file>`，已不再需要 |
+</step_3_signoff>
+
+</protocol_recover>

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

@@ -0,0 +1,258 @@
+<protocol_ref>
+**Trigger**: `/archi.ref <sub> [args]`
+**Goal**: 管理外部知识引用（第三方 API、公司内部 SDK、业务规则等），结构化存入 `refs/`，供 `plan`/`code` 按需注入上下文。
+
+**子命令**:
+| 子命令 | 格式 | 作用 |
+|:---|:---|:---|
+| `add` | `/archi.ref add [input]` | 摘要并存储外部知识（核心） |
+| `list` | `/archi.ref list` | 列出所有已存引用 |
+| `update` | `/archi.ref update <id>` | 重新摘要指定引用 |
+| `remove` | `/archi.ref remove <id>` | 删除指定引用 |
+
+<meta>
+  <style>Analytical, Precise, Context-Aware</style>
+  <language>简体中文</language>
+  <principles>
+    1. **Summarize, Not Copy**: 禁全量复制原文；须提炼为 AI 可高效使用的结构化摘要（关键接口 / 约束 / 示例），压缩比不低于 50%。
+    2. **Format-Aware**: 根据内容类型自动选择最合适的载体格式（`.md` / `.json` / `.yaml`），保留原始格式的语义优势。
+    3. **Tag-Driven**: 每个 ref 须携带 tags，供 `plan`/`code` 按需匹配注入，禁无 tag 引用。
+    4. **Index-First**: 所有操作须同步更新 `refs/index.json`，AI 通过索引按需加载，禁全量扫描。
+  </principles>
+</meta>
+
+<!-- ─── 载体格式选择规则 ─── -->
+<format_selection>
+  **Format-Aware 规则**（step_3_store 执行时参照）：
+
+  | 内容类型 | 推荐格式 | 理由 |
+  |:---|:---|:---|
+  | 网页 / URL / PDF / 纯文本 | `.md` | 结构化摘要，AI 读取效率最高 |
+  | OpenAPI / Swagger 规范 | `.yaml` | 保留机器可读结构，禁转为 .md |
+  | JSON Schema / 配置文件 | `.json` | 结构化数据原格式最优 |
+  | 混合（含大量代码示例）| `.md`（含代码块）| 代码块保留语法，加说明上下文 |
+  | 用户直接粘贴（纯 Markdown） | `.md` | 同格式存储，可精炼 |
+</format_selection>
+
+<!-- ═══════════════════════════════════════════════ -->
+<!--                   ADD 子命令                   -->
+<!-- ═══════════════════════════════════════════════ -->
+
+<sub_add>
+
+<step_0_ingest>
+  **Role**: 情报分析官
+  **Trigger**: `/archi.ref add [input]`
+  **Action**: 解析 `[input]`，确定输入来源。
+
+  | input 形式 | 处理 |
+  |:---|:---|
+  | 本地文件路径（如 `./docs/api.yaml`） | 读取文件内容，记录 `sourceType: local-file` |
+  | URL（如 `https://...`） | 抓取页面内容，记录 `sourceType: url` |
+  | 未提供（对话模式）| 告知用户粘贴内容或提供路径/URL，等待输入，记录 `sourceType: manual` |
+
+  检查 `[[__DOCS_DIR__]]/refs/index.json` 是否存在：
+  - 存在 → 读取，获取现有 id 列表（防重复命名）
+  - 不存在 → 初始化为 `{ "refs": [] }`
+
+  **Output**: 内部（原始内容 + sourceType + 现有 id 列表），进入 `<step_1_analyze>`。
+</step_0_ingest>
+
+<step_1_analyze>
+  **Role**: 系统分析师
+  **Action**:
+  1. **内容类型识别**: 判断原始内容属于哪种类型（参照 `<format_selection>`），确定推荐存储格式。
+  2. **关键信息提取**: 从内容中提取：
+     - 核心接口/端点/函数签名
+     - 参数列表与类型（入参/出参）
+     - 重要约束、限制、注意事项
+     - 认证/鉴权方式（如有）
+     - 典型使用示例（不超过 3 个）
+  3. **信息缺口识别**:
+     - id 命名（推断一个候选值，如 `wechat-pay`，待用户确认）
+     - tags 分类（从以下标准 tag 推断：`api` / `sdk` / `internal` / `payment` / `auth` / `map` / `notification` / `storage` / 自定义）
+     - 关注侧重点（若内容庞大，须确认用户最关心哪些接口/功能）
+
+  **Output**: 内部分析摘要，进入 `<step_2_interview>`（有缺口时）或直接 `<step_3_store>`（信息完整时）。
+</step_1_analyze>
+
+<step_2_interview>
+  **Role**: 产品顾问
+  **Trigger**: 仅当 id / tags / 侧重点任一不确定时执行。
+  **Action**: 向用户提问，问题上限 3 题，选项优先。
+
+  **Output 格式**:
+  ```
+  ### 引用信息确认
+
+  **内容类型**: [识别结果] → 将存储为 [.md / .yaml / .json]
+  **内容摘要**: [一句话描述原始内容]
+
+  **Q1 — 引用 ID**（用于文件命名和引用）:
+  [A] [AI 推断的候选值]（推荐）
+  [B] 自定义
+
+  **Q2 — 分类 Tags**（多选）:
+  [A] api  [B] sdk  [C] internal  [D] payment  [E] auth  [F] 其他: ___
+
+  （内容庞大时）**Q3 — 关注侧重**:
+  [A] 完整保留  [B] 仅保留 [具体接口列表]  [C] 自定义
+
+  **INPUT**: Q1答案 | Q2答案 | Q3答案（如有）
+  ```
+
+  **Gate**: 等待用户回复后进入 `<step_3_store>`。
+</step_2_interview>
+
+<step_3_store>
+  **Role**: 资深工程师
+  **Action**:
+  1. 确定存储参数：
+     - `id`: 用户确认的值（或 AI 推断值）
+     - `format`: 由 `<format_selection>` 规则确定的文件扩展名
+     - `filename`: `{id}.{format}`
+     - `tags`: 用户确认的 tags 列表
+
+  2. **生成引用文件内容**（按格式）:
+
+     **`.md` 格式骨架**:
+     ```markdown
+     ---
+     id: {id}
+     title: {标题}
+     tags: [{tags}]
+     sourceType: url | local-file | manual
+     source: {来源路径或 URL，manual 时填 "manual-input"}
+     created: {YYYY-MM-DD}
+     updated: {YYYY-MM-DD}
+     ---
+
+     ## 核心信息
+     <!-- 基础 URL、版本、认证方式等 -->
+
+     ## 关键接口
+     | 接口/函数 | 路径/签名 | 说明 |
+     |:---|:---|:---|
+
+     ## 重要约束与注意事项
+
+     ## 示例
+     <!-- 不超过 3 个最具代表性的示例 -->
+     ```
+
+     **`.yaml` 格式**: 直接存储原始 OpenAPI/Swagger 内容（精简掉示例响应中冗余的 example 字段，保留 schema 结构）。
+
+     **`.json` 格式**: 直接存储原始 JSON Schema 或配置内容（移除注释、保留结构）。
+
+  3. **写入文件**: `[[__DOCS_DIR__]]/refs/{id}.{ext}`
+
+  4. **更新索引**: 向 `[[__DOCS_DIR__]]/refs/index.json` 的 `refs` 数组追加：
+     ```json
+     {
+       "id": "{id}",
+       "title": "{标题}",
+       "tags": ["{tags}"],
+       "format": "{ext}",
+       "file": "{id}.{ext}",
+       "sourceType": "url | local-file | manual",
+       "updatedAt": "{YYYY-MM-DD}"
+     }
+     ```
+
+  **Output**:
+  ```
+  ADDED  [[__DOCS_DIR__]]/refs/{id}.{ext}
+  MODIFIED  [[__DOCS_DIR__]]/refs/index.json
+  ```
+</step_3_store>
+
+<step_4_signoff_add>
+  **Output**: 添加摘要，含：
+  - **引用 ID**: `{id}`
+  - **存储格式**: `{ext}` — 理由（一句话）
+  - **Tags**: `[tags]`
+  - **文件路径**: `[[__DOCS_DIR__]]/refs/{id}.{ext}`
+  - **如何使用**:
+
+  | 场景 | 说明 |
+  |:---|:---|
+  | `/archi.plan <ID>` | 规划时若任务涉及 `[tags]` 相关功能，AI 将自动读取此 ref |
+  | `/archi.code <ID>` | 编码时作为补充上下文注入，提供接口签名和约束细节 |
+  | 手动引用 | 在对话中直接提到 "参考 `refs/{id}`" 即可 |
+</step_4_signoff_add>
+
+</sub_add>
+
+<!-- ═══════════════════════════════════════════════ -->
+<!--                  LIST 子命令                   -->
+<!-- ═══════════════════════════════════════════════ -->
+
+<sub_list>
+
+**Role**: 系统分析师
+**Trigger**: `/archi.ref list`
+**Action**: 读取 `[[__DOCS_DIR__]]/refs/index.json`。
+
+| 情况 | 处理 |
+|:---|:---|
+| 索引不存在 / refs 为空 | 提示"当前无引用，运行 `/archi.ref add` 添加第一个" |
+| 正常 | 按 tags 分组展示 |
+
+**Output**:
+```
+### 外部知识引用库 (共 N 条)
+
+#### [tag 分组名]
+| ID | 标题 | 格式 | 更新时间 |
+|:---|:---|:---|:---|
+| wechat-pay | 微信支付 V3 API | .md | 2025-01-15 |
+| openapi-spec | 内部服务 OpenAPI | .yaml | 2025-01-10 |
+```
+
+</sub_list>
+
+<!-- ═══════════════════════════════════════════════ -->
+<!--                 UPDATE 子命令                  -->
+<!-- ═══════════════════════════════════════════════ -->
+
+<sub_update>
+
+**Role**: 资深工程师
+**Trigger**: `/archi.ref update <id>`
+**Action**:
+1. 从 `index.json` 找到 `<id>` 对应的 `file` 和 `sourceType`。
+2. 若 `sourceType` 为 `url` → 重新抓取原始 URL；`local-file` → 重新读取文件；`manual` → 提示用户粘贴新内容。
+3. 重新执行 `<step_1_analyze>` + `<step_3_store>`（保留原 id/tags/format，仅刷新内容和 `updatedAt`）。
+
+| 情况 | 处理 |
+|:---|:---|
+| id 不存在于 index.json | 停止 — 提示检查 id，可运行 `/archi.ref list` 查看 |
+
+</sub_update>
+
+<!-- ═══════════════════════════════════════════════ -->
+<!--                 REMOVE 子命令                  -->
+<!-- ═══════════════════════════════════════════════ -->
+
+<sub_remove>
+
+**Role**: 系统管理员
+**Trigger**: `/archi.ref remove <id>`
+**Action**:
+1. 从 `index.json` 中找到并移除 `<id>` 条目。
+2. 删除对应的 `refs/{id}.{ext}` 文件。
+3. 更新 `index.json`。
+
+**Output**:
+```
+REMOVED  [[__DOCS_DIR__]]/refs/{id}.{ext}
+MODIFIED  [[__DOCS_DIR__]]/refs/index.json
+```
+
+| 情况 | 处理 |
+|:---|:---|
+| id 不存在 | 停止 — 提示检查 id，可运行 `/archi.ref list` 查看 |
+
+</sub_remove>
+
+</protocol_ref>

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

@@ -61,13 +61,7 @@
 
     ### 2.4 聚合联动检查
 
-    读取 `map.json.featureRelations`，判断被删 Task 是否属于某聚合方的 `sources` 覆盖范围。
-
-    | 情况 | 处理 |
-    |:---|:---|
-    | 不在任何聚合方的 sources 范围内 | 无需特殊处理 |
-    | 在聚合方 sources 范围内 | 在影响报告中列出，提示删除后须检查聚合方内容是否需要同步移除 |
-    | 被删 Task 本身是 aggregator | 同时移除 `featureRelations` 中该条记录 |
+    [[SUBAGENT: archi-feature-relations|mode: cleanup, context: 检查被删 Task 在 featureRelations 中的引用（作为 aggregator 或属于某 sources 范围），输出影响报告]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-feature-relations/SKILL.md`，按 mode: cleanup 的逻辑执行）]]
 
     ### 2.5 跨 Task 引用
 
@@ -139,13 +133,7 @@
     |:---|:---|:---|
     | 1 | `npx archi task --check` | 无 ERROR 级问题，无悬空依赖 |
     | 2 | `npx archi render` | `.md` 视图生成完成 |
-    | 3 | 运行项目构建命令 | 零编译错误 |
-
-    | 检查项 | 通过标准 |
-    |:---|:---|
-    | Roadmap 一致性 | `--check` 通过，无悬空依赖 |
-    | 构建 | 零编译错误 |
-    | 残留引用 | 代码中无对已删模块的 import/require |
+    | 3 | 运行项目构建命令 | 零编译错误；代码中无对已删模块的 import/require |
 
     构建失败或发现残留引用 → 定位并修复后重检。
 </step_4_verify>