vision

/vision

你正在运行 vision 技能。请编写一份作者可以审核通过的 VISION.md：以项目实际构建的内容为依据，为项目未来制定验收政策，并通过作者在交互式审核板上回答的假设问题加以完善。

VISION.md 是唯一提交的对齐依据。即使审核者从未看过审核板，也必须能够仅凭它决定接受还是抵制一项变更。

这不是写作练习。请从头到尾遵循本文件。

宿主环境要求

你需要能够读取目标仓库及其真实历史：

• 优先通过 GitHub 类 CLI（gh、gh-axi）读取已合并的 PR 历史。
• 如果无法访问 PR，则回退到默认分支上的 git 提交历史（git log）：标题和消息仍能体现作者构建的内容。
• 只有完全无法读取任何真实历史时，才停止并说明原因。绝不捏造作者的价值观、PR 标题或证据。基于虚构证据构建的愿景比没有愿景更糟。

审核循环通过 lavish-axi 运行，直接使用 npx -y lavish-axi 执行 - 无需安装。直接尝试启动，只有启动本身失败时才报告阻碍。

硬性规则

1. 证据胜于空谈。 草案中的每条原则都必须能追溯到具体证据：具名 PR 或提交、文件、文档，或作者认可并纳入 VISION.md 的推理。除非历史记录能具体证明，否则禁止使用通用的工程美德（例如“我们重视质量”）。
2. 先检查是否已有 VISION.md。 如果默认分支上存在该文件，则切换到增量模式：将其视为已批准的基线，根据更新的证据提出逐行候选修改，绝不编写与之竞争的文档。
3. 愿景由作者决定。 你负责起草、检验，并根据作者的裁定进行调整；你绝不替作者批准，绝不为了迎合而弱化假设，也绝不纳入作者未陈述或未展现的原则。
4. 愿景是一项验收政策。 使用陈述式现在时编写可检验的接受／抵制标准，并明确列出非目标，确保未来的读者（无论是人还是 Agent）仅凭 VISION.md 就能评估具体变更。
5. 不要提出轻而易举的假设题。 每道题都必须立足于真正的分歧点，且支持“是”和“否”的理由都站得住脚。若你能预测作者的答案，就换一道题。
6. 审核循环必须通过 lavish-axi，使用随附模板。 草案和假设题必须在同一个审核板上呈现，该审核板由 assets/review-template.html + assets/review.css 构建，并原样使用：白纸黑字，采用文学作品的排版风格；完整草案始终全部可见；每次只在卡片堆中呈现一道假设题。填充模板的占位内容；绝不重新设计样式或结构，也绝不使用其他审核界面。
7. 分批迭代，追溯每项编辑。 每项作者裁定都必须对应变更日志中的一条具名编辑；作者必须能清楚看到自己的回答如何改变了文本。
8. 格式要求。 每行一句。使用普通连字符，绝不使用长破折号。不得包含路线图、功能列表或营销话术。
9. VISION.md 是唯一的对齐依据。 无论何种形式最合适，都要将作者的推理融入相关正文。绝不将假设题或审核板记录复制到 VISION.md。绝不在目标仓库中编写、保留或指向答案文件。审核板记录可以保存在工具的临时目录中，但绝不能提交。

流程

第 0 步 - 解析目标和作者

• 目标仓库：默认使用当前工作目录，也可以指定 owner/repo。
• 作者：愿景所属的人；默认使用仓库所有者。其已合并的工作构成证据基础。
• 只有在目标或作者确实存在歧义时，才提出一个简短问题。

步骤 1 - 了解模式

VISION.md 有稳定的结构；草稿应遵循这一结构：

• 身份开篇：“X 的存在是为了……”，说明它服务的对象，以及“它只负责一件事：……”。
• 3-6 个原则章节，标题简短且为陈述句；每节包含一组可检验的现在时承诺与拒绝事项。
• 明确列出非目标，具体说明（“它不是 CI 系统，也不是……”）。
• 以一组测试收尾：“当……时，变更符合原则”和“当……时，应抵制变更”，内容应具体到可用于评估真实 PR。
• 语气：陈述式、现在时、毫无营销意味；篇幅一到两页（40-70 行）。作者的推理应在相关之处融入正文，以最合适的形式呈现；绝不能用问题清单的形式记录。

如果作者点名了范例愿景文档，请阅读并留意其结构、语气和篇幅。

步骤 2 - 检查现有愿景文档

• 如果默认分支中有 VISION.md：采用增量模式（硬性规则 2）。结合历史记录比较其年代，只提出有证据支持、可独立接受的候选增补或修改。
• 如果没有：采用从头编写模式。
• 如果存在 VISION-ANSWERS.md 或任何配套答案文件，请在起草前运行迁移：将缺失的推理融入 VISION.md，删除答案文件，并移除指向它的引用。

步骤 3 - 梳理证据

• 分析代码库：README 中的身份主张、架构、明确声明的非目标、拒绝路径、测试规范。
• 梳理历史：列出作者已合并的 PR，目标为 30-100 个标题，并阅读分布于整个范围的 8-15 个完整 PR 正文（例如运行 gh pr list --author <owner> --state merged --limit 100，或使用 gh-axi 的等效命令）。如果无法访问 PR，则改为查看默认分支的提交历史（git log --author=<owner>），阅读提交消息以寻找相同的信号。
• 提炼反复显现的价值观：会构建什么、会拒绝什么、会从根本上修复哪类缺陷，以及作者在意图声明中写了什么。
• 生成一份私有证据表：价值观 -> 支持它的 PR、提交或文件。这份表是草稿中每一行内容的事实依据。

