新增项目文档规范驱动并对齐log，后续还可以把pitfall和anti pitfall都关联起来形成自动纠错

.opencode/data/changelog/changelog-full.md

@@ -3,3 +3,5 @@
 完整的开发改动记录，按时间倒序排列。作为主动 RAG 的数据源，用户手动唤醒时读取。
 
 ## 记录
+
+<!-- 新条目追加在此行上方 -->

.opencode/data/changelog/changelog-headlines.md

@@ -1,3 +1,5 @@
 # Dev Changelog — Headlines
 
 最近 ~50 次改动的一句话概要，按时间倒序排列。每次会话自动注入上下文。
+
+<!-- 新条目追加在此行上方 -->

.opencode/data/changelog/changelog-recent.md

@@ -2,3 +2,5 @@
 
 最近 ~10 次改动的摘要记录，按时间倒序排列。
 当 Agent 检测到当前任务与近期改动相关时自动读取。
+
+<!-- 新条目追加在此行上方 -->

.opencode/data/deferred/registry.md

@@ -2,7 +2,7 @@
 
 ## Active Items
 
-（暂无延期方案）
+<!-- Active Items 追加在此行上方 -->
 
 ---
 

.opencode/data/profile/project-profile-log.md

@@ -3,3 +3,5 @@
 详细记录每次项目画像更新的完整上下文，按时间正序追加。
 
 ## 记录
+
+<!-- 新条目追加在此行上方 -->

.opencode/data/profile/project-profile.md

@@ -2,8 +2,12 @@
 
 ## 项目定位
 
+<!-- 条目追加在此行上方 -->
+
 ## 技术栈与架构
 
+<!-- 条目追加在此行上方 -->
+
 ## 设计约定
 
 ## 产品方向

.opencode/data/spec-docs/state.json

@@ -0,0 +1,5 @@
+{
+  "last_review_date": null,
+  "last_processed_changelog_id": null,
+  "review_count": 0
+}

.opencode/skills/epee-orchestrator/registry.md

@@ -68,3 +68,11 @@
 - **输出**: 分流决策（调用已有 Skill / 创建新 Skill）、.opencode/skills/epee-orchestrator/registry.md 维护
 - **路径**: .opencode/skills/epee-orchestrator/SKILL.md
 - **备注**: 元层 Skill，自身注册以便其他 Agent 了解调度能力的可用性
+
+### spec-docs
+- **类型**: 基础设施
+- **能力**: 规范文档全生命周期管理 — 执行前检查是否需要创建/更新文档，周期审查文档与 changelog/代码的一致性（遗漏、陈旧、互斥检测），写入/更新规范文档
+- **触发场景**: "架构"、"重构"、"设计方案"、"交互规范"、"编码规范"、"审查文档"、"review docs"、"检查规范一致性"、周期自动审查（7天/30条changelog）
+- **输出**: docs/ 下 architecture/conventions/specs 子目录的规范文档、.opencode/data/spec-docs/state.json、审查报告
+- **路径**: .opencode/skills/spec-docs/SKILL.md
+- **备注**: 操作 B 具备 changelog 不可信假设与代码搜索 fallback 的互斥检测能力

.opencode/skills/profile-memory/SKILL.md

@@ -66,17 +66,17 @@ description: >-
 在正常对话中被动检测以下信号（**不主动询问**）：
 
 **个人特质**：
-- 审美/设计偏好（"太花哨了"、"我喜欢 minimal"）
+- 审美/设计偏好（"太花哨了"、"花里胡哨"、"看着舒服"、"简洁"、"轻量"）
-- 技术偏好（"以后都用 X"、"我不喜欢 class 写法"）
+- 技术偏好（"以后都用 X"、"我不喜欢 class 写法"、"我习惯用 Y"、"我偏好"、"倾向于"）
-- 做事风格（"先讨论再动手"、"不要自作主张"）
+- 做事风格（"先讨论再动手"、"不要自作主张"、"我喜欢先定方向"、"信奉约定优于配置"）
-- 沟通偏好（"给我简短的回答"、"多解释一下原理"）
+- 沟通偏好（"给我简短的回答"、"多解释一下原理"、"精炼一点"、"别啰嗦"）
 - 产品理解/思维方式
 
 **项目信息**：
