DOC-002 编写 README 与技术边界文档 #2

New Issue

wangdl · 2026-05-30T19:48:59+08:00

wangdl commented

2026-05-30 19:48:59 +08:00

该仓库容易被误做成万能文件预览器或 AI/RAG 解析服务。必须先通过文档冻结技术边界。

目标：编写 README 和 docs/ 文档。

已完成：README.md
待做：docs/architecture.md, supported-formats.md, event-protocol.md, reading-position-model.md, ios-integration.md

核心边界：
Rust Core 负责：文件类型识别、Markdown/TXT解析、图片metadata、阅读位置模型、阅读事件协议、搜索、笔记锚点、UniFFI绑定
Rust Core 不负责：网络请求、COS下载、用户登录、Token管理、后端API调用、AI/RAG、向量化、Office高保真预览、OCR、PDF标注

该仓库容易被误做成万能文件预览器或 AI/RAG 解析服务。必须先通过文档冻结技术边界。目标：编写 README 和 docs/ 文档。已完成：README.md 待做：docs/architecture.md, supported-formats.md, event-protocol.md, reading-position-model.md, ios-integration.md 核心边界： Rust Core 负责：文件类型识别、Markdown/TXT解析、图片metadata、阅读位置模型、阅读事件协议、搜索、笔记锚点、UniFFI绑定 Rust Core 不负责：网络请求、COS下载、用户登录、Token管理、后端API调用、AI/RAG、向量化、Office高保真预览、OCR、PDF标注

wangdl added this to the M0：项目初始化与技术边界冻结 milestone 2026-05-30 19:48:59 +08:00

wangdl added the

priority:p0

type:docs

area:architecture

labels 2026-05-30 19:48:59 +08:00

wangdl commented

2026-05-30 20:17:04 +08:00

完成项

✅ README.md 技术边界文档（772 行）
✅ docs/architecture.md 分层架构 + 职责边界 + 数据流 + Crate 拆分
✅ docs/supported-formats.md 格式矩阵（第一版/后续/明确不做）+ 识别策略
✅ docs/event-protocol.md 5 种事件类型 + JSON 示例 + 收集流程 + App 实现要点
✅ docs/reading-position-model.md 跨格式统一位置模型 + 序列化 + 继续阅读流程
✅ docs/ios-integration.md 构建 Rust 库 + Swift binding 生成 + XCFramework + 调用示例 + FAQ
✅ docs/app-rust-bridge.md 调用协议已融入 architecture.md（第 5 节 DOC-005 内容）

待跟进

⬜ 后续实现过程中持续更新文档（如 UniFFI .udl 语法细节、真实构建命令等）

## 完成项 ✅ README.md 技术边界文档（772 行） ✅ docs/architecture.md 分层架构 + 职责边界 + 数据流 + Crate 拆分 ✅ docs/supported-formats.md 格式矩阵（第一版/后续/明确不做）+ 识别策略 ✅ docs/event-protocol.md 5 种事件类型 + JSON 示例 + 收集流程 + App 实现要点 ✅ docs/reading-position-model.md 跨格式统一位置模型 + 序列化 + 继续阅读流程 ✅ docs/ios-integration.md 构建 Rust 库 + Swift binding 生成 + XCFramework + 调用示例 + FAQ ✅ docs/app-rust-bridge.md 调用协议已融入 architecture.md（第 5 节 DOC-005 内容） ## 待跟进 ⬜ 后续实现过程中持续更新文档（如 UniFFI .udl 语法细节、真实构建命令等）

wangdl closed this issue

2026-05-30 20:31:14 +08:00

wangdl commented

2026-06-02 20:14:44 +08:00

审查同步 (2026-06-02)

README 与技术文档已同步当前代码状态：

修正 DocumentBlock 数据模型（Table 补 headers 字段，补 HorizontalRule 变体）
精简依赖推荐为实际使用的 serde/serde_json/uuid，后续按需引入
移除目录结构中引用的不存在文档（note-anchor-model/android-integration/roadmap）
补充 app-rust-bridge.md 到 docs 目录清单
新增 .cargo/config.toml（cargo xtask 别名）

## 审查同步 (2026-06-02) README 与技术文档已同步当前代码状态： - 修正 DocumentBlock 数据模型（Table 补 headers 字段，补 HorizontalRule 变体） - 精简依赖推荐为实际使用的 serde/serde_json/uuid，后续按需引入 - 移除目录结构中引用的不存在文档（note-anchor-model/android-integration/roadmap） - 补充 app-rust-bridge.md 到 docs 目录清单 - 新增 .cargo/config.toml（cargo xtask 别名）

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#2