项目设计与概念整理 (Project Design & Concept Organizer)

1. 简介 (Introduction)

这是一个用于梳理和沉淀项目知识的技能。

在项目开发过程中，我们会自然形成许多设计模式、约定俗成的协议或特定的架构选择。此技能的目标是回顾：从已有的代码和讨论中提炼出这些设计要素，并将其整理为清晰的文档。它帮助我们保持项目概念的一致性，并方便新成员（或未来的自己）理解系统的全貌。

2. 适用场景 (When to Use)

请在以下情况使用本技能：

1. 阶段性梳理: 完成了一个较大的功能模块，需要总结其设计思路时。
2. 模式固化: 发现代码中反复出现某种特定的交互方式（如特定的前后端通信协议），需要将其正式定义时。
3. 补充开发日志: 在记录开发日志（doc-todo-log-loop）后，发现本次更新包含了重要的架构决策，值得单独提取出来时。
4. 理清思路: 当项目变得复杂，需要重新审视整体结构或目录规划时。

3. 操作步骤

第一步：回顾与识别 (Review & Identify)

回顾近期的代码变更、文件结构调整或关键的对话记录。 思考以下问题：

• 我们最近解决了什么核心问题？是用什么思路解决的？
• 代码中是否涌现出了新的“标准做法”或“协议”？
• 目录结构是否有明确的层级划分意图？

第二步：提炼概念 (Extract Concepts)

将具体的实现细节抽象为通用的设计概念。注意，宁缺毋滥，切勿过分抽象或过度提炼。

• 示例: 从一系列“修改了的文件”，提炼出“引入了配置驱动的插件机制”。
• 示例: 从一系列“前端加了某个判断”，提炼出“定义了基于特定标记的流式渲染协议”。

第三步：文档化 (Document)

使用下方的模板，创建或更新项目的设计文档（通常存放在 docs/ 或根目录下，如 ARCHITECTURE.md 或 DESIGN_CONCEPTS.md）。

• 保持语言平实、准确。
• 记录“为什么这么做”以及“如何运作”。

4. 整理模板 (Template)

在整理设计文档时，请参考以下结构。你可以根据实际情况灵活调整。

# [项目/模块名称] 设计理念与架构规范

## 1. 核心理念 (Core Philosophy)
> 简述项目的核心设计原则。不仅仅是“做什么”，更重要的是“为什么这么做”。
*   **原则 1**: [例如：文档驱动开发] - [简短解释]
*   **原则 2**: [例如：UI 与逻辑分离] - [简短解释]

## 2. 关键概念 (Key Concepts)
> 定义项目中特定的术语、模型或隐喻。
*   **[概念名]**: [解释。例如：“Inbox 范式” - 所有输入先进入 Inbox 目录等待分拣。]
*   **[概念名]**: [解释。例如：“Agent 节点” - 图谱中的独立执行单元。]

## 3. 交互协议 (Interaction Protocols)
> 记录前后端交互、组件间通信的特定规则。
*   **协议名称**: [例如：标记流式协议]
    *   **机制**: [描述协议如何工作]
    *   **目的**: [解决了什么问题]

## 4. 架构与目录意图 (Architecture & Directory Intent)
> 解释核心目录或模块的设计意图。
*   `app/core`: [存放核心业务逻辑，不依赖具体 UI]
*   `components/ui`: [纯展示组件，无业务状态]