-- 项目定位和目标（"这个项目是做 X 的"）
+- 项目定位和目标（"这个项目是做 X 的"、"这个应用的核心是"、"解决什么问题"）
-- 技术栈与架构决策
+- 技术栈与架构决策（"技术栈"、"架构上"）
 - 设计约定和规范
-- 产品方向和目标用户
+- 产品方向和目标用户（"产品方向"、"产品形态"、"定位是"、"我们的用户"、"目标用户是"、"使用场景"、"面向"、"核心竞争力"、"路线图"、"长期来看"、"最终形态"）
 
 ### 检测原则
 

.opencode/skills/spec-docs/SKILL.md

@@ -0,0 +1,210 @@
+# Skill: spec-docs
+
+# Spec Docs
+
+规范文档管理系统。负责架构方案、技术规范、项目约定等文档的全生命周期管理——从创建前的提醒、到创建后的周期审查、再到一致性校验。
+
+## 存储结构
+
+| 文件/目录 | 位置 | 用途 |
+|-----------|------|------|
+| `docs/` | 项目根 | 所有规范文档（architecture/conventions/specs） |
+| `docs/README.md` | 项目根 docs/ | 目录标准与使用规范 |
+| `state.json` | `.opencode/data/spec-docs/` | 周期审查状态追踪 |
+
+## 锚点 ID 机制
+
+规范文档使用 `DOC-NNN` 格式的 ID（如 `DOC-001`），与文件名中的三位编号一致。
+每次创建新文档时自动分配（读取目录下最大编号 +1）。
+
+在 frontmatter 的 `related_changelogs` 字段中记录关联的 `CL-xxx` 锚点 ID，实现 docs ↔ changelog 双向追溯。
+
+## 操作 A：执行前检查（Pre-execution Check）
+
+### 触发条件
+
+当 Agent 判断当前任务涉及以下维度时，**在执行代码改动前**触发本操作：
+
+- **架构级改动**：跨 3+ 模块、调整分层边界、引入/替换核心依赖、修改目录结构
+- **系统方案设计**：设计系统、交互规范、数据流、API 设计、部署方案
+- **项目规范制定**：编码规范、命名约定、工作流程、Git 规范
+
+### 触发关键词
+
+任一命中即触发（仅扫描用户消息，不扫描 Agent 输出）：
+
+| 类别 | 关键词 |
+|------|--------|
+| 架构 | `架构`、`重构`、`分层`、`模块划分`、`技术选型`、`目录结构`、`核心依赖` |
+| 方案 | `设计方案`、`设计系统`、`交互规范`、`UI规范`、`界面风格`、`数据流`、`API设计`、`部署方案` |
+| 规范 | `项目规范`、`编码规范`、`命名规范`、`约定`、`标准`、`编码风格`、`工作流` |
+
+### 执行流程
+
+```
+1. 暂停执行计划
+2. 扫描 docs/ 目录，查找是否有与当前任务相关的已有文档
+   a. 按文件名关键词匹配
+   b. 按文档 frontmatter 的 type 分类匹配
+3. 分支处理：
+   ├─ 无相关文档 → 向用户建议创建新文档，提示：
+   │   "本次涉及 [架构/规范/方案]，建议在 docs/ 下创建对应文档固化下来。
+   │    是否创建？可以现在创建，也可以执行完再创建。"
+   │
+   └─ 有相关文档 → 提示用户：
+       "本次任务可能影响 [DOC-xxx]：[文档标题]。
+        是否需要在本任务完成后更新该文档？"
+4. 用户决策后继续执行
+5. 执行完成后 → 若用户同意创建/更新文档，则执行操作 C（写入/更新文档）
+```
+
+### 不触发的情况
+
+- 纯 bug 修复（不改架构/规范）
+- 单文件小改动
+- 临时实验性代码（用户明确标记为实验）
+- 纯数据文件变更
+
+---
+
+## 操作 B：周期审查（Periodic Review）
+
+### 触发条件（满足任一）
+
+1. 距离上次审查超过 7 天
+2. 上次审查后新增 30+ 条 changelog 条目
+3. 用户主动触发：`审查文档`、`review docs`、`检查规范一致性`
+
+### 状态追踪
+
+`.opencode/data/spec-docs/state.json` 格式：
+
+```json
+{
+  "last_review_date": "2026-05-01",
+  "last_processed_changelog_id": "CL-20260501-2303",
+  "review_count": 1
+}
+```
+
+### 执行流程
+
+```
+1. 加载 state.json
+   ├─ 存在 → 读取 last_processed_changelog_id
+   └─ 不存在 → last_processed_changelog_id = null（全量审查）
+
+2. 收集 changelog 增量
+   a. 读取 changelog-headlines.md（L3）
+   b. 筛选 last_processed_changelog_id 之后的新条目
+   c. 对于每条新条目，在 changelog-recent.md（L2）中定位并读取完整摘要
+
+3. 分类 changelog 条目
+   将每条新条目标记为以下三类之一：
+   ├─ `arch`：涉及架构决策、模块结构、依赖变更
+   ├─ `conv`：涉及编码规范、命名约定、工作流程
+   └─ `none`：不涉及规范文档（纯 bug 修复、单文件改动）
+
+4. 加载现有文档
+   读取 docs/ 下所有非 README、非模板的 .md 文件，解析 frontmatter
+
+5. 一致性校验（对每个文档逐个检查）
+
+   === 5a. 遗漏检查：changelog 中有，文档中无 ===
+   对于标记为 arch/conv 的 changelog 条目：
+   - 检查是否有对应的 docs/ 文档覆盖了此改动
+   - 无覆盖 → 列入"遗漏项"：建议创建新文档或追加到已有文档
+
+   === 5b. 陈旧检查：文档引用的 changelog 已不反映现状 ===
+   对于每个文档的 related_changelogs：
+   - 检查引用的 CL-xxx 是否存在于 L1 changelog-full.md
+   - 检查被引用的条目在 L1 中的 affected_files 是否仍与文档描述一致
+   - 不一致 → 列入"陈旧项"
+
+   === 5c. 互斥检查：文档与代码/changelog 描述冲突 ===
+   当 5b 发现不一致时，执行深度校验：
+   a. 从 changelog 条目的 affected_files 提取文件路径
+   b. 搜索实际代码中对应文件（Grep/Glob）
+   c. 比对：代码现状 vs 文档描述 vs changelog 记录
+   d. 三向对比结果分类：
+
+      | 代码状态 | 文档描述 | changelog 记录 | 诊断 |
+      |---------|---------|---------------|------|
+      | 与文档一致 | ✓ | 与文档不一致 | changelog 误记 |
+      | 与 changelog 一致 | ✗ | ✓ | 文档需更新 |
+      | 与两者都不一致 | ✗/✓ | ✗/✓ | 需人工调查 |
+      | 与两者都一致 | ✓ | ✓ | 无冲突 |
+
+   e. 对于"changelog 误记"：提醒用户修正 changelog
+   f. 对于"文档需更新"：列出需更新的具体章节，建议用户更新
+   g. 对于"需人工调查"：标记为严重冲突，高亮提醒
+
+   === 5d. 引用死亡检查 ===
+   - 文档中引用的 CL-xxx 在 L1 中不存在 → 标记为"死亡引用"
+
+6. 生成审查报告
+   按严重程度排序：
+
+   [严重] 互斥冲突（需人工调查）
+   [警告] 文件缺失（docs/ 缺少本应存在的文档）
+   [警告] 文档过时（与代码现状不一致）
+   [资讯] 遗漏项（changelog 中有架构级改动但未写入文档）
+   [资讯] changelog 误记（changelog 与代码/文档不符）
+
+7. 汇报用户
+   格式如下：
+   
+   "周期审查报告 — [日期]
+   自上次审查以来共 [N] 条改动，其中 [X] 条涉及架构/规范。
+   
+   [严重] ...[条数] 项
+   [警告] ...[条数] 项
+   [资讯] ...[条数] 项
+   
+   是否需要逐条查看和处理？"
+
+8. 更新 state.json（无论用户是否处理了所有问题）
+```
+
+### 审查原则
+
+- **不自动修改任何文件**——审查仅提供发现和诊断，不自动修改 docs/ 或 changelog
+- **changelog 不可信假设**——始终通过检索实际代码来验证 changelog 的准确性
+- **幂等**——重复执行同一次审查不会产生重复报告
+
+---
+
+## 操作 C：文档写入/更新
+
+### 创建新文档
+
+```
+1. 读取 docs/ 下对应子目录，确定编号（如 architecture 下最大为 002）
+2. 分配 DOC-NNN 编号，创建文件
+3. 写入 frontmatter（status: draft）
+4. 写入文档正文
+5. 在 related_changelogs 中记录当前触发的 CL-xxx
+```
+
+### 更新已有文档
+
+```
+1. 修改文档内容
+2. 更新 frontmatter 中的 updated 日期
+3. 在 related_changelogs 中追加新的 CL-xxx（去重）
+4. 如改动较大，将 status 从 stable 改为 review，提请用户确认后改回 stable
+```
+
+### 废弃文档
+
+```
+1. 将 frontmatter status 改为 deprecated
+2. 在文档顶部添加废弃提示（替代文档编号）
+3. 保留文档内容不删除（供历史追溯）
+```
+
+## 自迭代日志
+
+### 已知必要检查
+
+（暂无）

