已开启
docs: 新增用户指南 user-guide.md(5 分钟上手 + 逐命令参考 + Level A–E 速查 + FAQ) #13
LuBo创建于 8月16日
docs: 新增用户指南 user-guide.md(5 分钟上手 + 逐命令参考 + Level A–E 速查 + FAQ) #13
已开启
LuBo创建于 8月16日
LuBo成员
8月16日

背景

仓库此前没有面向使用者的 user guide:README 面向仓库/贡献者,workflow-guide.md 是流程规范,均不含「装完之后第一步敲什么」、逐命令参考和故障排查。本 PR 补上这层。

改动

新增 docs/guide/user-guide.md(456 行),七节:

  1. 这是什么:定位 + mermaid 工作流全景 + 三个高频动作
  2. 环境要求与安装:三平台 + python 3.8+(含无 python 降级预警)
  3. 5 分钟上手:样例看全绿 → init → status → validate 读红(含 rework 路由)→ archive/registry
  4. 命令参考:7 条命令逐条(用途/用法/真实输出/退出码/典型错误,含 --json 的 CI 用法)
  5. Level A–E 速查表 + Level C EDGE_REWORK 回修路由表
  6. Skills 与 CLI 的配合(skill 产出 → CLI 校验 → broken 路由回修闭环)
  7. FAQ/故障排查 8 条

另在 README.md 与 workflow-guide.md 各加一行交叉引用,保持「流程规范」与「操作手册」分工。

质量保证

  • 所有终端输出均为本机真实运行捕获(含无 python fallback、Level B 锚点报错、archive 拒绝路径)
  • 8 个文件引用路径已验证存在;docs/guide/ 不在打包链路,对构建/测试零影响

写作取舍(供 review 关注)

  • archive 一节含「在途变更预告」:按 0.4.0 实际行为写(当前仅 legacy 迁移检查),#10 合入后变硬门禁,用警示块预告避免文档写完即过期
  • 5 分钟上手故意展示「红」:教新手读 broken 边和 -> ohos-xxx rework 路由,比假装一路绿更有用
  • 贴图用代码块 + 1 张 mermaid;PNG 截图留作后续增强(docs/guide/img/ + 相对引用,不动构建链路)

docs-only 变更,未触碰 CHANGELOG(如需随下一版本记一条可 review 时提出)。

likedislike
合并受阻
LLuBo成员
8月16日 修改标题为 “docs: 新增用户指南 user-guide.md(5 分钟上手 + 逐命令参考 + Level A–E 速查 + FAQ)”,原标题为“test”
LLuBo成员
8月16日 修改了pull request 的描述
LLuBo成员
8月17日 推送  1 个提交:fb65428d-docs: review 反馈 — 在途 PR 指向补 #10 编号 + 版本一致性措辞收紧
LuBo成员
8月25日 评论:

#10 已合入 main,其 archive 门禁随后在 !15(关联 #6 方案 A)调整为按 manifest.complexity 分档:simple 档 evidence 可选(存在即严校验),standard/complex/critical 及 complexity 未知(含无 manifest)归档必须三份 Approved Review Evidence。

本 PR user-guide 的 archive 章节(4.5 预告与 4.3 校验输出示例中的「三份 Review Evidence 均 Approved」表述)需要在合入前按分档结果核对更新——描述 simple 档可选、其余档强制,并建议在命令参考中补一句「归档分档读取 manifest.complexity」。可参考 !15 的实现与 CHANGELOG 措辞。

likedislike
LLuBo成员
8月27日 推送  22 个提交:4578a7ac-20 commits from branch oshunter/ohos-sdd:main,bf4439be-Merge branch 'main' into docs/user-guide,df56ee25-docs: user-guide 对齐 #10/#15 合入后行为;修复 archive-shape README 过时口径
LLuBo成员
8月27日 推送  1 个提交:886a602c-docs: user-guide 版本口径对齐 CHANGELOG 0.5.0 Unreleased