@seanyao/roll 4.630.2 → 4.702.2

package/guide/zh/conventions.md

@@ -0,0 +1,96 @@
+# Roll — 约定与 AGENTS.md
+
+Roll 的约定系统让每个 AI Agent 对你的项目有相同的共识——领域模型、编码规范和文档导航。
+
+## AGENTS.md
+
+`AGENTS.md` 是主约定文件，定义：
+
+- **领域模型**：限界上下文、聚合、核心实体
+- **编码规范**：语言惯用法、命名、禁止模式
+- **作用域规则**：Agent 允许修改的文件范围
+- **Where to Look**：关键文档和目录的命名指针
+- **Goal-Driven Execution**：要求 Agent 在行动前定义可验证目标
+
+Roll 在 `roll init` 时写入 `AGENTS.md` 骨架，你来填写项目特有的领域模型和规范。
+
+## Goal-Driven Execution 规则
+
+每个 Agent 在开始工作前必须定义可验证目标：
+
+```
+Verifiable Goal: <一句话，可判断真假>
+Success Criteria: <可衡量的完成标准>
+```
+
+这避免了模糊执行（"重构 auth 模块"），强制 Agent 说清楚"完成"是什么样。Roll 的技能在每个故事开始时强制执行此规则。
+
+## Where to Look
+
+`AGENTS.md` 导航段将概念名映射到文件路径。Roll 2.0 将所有 Roll 接触的内容
+统一收进 `.roll/`，导航也以此为锚点：
+
+```markdown
+## Where to Look
+
+| 概念 | 位置 |
+|------|------|
+| Backlog 索引 | `.roll/backlog.md` |
+| Feature 规格 | `.roll/features/<name>.md` |
+| 领域模型 | `.roll/domain/context-map.md` |
+| 架构决策 | `.roll/decisions/` |
+| 自主层产出（briefs / dream） | `.roll/briefs/`、`.roll/dream/` |
+| 用户指南 | `guide/en/`、`guide/zh/` |
+| 测试辅助函数 | `tests/unit/helpers.bash` |
+```
+
+约定如下：`AGENTS.md` 留在项目根目录（每个 AI 客户端的第一个读取点），它
+指向的一切都在 `.roll/` 之下。根目录保持干净，导航表就是 Agent 唯一需要
+的地图。
+
+`$roll-design` 在新增文档和目录时维护此表。任何进入项目的 Agent 无需扫描整棵树就能导航到权威来源。
+
+## 语言表面政策
+
+Roll 把契约语言和用户可见语言分开：
+
+- Agent 契约、TypeScript 代码、git 元数据、schema 与稳定 key 保持英文。
+- 与 owner 的对话跟随当前任务中 owner 使用的语言。
+- CLI 输出、帮助、文档和 HTML 页面一次只显示一种语言，由 `ROLL_LANG`、
+  `roll config lang`、`roll help --lang` 或系统语言探测决定。
+
+用户文档写进对应 locale 文件：英文放 `guide/en/`，中文放 `guide/zh/`。CLI
+和生成 HTML 需要改 i18n catalog，不要把翻译对写进同一个输出字符串。
+当约定、帮助、文档或生成表面变化时，发版前运行 `roll doctor language`。
+这条政策由 `packages/cli/test/cli-language-surface.test.ts`、
+`packages/cli/test/__snapshots__/cli-language-surface.test.ts.snap` 和
+`packages/cli/test/doctor-language.test.ts` 覆盖。
+
+## 已有代码库：`$roll-onboard` 与 `$roll-doc-audit`
+
+对于尚无 `.roll/` 的已有代码库，入口是 `$roll-onboard`（**graft（嫁接）**
+接入模式）：扫描代码、问一组聚焦的认知 / 范围 / 隐私问题、产出
+`.roll/onboard-plan.yaml` 作为可审阅的契约。审阅通过后执行
+`roll init --apply`，它会打印计划操作检查点并在落盘前等待确认；非交互自动化必须使用
+`roll init --apply --auto` —— 见
+[legacy-onboarding.md](legacy-onboarding.md) 和
+[patterns/](patterns/README.md)。
+
+对于已有 `AGENTS.md` 但文档散落或过期的项目：
+
+```bash
+$roll-doc-audit
+```
+
+`roll-doc-audit` 会核对 README、指南、网站页面、CLI help 与文档是否匹配真实实现。
+需要文档盘点时，它从已有代码推断领域结构，刷新 `Where to Look` 导航表，并标记
+文档缺口（缺少架构文档、未记录的公开 API）供 `$roll-build` 补全。
+
+## 全局约定
+
+`~/.roll/conventions/global/` 中的文件由 `roll setup` 和 `roll sync` 同步到每个 AI 工具的配置目录。修改全局约定后，下次 sync 时自动传播到所有项目。
+
+## 另见
+
+- [project-setup.md](project-setup.md) — `roll init` 创建 AGENTS.md
+- [overview.md](overview.md) — 三层模型（人 / BACKLOG / 自主）

