Files

T

weichen 2c7f55bfe8 Document svc.sh comprehensively and layer its help system

Why:
svc.sh grew into a three-kind service manager with database operations,
but its only documentation was a flat --help wall of text; the user asked
for a complete usage document and a better help experience.

Evidence:
- docs/svc.md: 14-section manual (prerequisites, quick start, concepts
  and directory layout, per-command reference for service/global/db
  commands, deploy sources, database operations handbook, configuration
  layering, registry fields and event types, safety boundaries, exit
  codes, troubleshooting table, recipe index) — every claim cross-checked
  against the implementation from the previous two rounds.
- Help layering: no-args and -h print a one-screen overview; --help
  renders the header comment reorganized into 7 labeled sections; the new
  "help [topic]" command deep-dives eight topics (model, deploy,
  lifecycle, db, dbops, config, examples, safety); usage errors now show
  the short overview plus a pointer to --help / help / docs/svc.md.
  All topics verified to render; unknown topic exits 2.
- No runtime behavior changed: end-to-end db lifecycle regression
  (create → start → backup → status → stop → rm --purge) passes after the
  refactor.
- Makefile help and README's documentation section point to docs/svc.md.

Impact:
Documentation-only plus display-layer changes; command semantics,
exit codes and file formats are untouched. Maintenance note: behavior
changes must now update both --help and docs/svc.md.

Refs: .task/feature-svc-docs-help.md（任务卡=PR 描述）

2026-09-30 14:29:39 +00:00

2.4 KiB

Raw Blame History

feature/svc-docs-help 任务卡

任务主记录：<PR 链接，task-finish 时填写>；状态：进行中；owner：weichen

基线与授权

权威仓：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-System-Dev.git；目标分支：main；R0（initial_base_sha）= 22d14db80c
工作区：/home/weichen/projects/Agent-System-Dev-wt-feature-svc-docs-help（worktree）；分支：feature/svc-docs-help
授权与交付终点：用户要求"详细完整使用文档 + 完善 --help"；终点 = 实现合入 main 并回收工作区。仅新增 docs/svc.md，修改 scripts/svc.sh 帮助层、Makefile 帮助行、README 文档指引。

目标与非目标

目标：

docs/svc.md：完整使用文档（前提/上手/概念布局/四段命令参考/部署来源/配置系统/登记与事件/安全边界/退出码/故障排查/配方索引）。
svc.sh 帮助分层：无参数/-h → 一屏短帮助；--help → 分节完整帮助（重排头部注释）； help [主题] → 8 个主题详解（model deploy lifecycle db dbops config examples safety）；用法错误改走短帮助并指路。
Makefile help 加文档指引；README「文档」节加 svc.md 条目。

非目标：不改任何运行行为/命令语义（帮助与文档纯属展示层）；不翻译英文错误信息；不生成 man page。

同步记录

节点	sync_base_sha	tested_head_sha	checked_at
启动	`22d14db80c`	`22d14db80c`	2026-09-30T14:17:54Z

结果与验证（完成后填写）

结果：docs/svc.md（14 节，与实现逐条对齐）；svc.sh 头部注释重排为 7 个分节（--help 渲染），新增 usage_short() 与 cmd_help()（8 主题 heredoc），main 接线 -h/--help/help 三层， parse_args 未知参数改走短帮助；Makefile/README 指引。无运行行为改动。
验证：bash -n 通过；无参数/-h 短帮助、--help 完整（7 分节 + 文档指路）、help 主题清单、 8 个主题全部渲染、help bogus 退出码 2 并列出可选主题；db 用法错误指向分主题；功能回归（db create→start→backup→status→stop→rm --purge 全链路）通过，runtime 清理干净。
影响与剩余项：帮助文本与实现的双源维护成本（后续改行为须同步 --help 与 docs/svc.md）；未做 man page / shell 补全（可作后续项）。

2.4 KiB Raw Blame History Unescape Escape

feature/svc-docs-help 任务卡

基线与授权

目标与非目标

同步记录

结果与验证（完成后填写）

2.4 KiB

Raw Blame History