AGENTS.md

@@ -115,14 +115,33 @@ Agent 在以下场景中应自动检索 `.opencode/data/pitfalls/pitfalls.md`：
 每次完成涉及 debug/修复的任务后，应加载 `pitfall-journal` Skill 并执行写入流程。
 判断标准：问题根因是否"非显而易见"——如果只看代码逻辑觉得应该没问题但运行时报错，就值得记录。
 
+## 架构方案沉淀
+
+项目根 `docs/` 目录集中存放架构方案、技术规范、项目约定等规范文档。
+
+### 执行前检查（Pre-execution Check）
+
+当 Agent 识别到当前任务涉及以下维度时，应在**执行代码改动前**加载 `spec-docs` Skill 并执行操作 A（检查是否需要创建/更新规范文档）：
+
+**触发关键词**（任一命中即触发）：
+- 架构：`架构`、`重构`、`分层`、`模块划分`、`技术选型`、`目录结构`、`核心依赖`
+- 方案：`设计方案`、`设计系统`、`交互规范`、`UI规范`、`界面风格`、`数据流`、`API设计`、`部署方案`
+- 规范：`项目规范`、`编码规范`、`命名规范`、`约定`、`标准`、`编码风格`、`工作流`
+
+不触发的情况：纯 bug 修复、单文件小改动、临时实验代码、纯数据文件变更。
+
+### 周期审查
+
+每 7 天或每 30 条新 changelog 后，Agent 自动根据 changelog 对 `docs/` 下文档进行一致性审查（`spec-docs` Skill 操作 B），报告遗漏/陈旧/互斥项。changelog 不可信——发现互斥时优先通过检索实际代码验证。
+
 ## 任务完成 Checklist（强制）
 
 Agent 在即将输出最终回复前，必须逐项检查。跳过任何一项视为执行错误。
 
 ### A. 画像信号扫描（短路版）
 扫描本次对话中用户消息，检查是否出现以下触发词族：