package/guide/zh/dream.md

@@ -0,0 +1,97 @@
+# roll-.dream — 夜间代码健康巡检
+
+`roll-.dream` 是每晚自动运行的代码巡检技能，扫描代码库中的架构摩擦、死代码和技术债。
+它由 launchd 在凌晨 3 点触发（通过 `roll loop on` 安装），
+并将发现的问题以 `REFACTOR-NNN` 条目的形式追加到 BACKLOG.md，等待 loop 执行。
+
+调度触发的是一个自包含的 v3 runner，其心脏是 `roll dream run-once`
+（解析 `roll-.dream` skill 并就地起 agent 扫描的 TS 命令）——与 loop runner 同形，
+不依赖任何 bash 引擎函数。
+
+## Dream 做什么
+
+每晚 dream 完整扫描一次代码库，输出这些结果：
+
+1. **`.roll/dream/YYYY-MM-DD.md`** — 中文详细报告（每晚一个文件）
+2. **BACKLOG.md 条目** — 可操作的 `REFACTOR-NNN` 条目追加到 `## ♻️ Refactor` 表格
+3. **`.roll/dream/structure-scan.json`** — 代码结构发现的确定性 TypeScript/AST 证据
+
+报告覆盖以下方面：
+
+- 死代码和未使用函数，先由 TypeScript Language Service 引用图给出证据
+- 跨模块的重复逻辑，先由规范化 AST fingerprint 给出证据
+- 模块边界违反（一个关注点泄漏到另一个模块）
+- 已上线功能缺少测试
+- 文档覆盖度缺口（缺 EN/ZH 指南、过时引用）
+
+代码结构类发现现在先走确定性 pre-scan：dead export、不可达分支、重复 AST 形状、
+单实现抽象和未文档化 env 变量都会在 agent 运行前写入 `structure-scan.json`。
+agent 消费这份 artifact，不再用 grep 式启发兜底。文档覆盖、新鲜度和存在性漂移
+仍保留在原有 Dream 流程里。
+
+## 如何读 Dream 报告
+
+```bash
+# 查看最近 3 次报告
+ls -lt .roll/dream/ | head -4
+
+# 读取最新报告
+cat .roll/dream/$(ls -1t .roll/dream/ | head -1)
+```
+
+每个报告章节末尾有优先级分类：
+
+- **P0** — 阻碍其他工作，本迭代内处理
+- **P1** — 显著摩擦，2 周内处理
+- **P2** — 低优先级，有空时处理
+
+## REFACTOR 条目生成
+
+发现具体可操作的问题时，dream 向 BACKLOG.md 追加一行：
+
+```markdown
+| REFACTOR-005 | 提取 _for_each_ai_tool() — 4 处重复的迭代逻辑 | 📋 Todo |
+```
+
+Loop 按正常优先级处理这些条目（晚于 FIX-XXX，与 US-XXX 并列）。
+
+Dream **不会**生成 REFACTOR 条目的场景：
+- 修复需要超过 1 天（改为追加为 IDEA）
+- 纯粹的风格偏好问题
+- BACKLOG 中已有对应 US 或 FIX 条目的问题
+
+## 调度配置
+
+Dream 默认在凌晨 3 点运行。推荐用 `roll config dream-time` 改时间——
+一条命令同时写 `loop_dream_hour` 与 `loop_dream_minute` 两个 key：
+
+```bash
+roll config dream-time 03:20   # 同时写 loop_dream_hour + loop_dream_minute
+```
+
+改完时间只写配置；用 `roll loop on` 重挂应用新调度（config 写入不再自动重挂
+launchd —— US-PORT-006）。`roll loop on` 会把 dream plist 和 loop、pr plist 一起安装。
+三个服务统一管理：
+
+```bash
+roll loop on       # 安装 loop + pr + dream
+roll loop off      # 卸载 loop + pr + dream
+roll loop status   # 查看三个服务的状态
+```
+
+## 手动触发
+
+无需等到凌晨 3 点，随时可以手动跑一次 dream 巡检：
+
+```bash
+# v3 原生——与夜间 runner 同一个心脏
+roll dream run-once
+
+# 或在 Claude Code 里直接调用 skill
+$roll-.dream
+```
+
+Dream 每次运行写入当天日期的文件，并追加到 BACKLOG.md。
+同一天运行两次是安全的（只是产生第二次追加，不会覆盖）。
+每次运行也会刷新 `.roll/dream/structure-scan.json`；需要核对代码结构 REFACTOR
+背后的机器证据时，看这份文件。