weichen
7818dfbe85
ci / test (pull_request) Failing after 1m38s
Why: branches merged into main had left their task cards open; backfill status and archive to prevent bookkeeping debt. Evidence: feature-svc-docs-help.md(PR#63) — merges verified via git log --merges against origin/main. Impact: .task/*.md moved to .task/archive/ with status backfilled; no code or submodule change. Refs: task.sh close (card-autoclose-r1)
47 lines
2.9 KiB
Markdown
47 lines
2.9 KiB
Markdown
# feature/svc-docs-help 任务卡
|
||
|
||
任务主记录：PR #63 https://git-panel.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/63（merge 404079dc98）；状态：已完成（回填）；owner：weichen
|
||
|
||
## 基线与授权
|
||
|
||
- 权威仓：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-System-Dev.git；目标分支：main；R0（initial_base_sha）= 22d14db80c31e4bcfa24411f847018f527b16a01
|
||
- 工作区：/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 文档指引。
|
||
|
||
## 目标与非目标
|
||
|
||
目标：
|
||
1. docs/svc.md：完整使用文档（前提/上手/概念布局/四段命令参考/部署来源/配置系统/登记与
|
||
事件/安全边界/退出码/故障排查/配方索引）。
|
||
2. svc.sh 帮助分层：无参数/-h → 一屏短帮助；--help → 分节完整帮助（重排头部注释）；
|
||
help [主题] → 8 个主题详解（model deploy lifecycle db dbops config examples safety）；
|
||
用法错误改走短帮助并指路。
|
||
3. Makefile help 加文档指引；README「文档」节加 svc.md 条目。
|
||
|
||
非目标：不改任何运行行为/命令语义（帮助与文档纯属展示层）；不翻译英文错误信息；
|
||
不生成 man page。
|
||
|
||
## 同步记录
|
||
|
||
| 节点 | sync_base_sha | tested_head_sha | checked_at |
|
||
|---|---|---|---|
|
||
| 启动 | 22d14db80c31e4bcfa24411f847018f527b16a01 | 22d14db80c31e4bcfa24411f847018f527b16a01 | 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 补全（可作后续项）。
|
||
|
||
## 闭合记录（card-autoclose 回填）
|
||
|
||
- 依据：merge 404079dc98b555705013eaefbb0be9a2aec0129a（PR #63）已包含于 origin/main，分支成果已落盘；本段为合入后回填。
|
||
- 合并主题：Merge pull request 'Document svc.sh comprehensively and layer its help system' (#63) from feature/svc-docs-help into main
|
||
- 归档：随闭合移入 .task/archive/；任务执行期的过程证据见原任务记录与 PR。
|