-- 个人偏好：`我喜欢` / `我倾向` / `我不喜欢` / `以后都` / `我的风格` / `太花哨` / `简洁` / `精炼` / `啰嗦`
+- 个人偏好：`我喜欢` / `我倾向` / `我不喜欢` / `我讨厌` / `我习惯` / `我偏好` / `以后都` / `倾向于` / `我的风格` / `太花哨` / `花里胡哨` / `看着舒服` / `简洁` / `精炼` / `轻量` / `啰嗦` / `信奉`
-- 项目决策：`这个项目是` / `目标用户是` / `技术栈` / `架构上` / `产品方向` / `定位是`
+- 项目决策：`这个项目是` / `目标用户是` / `这个应用的` / `我们的用户` / `技术栈` / `架构上` / `产品方向` / `产品形态` / `定位是` / `使用场景` / `面向` / `核心竞争力` / `路线图` / `长期来看` / `最终形态`
 
 无匹配 → 跳过（thinking 应在 50 token 内结束）。有匹配 → 加载 `profile-memory` Skill 执行记录流程。
 
@@ -142,6 +161,10 @@ Agent 在即将输出最终回复前，必须逐项检查。跳过任何一项
 4. **本次是否有 Skill 使用异常？**（遗漏、误触、产物与预期偏差）
    - 是 → 执行 `epee-orchestrator` Skill 的自迭代确认流程
 
