Skip to content

[DOCS] Align user guides with implemented CLI, SnapshotDB, and Python API behavior #91

Closed

Description

@codeasier

问题类型

  • 文档内容错误或不准确
  • 文档缺失(缺少某些功能的说明)
  • 文档结构/导航问题
  • 示例代码错误
  • 文档格式问题
  • 需要添加新的文档
  • 其他

受影响的位置

README.md, README_zh.md, docs/README.md, docs/en/*.md, docs/zh/*.md

问题描述

用户文档与当前实现发生了系统性漂移:

  • 入门流程引用仓库中不存在的示例数据库,并使用无效的 --state 查询参数。
  • SnapshotDB 文档中的 SQL 约束、默认值、事件 ID 关系和 dictionary 编码方向与运行时 schema 不一致。
  • focus 隔离、split 切片数量、失败清理和平台要求存在过度承诺。
  • CLI、Python API 和 MCP 返回原始 SQLite 值,但文档展示了自动应用 output_schema 后的值。
  • 文档导航将低层 ResultMapper 错标为 Python API,且缺少高层 SnapshotAnalyzer 指南。
  • 根 README 包含容易漂移的源码树、模板清单和内部维护契约,中英文内容也未完全对齐。

改进建议

  • 以 CLI、Python API、MCP、运行时 schema 和测试为事实来源,逐项校正文档。
  • 保持 docs/en/ 与 docs/zh/ 的行为描述和导航同步。
  • 新增中英文 SnapshotAnalyzer 高层 API 指南,明确 focus、设备优先级、查询结果、metadata 和异常语义。
  • 精简根 README,只保留安装、工作流、命令、文档入口和开发命令。
  • 补全文档索引、语言切换和 AGENTS 导航。
  • 使用 API、治理、AGENTS 和相对链接检查验证修改。

期望的内容

  • 文档中的命令可直接使用当前 CLI 执行。
  • SnapshotDB schema 和生命周期关系与运行时数据库一致。
  • 中英文指南覆盖相同功能并保持语义一致。
  • 高层 Python API 与可选结果映射工具有清晰独立的入口。
  • README 面向用户,维护者契约由 AGENTS.md 承载。

补充信息

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions