docs(m3): 补知识接口契约、M3 清单与状态表

- API.md 新增第 5 节：列表/详情/手记/改内容/状态动作/从事项沉淀 + 7xxx 错误码
- ROADMAP 增 M3 全节与 DOD，验收用例补 11–13，明确 3.8 向量索引未跑
- README 状态表：知识已通、pgvector 只有配置
- DEVELOPMENT 补三条 e2e 命令与「先想一条能失败的断言」

2.Design/API.md

@@ -1,4 +1,4 @@
-# 接口约定（M0–M2 已实现）
+# 接口约定（M0–M3 已实现）
 
 > 只写**已经在跑**的接口。写完没验证的东西不进这份文档。
 > 前缀 `/api/v1`。所有响应都是同一个信封，**HTTP 200 不代表业务成功**。
@@ -301,7 +301,95 @@ canceled→ todo            (恢复)
 
 ---
 
-## 5. 健康与版本
+## 5. 知识 `/workspaces/{ws_id}`
+
+### 5.1 `GET /knowledge`
+
+| 参数 | 说明 |
+|---|---|
+| `status` | 可重复；`draft`/`in_review`/`published`/`archived`，不传为全部 |
+| `doc_type` | `note`/`howto`/`faq`/`postmortem`/`decision` |
+| `source_item_id` | 按来源事项筛 |
+| `q` | 标题 / 正文 / 摘要子串 |
+| `limit` | 1–100，默认 30 |
+| `cursor` | 上一页的 `next_cursor` |
+
+返回 `{items, next_cursor, has_more}`。每条是 `item` 字段 + `knowledge` + `source`：
+
+```json
+{
+  "id": "…", "kind": "knowledge", "title": "发票原件必须一起寄",
+  "body_md": "…", "status": "published", "tags": [],
+  "knowledge": {
+    "doc_type": "howto", "summary": "…", "status_hint": "published",
+    "source_kind": "task", "source_item_id": "…", "generated_by": "human",
+    "published_at": "2026-10-28T05:54:44Z", "archived_at": null,
+    "chunk_count": 0, "author_id": "…"
+  },
+  "source": {"id": "…", "kind": "task", "title": "发票原件必须一起寄", "status": "done"}
+}
+```
+
+> `status` 与 `knowledge.status_hint` 是同一件事：前者在 `item` 上（复用事项表），
+> 后者在 `knowledge_doc` 上（列表按知识口径筛时不必回连 `item`）。**两者必须同步**，
+> 状态动作接口会一起写。
+
+### 5.2 `GET /knowledge/{item_id}`
+
+详情，附最近 50 条 `activities`。不存在或跨租户统一 `7001`。
+
+### 5.3 `POST /knowledge` — 手记或指定来源
+
+```json
+{"title": "报销单要贴发票原件", "body_md": "…", "doc_type": "note",
+ "source_item_id": "可选的来源事项 id"}
+```
+
+- 不带 `source_item_id` → `source_kind=manual`（手记），允许没有来源。
+- 带 → 来源必须是同工作区的 `task`/`ticket`，否则 `7005`。
+- 新知识一律 `draft`，不会直接对外可见。
+
+### 5.4 `PATCH /knowledge/{item_id}` — 修改内容
+
+必须带 `version`（乐观锁，冲突 `4009`）。可改 `title`/`body_md`/`summary`/`doc_type`。
+**已发布的不许直接改**（`7003`，先撤回审议或归档），避免"发布后被悄悄改写"。
+
+### 5.5 `POST /knowledge/{item_id}/status` — 状态动作
+
+| action | 允许的前置状态 | 结果 | 谁能做 |
+|---|---|---|---|
+| `submit_review` | draft | in_review | 成员 |
+| `withdraw` | in_review | draft | 成员 |
+| `publish` | draft / in_review | published | owner / admin |
+| `archive` | draft / in_review / published | archived | 成员 |
+| `restore` | archived | draft | 成员 |
+
+非法动作返回 `7003`，`details.allowed_from` 是动作要求的前置状态，`details.allowed_actions`
+是当前状态下还能做什么——前端据此渲染按钮，不用自己维护一份状态机。
+
+**发布要 owner/admin 的理由**：发布等于团队为这条结论背书，不能谁都能推。
+
+### 5.6 `POST /items/{item_id}/knowledge` — 把一件事沉淀成知识
+
+Query：`doc_type`（默认 `postmortem`）。来源可以是任务或工单；工单会带出验收结论。
+返回与 5.2 相同的知识对象；同一来源重复沉淀 → `7002`。
+
+**工单验收通过时，后端会自动调用这条逻辑**（`generated_by=rule`，`doc_type=postmortem`，
+正文开头固定一句"这份草稿由系统根据来源自动整理，请先核对再发布"），所以用户不需要记得点。
+
+### 5.7 知识的错误码
+
+| 码 | HTTP | 含义 |
+|---|---|---|
+| 7001 | 404 | 知识不存在，或不是知识 |
+| 7002 | 409 | 这个来源已经有知识了 |
+| 7003 | 409 | 当前状态不允许这个动作 |
+| 7004 | 403 | 权限不足（如非管理员发布） |
+| 7005 | 409 | 来源事项无效或缺失 |
+
+---
+
+## 6. 健康与版本
 
 | 方法 | 路径 | 说明 |
 |---|---|---|