qa-versioning

技能文档

---
name: qa-versioning
description: 问答版本管理（问题序列）。依托 Git 对一组问答做版本管理：每题一 commit、按题回滚开新分支、改答案改变版本走向、下游答案自动改写、版本树/diff/导出。触发词：问答版本管理、问题序列、回滚到第N题、改第N题答案、版本走向、问答版本、决策链重算。支持 AI 驱动问答（模式一）与接管已有问答文档（模式二）。
---

# 问答版本管理（QA Versioning，即问题序列）

把一组"问题 + 回答"纳入 Git 版本管理。每个序列是 `~\question-sequences\<序列名>\`
下的独立 Git 仓库，正文在 `sequence.md`。确定性操作全部走脚本，你只负责判断与内容。

## 脚本调用

```
python <本技能目录>/scripts/qseq.py <子命令> --seq <序列名> [参数]
```

若终端出现中文/框线乱码，先执行 `chcp 65001`（或设置 `PYTHONIOENCODING=utf-8`）再调用。

序列默认存放在 `~\question-sequences\` 下；环境变量 `QSEQ_ROOT` 可覆盖该根目录
（很少需要，一般不用设）。

| 子命令 | 用途 | 关键参数 |
|---|---|---|
| init | 创建序列 | `--title` |
| answer | 回答/重答第 N 题（rev 自动递增） | `--q` `--question`(新序列首题必填；rev 分支重答可省略，自动从历史找回题干) `--text`(或 stdin) `--source ai\|human` `--summary` |
| rollback | 回滚到第 N 题之前并开新分支 | `--at-q` `--slug`(从新答案提炼关键词) |
| tree | ASCII 版本树 | `--all-branches` |
| diff | 两分支逐题对比 | `--from` `--to` |
| export | 导出报告 | `--format md\|pdf` `--branch` |
| list | 列出所有序列 | — |

## 模式一：AI 驱动问答会话

1. 与用户确认序列标题与名字（目录名，用拼音/英文短词）；
2. `init` 建序列；
3. **一次只问一题**；用户作答后 `answer --source human`，用户授权你代答则
   `answer --source ai`；题干用 `--question` 原文记录；
4. 答案必须是单行：长答案先压缩，换行用中文分号"；"衔接；
5. 全部答完 → 输出总结 + `tree` 展示版本树（默认含 main 与所有 rev/* 分支）。

## 模式二：接管已有问答文档

1. 读用户文档，解析为逐题问答；信息缺口（如缺标题）补默认值并告知用户；
2. `init` + 逐题 `answer --source human` 重放为初始 commit 链；
3. 之后与模式一完全合流。

## 回滚与改变版本走向（核心）

用户说"回到第 3 题重选 / 如果第 3 题换个答案"→

1. `rollback --at-q <n> --slug <从新答案提炼的短英文或拼音关键词>`；
2. 在新分支上 `answer --q <n>` 写入新答案；
3. 执行下游处理（见下节）；
4. 原分支保留，可 `diff --from main --to <新分支>` 给用户讲两条走向的分歧点。

## 下游改写机制

先理解 rollback 基线：新分支取自「第 N 题首次回答之前」的提交，因此 rollback
后的新分支工作区里没有 Q<n> 及其下游题块——这是正常状态，不是数据丢失。
改完第 N 题后，从原分支读取 `## Q<N>` 之后的所有题块做判断（只读历史是允许的，
例如 `git -C <序列目录> show main:sequence.md`；"边界"规则只禁止手工 git 命令
**修改**序列仓库），逐题判断下游旧答案与新答案是否自洽；对不自洽的题在当前
（rev）分支重新 `answer`——题干缺失时脚本自动从历史找回，无需 `--question`：

- **不自洽** → 重写该题 answer（单行压缩），用 `answer --q <m> --summary "因 Q<N> 变更改写：<要点>"`
  提交——摘要写入 commit 消息留痕；逐题一 commit；
- **全部自洽** → 明确告知"下游无影响"，什么都不做；
- **用户要求重走** → rev 分支上下游题块因 rollback 基线天然不存在，无需清空；
  若用户在不改走向（不 rollback）的当前分支上重答且要求下游作废，脚本没有
  清空题块的子命令——直接告知用户并逐题重新提问（模式一流程从 Q<N+1> 继续），
  不要用占位文本调 `answer`（会虚增 rev）。

改写后向用户口头展示改动清单（题号 / 原题 / 旧答案 → 新答案），单题可返工
（再次 `answer` 同题，rev 自动 +1）。

注：序列文件里的 `rewritten_reason` 字段由历史数据保留展示用，当前 `answer`
命令不写入该字段；改写留痕以 `--summary` 的 commit 消息为准。

## diff 解读职责

脚本输出的逐题差异表是原料；你要把它讲成结论，例如：
"两条走向在 Q2 分岔：main 走 Docker（部署快但本地调试重），
rev/q2-local 走本地环境（调试轻，Q3 的 CI 方案因此整体改写）"。

## 错误翻译

脚本失败即非 0 退出、stderr 给出中文错误行（"建议"细节行可能是原始 git 英文
输出，转述时翻译大意）。把 stderr 关键信息转述给用户并按
"建议"行行动；常见映射：脏工作区 → 问用户是否提交/丢弃未保存改动；
序列不存在 → `list` 列出让用户选；找不到 q<n> → 该分支没答过这题，列出实际题号；
pandoc 缺失 → export 自动降级为 md 并提示，不要向用户承诺 PDF。

## 边界

- 永不删除分支；永不改用户全局 git config；
- 回滚取「第 N 题首次回答之前」为基线；若历史上存在乱序答题（大题号先答），
  rev 分支可能保留更早的大题号题块，属已知边角；
- 所有 Git 细节（commit 格式、分支命名、rev 递增）由脚本负责，不要手工执行 git 命令改序列仓库。

使用说明

# 问答版本管理（qa-versioning）

把一组"问题 + 回答"纳入 Git 版本管理，让问答过程像代码一样可以回滚、分叉、对比。

## 核心能力

- **每题一 commit**：序列存放在 `~\question-sequences\<序列名>\` 下的独立 Git 仓库，问答逐题留痕
- **按题回滚开新分支**：`rollback --at-q N` 回到第 N 题之前，自动创建 `rev/` 分支
- **改答案改变版本走向**：在新分支重答第 N 题，原分支保留，两条走向并存
- **下游答案自动改写**：修改第 N 题后逐题判断下游是否自洽，不自洽的自动重写并在 commit 摘要留痕
- **版本树 / diff / 导出**：ASCII 版本树、两分支逐题对比报告、导出 md/pdf

## 两种使用模式

| 模式 | 场景 |
|---|---|
| 模式一：AI 驱动问答 | 与 AI 进行结构化问答会话，一次一题，随时回滚重选 |
| 模式二：接管已有文档 | 把已有的问答文档解析重放为初始 commit 链，之后合流 |

## 快速开始

安装后直接对 AI 说：

- "帮我建一个问答序列，主题是 XXX"
- "回滚到第 3 题，我换个答案"
- "看看版本树" / "对比 main 和 rev 分支的差异"

所有确定性操作由 `scripts/qseq.py` 脚本完成（init / answer / rollback / tree / diff / export / list），AI 只负责判断与内容。

## 触发词

问答版本管理、问题序列、回滚到第N题、改第N题答案、版本走向、问答版本、决策链重算

## 安装

```bash
skillpie install qa-versioning

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。