+5. **本次改动是否涉及架构/规范/方案？**
+   - 检查 `docs/` 下相关文档是否需要创建或同步更新
+   - 需要但尚未写入 → 加载 `spec-docs` Skill 执行操作 C 写入/更新
+
 ### C. 收尾
 先完成 checklist 中的所有写入动作，再输出面向用户的回复文本。
 如执行了 B2 项（开发日志写入），在回复末尾附 `[已记录到开发日志]`。

docs/README.md

@@ -0,0 +1,73 @@
+# 项目文档中心
+
+> 集中存放架构方案、技术规范、项目约定的文档目录。
+> Agent 和用户可以随时查阅、创建、更新此目录下的文档。
+
+## 目录结构
+
+```
+docs/
+├── README.md              # 本文件 — 目录标准与使用规范
+├── architecture/          # 架构级方案（分层、模块、技术选型、组件架构）
+├── conventions/           # 项目约定（编码规范、命名、Git 工作流）
+└── specs/                 # 系统级技术规范（API 设计、数据模型、接口协议）
+```
+
+## 文档命名规范
+
+- 文件名格式：`NNN-简短描述.md`，NNN 为三位递进编号（从 001 起）
+- 示例：`001-interaction-design-system.md`、`002-api-conventions.md`
+- 编号由 Agent 自动分配（读取目录下最大编号 +1）
+- 使用英文短横线命名（kebab-case），描述部分用英文
+
+## 文档元数据
+
+每个规范文档在文件开头**必须**包含以下 YAML frontmatter：
+
+```yaml
+---
+id: DOC-NNN
+title: 文档标题（中文）
+type: architecture | convention | spec
+status: draft | review | stable | deprecated
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+related_changelogs: [CL-xxx, CL-xxx]
+---
+```
+
+字段说明：
+- `id`：与文件名编号一致
+- `type`：architecture（架构）、convention（规范）、spec（技术规范）
+- `status`：draft（草稿）、review（审查中）、stable（已定稿）、deprecated（已废弃）
+- `related_changelogs`：关联的 changelog 锚点 ID 列表，用于溯因
+
+## 固化时机（何时写入）
+
+以下情况应创建或更新对应文档：
+
+| 场景 | 操作 |
+|------|------|
+| 完成涉及 3+ 模块的架构级改动 | 创建/更新 architecture 文档 |
+| 制定或修改了项目公共规范（编码/命名/流程） | 创建/更新 conventions 文档 |
+| 引入或替换了核心依赖（终端引擎/构建工具/UI 库） | 更新 architecture 文档 |
+| 调整了目录结构或模块划分 | 更新 architecture 文档 |
+| 设计或修改了 UI/交互标准 | 创建/更新 architecture 文档 |
+| 定义了 API 接口、数据模型、通信协议 | 创建/更新 specs 文档 |
+| 约定被废弃或替换 | 标记为 deprecated，写明替代文档编号 |
+
+## 更新与维护
+
+- **关联 changelog**：每次基于开发改动更新文档时，必须在 `related_changelogs` 中追加对应的 `CL-xxx` 锚点 ID
+- **代理审查**：Agent 在周期审查中会自动对比 changelog 与文档的一致性（见 `spec-docs` Skill）
+- **手动审查**：用户可在任意时间要求 Agent 执行文档审查
+- **冲突处理**：当文档与代码/changelog 存在逻辑互斥时，Agent 应标记为 `review` 状态并提请用户裁决
+
+## 与其它系统的关系
+
+| 系统 | 关系 | 说明 |
+|------|------|------|
+| `dev-changelog` | 上游数据源 | changelog 记录"做了什么"，docs 沉淀"如何做的规范" |
+| `spec-docs` Skill | 管理工具 | 负责文档的创建提醒、周期审查、一致性校验 |
+| `deferred-decisions` | 互补 | deferred 记录"暂不做的方案"，docs 记录"已确定的方案" |
+| `profile-memory` | 互补 | profile 描述项目"是什么"，docs 描述项目"怎么做" |