126 lines
3.6 KiB
Markdown
126 lines
3.6 KiB
Markdown
# 知识项目目录结构
|
||
|
||
## 目录结构
|
||
|
||
每个知识项目是当前工作目录（CWD）下的一个子目录，包含以下固定结构：
|
||
|
||
```
|
||
<project-name>/
|
||
├── project.md # 高度摘要 + 文件索引
|
||
├── manifest.json # 增量追踪
|
||
├── parsed/ # 解析后的 markdown（中间产物）
|
||
├── sources/ # 待处理区（用户放入原始文档）
|
||
└── archive/ # 原始文件备份（带时间戳）
|
||
```
|
||
|
||
### 各目录/文件职责
|
||
|
||
| 路径 | 职责 |
|
||
|------|------|
|
||
| `project.md` | 项目的高度摘要和文件索引，作为问答时的入口文件 |
|
||
| `manifest.json` | 记录已处理文件的元信息，用于增量检测和版本追踪 |
|
||
| `parsed/` | 存放解析后的 markdown 文件，便于大模型读取分析 |
|
||
| `sources/` | 用户放入待处理文档的目录，解析后文件会被移走 |
|
||
| `archive/` | 原始文件的备份，每个文件都带时间戳后缀 |
|
||
|
||
### 结构完整性验证
|
||
|
||
执行任何 command（ingest / rebuild / ask）时，必须先验证项目目录结构是否完整，即以下 5 项是否全部存在：
|
||
- `<project-name>/project.md`
|
||
- `<project-name>/manifest.json`
|
||
- `<project-name>/parsed/`
|
||
- `<project-name>/sources/`
|
||
- `<project-name>/archive/`
|
||
|
||
若不完整，提示用户先执行 `/lyxy-kb-init <project-name>`，终止当前操作。
|
||
|
||
## 项目名称规则
|
||
|
||
项目名称只允许使用以下字符：
|
||
- 中文字符
|
||
- 英文字母（a-z、A-Z）
|
||
- 数字（0-9）
|
||
- 短横线（-）
|
||
- 下划线（_）
|
||
|
||
**不允许包含空格或其他特殊字符。** 不符合规则时应提示用户修改。
|
||
|
||
## project.md 格式规范
|
||
|
||
```markdown
|
||
# <项目名称>
|
||
|
||
## 概述
|
||
（高度总结的项目信息，几百字以内）
|
||
|
||
## 关键信息
|
||
（从所有文档中提炼的核心要点）
|
||
|
||
## 文件索引
|
||
|
||
| 文件名 | 解析文件 | 最新归档 | 摘要 |
|
||
|--------|----------|----------|------|
|
||
| 需求文档 | parsed/需求文档.md | archive/需求文档_202602181600.docx | 简要摘要... |
|
||
|
||
## 更新记录
|
||
- 2026-02-18 16:00: 解析 需求文档.docx
|
||
```
|
||
|
||
## manifest.json 结构
|
||
|
||
```json
|
||
{
|
||
"project": "<项目名称>",
|
||
"created_at": "2026-02-18T16:00",
|
||
"last_ingest": "2026-02-18T17:25",
|
||
"files": [
|
||
{
|
||
"name": "需求文档",
|
||
"ext": ".docx",
|
||
"parsed": "parsed/需求文档.md",
|
||
"versions": [
|
||
{
|
||
"archived": "archive/需求文档_202602181600.docx",
|
||
"hash": "sha256:abc123...",
|
||
"ingested_at": "2026-02-18T16:00"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `project` | 项目名称 |
|
||
| `created_at` | 项目创建时间 |
|
||
| `last_ingest` | 最近一次 ingest 的时间 |
|
||
| `files[].name` | 文件名（不含扩展名） |
|
||
| `files[].ext` | 原始文件扩展名 |
|
||
| `files[].parsed` | 解析产物的相对路径 |
|
||
| `files[].versions` | 版本历史数组 |
|
||
| `files[].versions[].archived` | 归档文件的相对路径 |
|
||
| `files[].versions[].hash` | 文件内容的 SHA-256 哈希（使用 `sha256sum` 命令计算） |
|
||
| `files[].versions[].ingested_at` | 该版本的入库时间 |
|
||
|
||
## parsed 文件元信息标记
|
||
|
||
每个 parsed markdown 文件头部必须包含元信息注释：
|
||
|
||
```markdown
|
||
<!-- source: 技术方案.pdf -->
|
||
<!-- archived: archive/技术方案_202602181725.pdf -->
|
||
<!-- parsed_at: 2026-02-18 17:25 -->
|
||
|
||
# 技术方案
|
||
（文档正文内容...）
|
||
```
|
||
|
||
| 元信息 | 说明 |
|
||
|--------|------|
|
||
| `source` | 原始文件名（含扩展名） |
|
||
| `archived` | 对应的归档文件相对路径 |
|
||
| `parsed_at` | 解析时间（YYYY-MM-DD HH:mm 格式） |
|