步骤 4 - 起草

• 遵循步骤 1 的结构和下方的输出模板。
• 每一行都必须对应证据表中的证据。目标篇幅：40-70 行。
• 增量模式则应输出：基线内容保持不变 + 编号列出的候选增补或修改，每项都附上证据。

步骤 5 - 设计假设情境

• 每份愿景文档设计 8-12 个具体的变更提案，针对草稿中的薄弱之处。参考以下类型：
  • 诱人但偏离使命的功能，作者可能会被要求开发；
  • 原则冲突（简单性与能力、安全性与速度、通用性与专注度、成本与质量）；
  • 渐进失控：某个合理步骤会让下一个步骤变得顺理成章；
  • 范围扩张（新用户、新内容类型、新主机、团队）；
  • 草稿未明确说明的身份问题。
• 每个假设情境的格式：编号、标题、具体提案（2-4 句）、测试的原则（引用草稿内容），以及答案为何并非显而易见（公正地论述双方理由）。
• 质量门槛：删除并替换任何答案可以预测的假设情境。

步骤 6 — 评审循环（lavish-axi，使用随附模板）

• 将 assets/review-template.html 和 assets/review.css 复制到工具的临时工作区（而非目标仓库），然后只填写模板中标记的空位：项目名称、运行说明、完整的 DRAFT markdown，以及 CARDS 数组（每张卡片包含 id、标题、提案、经过检验的原则和双方论证）。
• 不要更改其他任何内容：模板已经包含既定结构——左侧显示完整草稿，右侧一次显示一张卡片，完整展示双方论证，并为每张卡片排队一个评判结果——因此无需重写样板内容，也无需重新设计任何一次运行的样式。
• 使用 npx -y lavish-axi <board.html> 启动，报告 URL，然后等待 npx -y lavish-axi poll <board.html>；答案会以排队的评判结果形式送达。
• 每批答案到达后：将作者的推理融入草稿，使 VISION.md 本身足以用于接受／抵制测试。采用最合适的表达方式；不要照抄假设情境、卡片 id 或看板记录。看板 HTML 和轮询日志可以保留在工具的临时工作区；绝不要将答案文件写入目标仓库。原地更新看板（更新草稿文本和剩余卡片），并通过 poll --agent-reply 回复，每个评判结果附一行变更日志（“H-7 不通过 -> 权威性部分现在以……开头”）。
• 持续进行，直到作者批准或结束会话。不要代替作者批准；也不要将沉默视为批准。

步骤 7 — 完成

• 交付：已批准的 VISION.md 文本（或已批准的差异）。该文件就是完整的对齐依据。
• 确认目标仓库中没有 VISION-ANSWERS.md，也没有其他答案文件，且 README 和 AGENTS.md 未指向任何此类文件。
• 不要告诉作者要保留答案文件。变更日志已包含在评审循环回复中；它不是需要提交的产物。

输出模板（从头编写模式）

# 愿景

`{project}` 的存在，是为了{项目存在的单句理由}。
它服务于{指定用户}，并将其输入转化为{转化结果}。
它只负责一件事：{唯一负责的内容}。

## {原则章节，共 3-6 个}

{陈述式、可检验、使用现在时的内容；每行一句。}
{明确的边界：欢迎什么、拒绝什么，以及原因。}

## 范围

{明确指出本项目不是什么。}
{个人／私人材料应存放的位置（如适用）。}
{仓库如何遵守自身标准（如适用）。}

当{可检验的正向标准}时，变更与愿景一致。
当{可检验的负向标准}时，应抵制变更。

起草前检查清单

• 已确认目标仓库和作者
• 已检查现有 VISION.md（已选择模式）
• 已迁移现有 VISION-ANSWERS.md，或确认其不存在
• 已根据真实 PR 或提交构建证据表（未杜撰证据）

作者批准前检查清单

• 每一行草稿均可追溯至证据表，或作者在 VISION.md 中阐明的推理
• 有 8-12 个假设情境，均不可预测，且双方论证充分
• 每条作者评判结果的推理都已反映在草稿中，并在评审回复中附有可追溯的变更日志行
• VISION.md 本身足以用于接受／抵制测试
• 未在目标仓库中写入、保留或引用任何答案文件

迁移（现有的 VISION-ANSWERS.md）

如果目标仓库已有 VISION-ANSWERS.md（或 vision 旁边的任何配套 答案文件或文字记录文件）：

1. 阅读文件。提取作者的推理。舍弃假设、卡片 ID、 结论标签、正反论据和讨论记录。
2. 将 VISION.md 缺少的推理融入正文，采用最合适的表述形式。跳过 已涵盖的内容。合并重叠的回答，不要按问题逐条罗列。
3. 从目标仓库中删除答案文件。
4. 从 AGENTS.md、README 和其他所有已提交的文档中删除指向该文件的链接。

篇幅要求：VISION.md 应保持一到两页（目标为 40-70 行），而不是 一本台账。如果融入内容会让它变成一份问答合集，就进一步提炼。检验 标准是：从未看过讨论记录的审核者，仅凭 VISION.md 就能接受或反对一项具体变更。