kb

name	kb
description	知识库管理技能；知识库操作时读取；包含初始化、更新、同步策略

知识库管理 - V2 规则

目标： 管理 .sopify-skills/ 的 V2 分层知识，保持长期知识、活动方案与归档层职责清晰。

知识库结构

.sopify-skills/
├── blueprint/
│   ├── README.md           # 纯索引页，只保留索引必需区块
│   ├── background.md       # 长期目标、范围、非目标
│   ├── design.md           # 模块/宿主/目录/消费契约
│   └── tasks.md            # 未完成长期项与明确延后项
├── project.md              # 项目技术约定
├── user/
│   ├── preferences.md      # 用户长期偏好
│   └── feedback.jsonl      # 原始反馈事件
├── plan/
│   └── YYYYMMDD_feature/   # 当前活动方案
├── history/
│   ├── index.md            # 归档索引
│   └── YYYY-MM/
└── state/                  # runtime machine truth

初始化策略

Full 模式 (kb_init: full)

首次 bootstrap 直接创建：

创建文件:
  - .sopify-skills/project.md
  - .sopify-skills/user/preferences.md
  - .sopify-skills/user/feedback.jsonl
  - .sopify-skills/blueprint/README.md
  - .sopify-skills/blueprint/background.md
  - .sopify-skills/blueprint/design.md
  - .sopify-skills/blueprint/tasks.md

注意：

• 不预建 plan/ 正文。
• 不预建 history/index.md 或任何 archive。

Progressive 模式 (kb_init: progressive) [默认]

按生命周期创建：

首次真实项目触发:
  - .sopify-skills/project.md
  - .sopify-skills/user/preferences.md
  - .sopify-skills/blueprint/README.md

首次进入 plan 生命周期:
  - .sopify-skills/blueprint/background.md
  - .sopify-skills/blueprint/design.md
  - .sopify-skills/blueprint/tasks.md
  - .sopify-skills/plan/YYYYMMDD_feature/

首次显式 ~go finalize:
  - .sopify-skills/history/index.md
  - .sopify-skills/history/YYYY-MM/YYYYMMDD_feature/

首次出现明确长期偏好:
  - .sopify-skills/user/feedback.jsonl

上下文读取顺序

1. project.md
2. user/preferences.md
3. blueprint/README.md
4. blueprint/background.md
5. blueprint/design.md
6. blueprint/tasks.md
7. active_plan = current_plan.path + current_plan.files

读取规则：

• 咨询/澄清优先消费 L0/L1，不强制要求 deep blueprint。
• planning / develop 才进入 L2 active plan。
• history/ 不是默认长期上下文，只在 finalize 后查询或人工追溯时读取。

更新规则

L0 索引约束

• blueprint/README.md 只保留 状态 / 维护方式 / 当前目标 / 当前焦点 / 深入阅读入口。
• 不把绝对工作目录、架构正文、正式契约正文写进 blueprint/README.md。
• 若 blueprint/ 根层存在额外长期专题文档，必须在 blueprint/README.md 显式列出入口。

blueprint/tasks.md 边界

• 只保留未完成长期项与明确延后项。
• [x] 已完成项不应继续保留在 blueprint/tasks.md。

必须更新

• project.md：跨任务可复用的技术约定变化。
• blueprint/background.md：长期目标、范围、非目标变化。
• blueprint/design.md：模块/宿主/目录/消费契约变化。
• blueprint/tasks.md：长期未完成项或明确延后项变化。
• user/preferences.md：用户明确声明长期偏好。

不应写入长期知识

• 一次性实现细节。
• 当前 plan 的短期拆解。
• 仅属于本轮任务的临时取舍。
• 已完成任务清单继续滞留在 blueprint/tasks.md。
• history 正文回灌到 blueprint。

knowledge_sync 同步契约

knowledge_sync:
  project: skip|review|required
  background: skip|review|required
  design: skip|review|required
  tasks: skip|review|required

执行要求：

• skip：本轮不要求同步。
• review：finalize 前至少复核。
• required：未更新则 finalize 阻断。

冲突处理

• 代码与文档冲突：以代码现状为准，文档随后修正。
• 当前任务与长期偏好冲突：当前任务明确要求 > user/preferences.md > 默认规则。

输出格式

初始化完成：

[{BRAND_NAME}] 知识库初始化 ✓

创建: {N} 文件
策略: {full/progressive}

---
Changes: {N} files
  - .sopify-skills/project.md
  - .sopify-skills/blueprint/README.md
  - ...

Next: 知识库已就绪

同步完成：

[{BRAND_NAME}] 知识库同步 ✓

更新: {N} 文件

---
Changes: {N} files
  - .sopify-skills/project.md
  - .sopify-skills/blueprint/design.md
  - ...

Next: 文档已更新