# 项目文档规范

本文件规定项目文档的**内容与结构**。文档由模型编写，用户阅读与修改。

## 这份文档是什么

记录一个项目**在做什么、做到哪、下一步**。

它不是：
- 代码注释（那属于代码）
- git log（那属于版本控制）
- 会话记录（那属于 DSH 本身）

**它是一个人接手这个项目时，最先该读的那一页。**

## 何时写

- 有实质进展、决定、结论或遗留问题时
- **无事发生就不写。** 不要为了"保持更新"而记录流水账

## 骨架

新建文档时复制此块，再逐项填写：

```markdown
# <项目名>
> 上游：<仓库地址或"无"> ｜ 本地：<主要目录> ｜ 更新：<YYYY-MM-DD>

## 现状
<一到三句话：现在到哪了>

## 关联资产
- <仓库 / issue / PR / 文档 的链接与一句话说明>

## 台账
| 状态 | 日期 | 事项 | 会话 |
|---|---|---|---|
| 跟踪中 | MM-DD | <一句话说明这是什么问题或想法> | @[<标签>](dsh-session:<base64>) |
```

## 规则

### 一、单位是「事项」，不是会话，也不是文件改动

一个 bug 可能跨多轮对话、动多个文件，**在台账里只占一行**。
一行代表「一个独立的问题或想法」从出现到结论的完整过程。

### 二、状态四选一

| 状态 | 含义 |
|---|---|
| `跟踪中` | 正在处理或已知待办 |
| `已完成` | 有结论并已落地 |
| `已挂起` | 暂时停下，将来可能继续 |
| `已放弃` | 明确不做了（**保留原因**，避免将来重复讨论） |

### 三、会话列使用官方深链

格式：`@[<标签>](dsh-session:<base64>)`

标签写人能看懂的名字。没有对应会话时留空。

### 四、不自动分类

台账分组、排序、归档**只由用户决定**。模型只追加与更新行，不重排既有行。

### 五、保留而非删除

- 已完成/已放弃的事项**保留在台账里**，只更新状态——它们是这个项目的记忆
- 只有当一行**完全被另一行取代**时才合并，并在合并处说明

## 何时重写

当本规范发生变化、需要把已有文档迁移到新结构时，读 `REWRITE-FLOW.md`，按它执行。