Appearance
方舟项目 (The Ark) 构建方案
核心哲学：文档即代码 (Documentation as Code) 知识库不是零散笔记的堆砌，而是一个需要工程化维护的系统。文档应当像代码一样拥有清晰的结构、严格的规范、版本化的管理以及自动化的流转管线。
一、 命名与愿景 (Vision)
- 项目名称：方舟项目 (The Ark)
- 核心定位：全栈开发者的第二大脑 (Second Brain)
- 愿景：打造一个低摩擦、高产出、对 AI 极其友好的数字资产管线。不仅是给现在的自己看，更是为未来的 AI 助手提供高质量的长期记忆（Long-term Memory）。
二、 核心架构原则 (Core Principles)
| 原则 | 描述 | 实施手段 |
|---|---|---|
| 文档即代码 | 文档是项目的一等公民，需严谨维护。 | 建立 docs/ 专用目录，存放规范 (rules) 与架构说明。 |
| 功能化归类 | 摆脱以工具为中心的分类，转向以功能/领域为中心。 | 将 docker 归入 container，git 归入 version-control。 |
| 渐进式提炼 | 知识遵循 Inbox → Note → Knowledge 的流转路径。 | inbox 快速记录，note 提炼草稿，knowledge 沉淀成品。 |
| AI 协同 | 所有文档必须结构化，以便 AI 检索与处理。 | 强制 YAML Front Matter，统一中文命名规范。 |
三、 目录结构设计 (Standard Structure)
基于「方舟」的核心设计，项目目录结构如下：
text
ark/
├── docs/ # [专用文档] 项目自身的元数据与规范 (文档即代码)
│ ├── rules/ # 落地规范 (Documentation Standard)
│ └── architecture/ # 架构设计方案 (本文件所在位置)
├── knowledge/ # [成品区] 经提炼、面向发布的 Wiki 内容
│ ├── architecture/ # 架构与模式
│ ├── backend/ # 后端技术栈
│ ├── tools/ # 工具箱 (按功能分类)
│ └── ...
├── inbox/ # [收集区] 原始想法与未经排版的素材
├── assets/ # [资源层] 图片、PDF 等附件的 SSOT 存放点
└── .trae/ # [AI 配置] Trae 智能体的局部规则与记忆四、 "AI-First" 文档规范
每一份文档都必须是 AI 可理解的资产：
- YAML Front Matter：必须包含
title,category,tags,summary。 - 中文命名：2026-09 新规要求文件名使用 5-10 字中文，避免 UI 换行，增强直观感。
- 结构化 H 标签：合理使用 H1-H3，确保目录导航清晰。
- 代码块增强：所有代码必须标注语言，并提供核心逻辑的中文注释。
五、 演进路线图 (Roadmap)
第一阶段：结构化重整 (Done)
- [x] 建立
docs/目录，将rules升级为项目核心组件。 - [x] 确立功能化分类体系，重构
tools目录。
第二阶段：自动化赋能 (In Progress)
- [ ] 开发
orchard自动化脚本，自动生成目录索引与 Front Matter 校验。 - [ ] 构建 AI 知识园丁 (Knowledge Gardener) 技能。
第三阶段：全栈覆盖 (Future)
- [ ] 逐步将
inbox中的历史碎片按功能分类提炼入knowledge。 - [ ] 实现 VitePress 站点的全自动 CI/CD 发布。
六、 维护准则
“如果不维护，知识就会腐烂。”
- 定期审计：每月清理一次
_archive，更新index.md。 - 低摩擦：如果一条规则让人不想写文档，那就优化规则，而不是惩罚自己。
- 未来导向：每一行字都要考虑：一年后的自己或 AI 能不能快速看懂？