skein-setup — 初始化 / 结构维护
🔒 全局流程规则（状态机/调度/优先级等）以 skein-flow/references/ 为单一真值源。
两用途：① 未初始化仓库 → 建 .skein/ 工作区；② 已初始化 → 手动优化 .skein/ 结构。幂等 — 重跑安全。
触发: 用户显式要求初始化 / 迁移 / 维护 SKEIN 工作区, 或 SessionStart hook 注入「无 .skein/」提示后 main 主动调用。
分流
skein setup # 幂等 scaffold + 输出 manifest JSON
| manifest / 现状 |
用途 |
见 |
无 .skein/ (trellis_present:false) |
① 初始化 — main 直接跑, 纯机械 |
下 §初始化 |
已有 .skein/, spec/ 已是 rules/product/map/external 新结构 |
② 结构维护 — 用户手动优化 |
下 §结构维护 |
已有 .skein/, 检出 spec/core/ (旧两层结构残留) |
② 的前置 — 提示迁移新 namespace 结构, 用户拒绝仍可继续②用旧路径 |
../skein-spec/references/migration-v2.md |
检测到 .trellis/ (trellis_present:true) |
① 的一种场景 — 派 agent 语义迁移 |
references/trellis-migration.md |
① 初始化 (未初始化仓库)
- 新仓 → main 直接跑
skein setup (纯机械, 不派 agent): 建 .skein/ + config + gitignore + 本地 .skein/spec 库 (直接落 rules/product/map/external 四 namespace 目录, 不经过旧两层结构)。完成即可用。
- 既有 trellis 仓 (
.trellis/) → 🛑 检测到 .trellis/ 时 main 用 AskUserQuestion 让用户选迁移模式 (缺省兼容 · STOP, --full 整删不可逆): 兼容 (留 .trellis/ 数据) / --full (整删 .trellis/); 接线 (hooks/scripts/settings) 两模式都删。据选定跑 setup 或 setup --full, 语义迁移 (派 skein-setup agent) 详见 references/trellis-migration.md (目标结构同 §②旧结构检出: 四 namespace)。
旧两层结构检出 (spec/core/ 存在, 独立于 trellis 迁移)
已初始化仓 (.skein/ 已存在) 若检出 spec/core/ 目录 (旧 core/recall 两层, 迁移新 namespace×inclusion 结构前的遗留) → 🛑 main 用 AskUserQuestion 提示「检测到旧两层结构, 是否迁移新 namespace 结构 (rules/product/map/external)」。用户同意 → 走 migration-v2.md 两阶段流程 (阶段 1 机械改名无损, 阶段 2 语义分拣 product/map 无硬性完成线)。用户拒绝 → 旧结构继续可用 (skein-spec 各命令兼容旧路径读取, 新写入统一走新结构), 不阻塞正常使用, 不强迁。
② 结构维护 (已初始化, 用户手动优化)
用户想调整 .skein/ 布局时用。可调项 + 落地方式：
| 想改 |
怎么改 |
收尾 |
| 并发上限 (max_active) |
直接 Edit .skein/config.yaml |
无 |
| spec 类目重组 (类目 = namespace 内子目录, 自由取名 git/test/arch/build/style/domain/ops...) |
移动 / 改名 .skein/spec/<namespace>/<category>/*.md (namespace 自由目录, 默认 rules/product/map/external) |
skein-spec reindex |
调加载策略 (页过重超 spec.always_budget 会告警, 数值见 .skein/config.yaml) |
改规则文件 frontmatter 的 inclusion: (always/auto/fileMatch/manual 四值, 与 namespace 正交), 不要搬文件 — 目录 = namespace(内容类型), 与加载策略无关; 或跑 skein-spec degrade <cat>/<name> 自动改 (always→auto) |
skein-spec reindex |
| 新增一条规则 |
skein-spec sediment --namespace <ns> [--inclusion always|auto] --category <cat> --topic <主题> --title <T> |
追加为主题文件章节 + 自动 reindex |
- 改 spec 盘后必
reindex — 索引 (三份 index.md) 落后于实际盘面 = 召回失效。
- task.json / task.md 禁手改 — 经
skein task create/confirm/... 命令维护, PreToolUse hook 硬阻直接写。
铁律 (通用)
- 幂等 — 已初始化重跑不覆盖 (config/spec 存在则跳过);
.skein/spec 已存在则不重复拷贝。
- spec 盘面变更后 reindex — 手动重组 / 迁移后同步索引。
- task 状态经脚本 — 不直接编辑
.skein/task*。
✅ 正向配方 (命中反面=流程错误)
🔒 铁律: 幂等可重跑; task.json/task.md 经脚本不经手改 (PreToolUse hook 硬阻)。
| 场景 |
正确做法 (❌ 反面) |
改 .skein/task* |
经 skein task create/confirm/... 命令改 (❌ 手改绕脚本 → PreToolUse hook 硬阻 + 破坏索引一致性) |
| 改 spec 盘面后 |
必跑 skein-spec reindex (❌ 不 reindex → 三份 index.md 落后盘面 = 召回失效) |
检测到 .trellis/ |
先 AskUserQuestion 选兼容 / --full 再迁移 (❌ 直接 setup --full → 未问用户整删可能丢数据) |
| 已初始化仓重跑 |
正常重跑, config/spec 存在则跳过 (❌ 当报错 → setup 幂等, 重跑安全不覆盖) |
| 规则归类 |
默认 namespace=rules + inclusion=auto, inclusion=always 只留命令式硬契约 (❌ 什么都堆进 always 常驻 → 超预算告警, 稀释硬约束) |
检出 spec/core/ 旧结构 |
AskUserQuestion 征同意再走 migration-v2 两阶段迁移 (❌ 不问用户直接批量改路径, 或放任旧结构不提示) |
失败模式 (if-then 三段式: 触发 → 一线修复 → 仍失败兜底)
| 触发 |
一线修复 |
仍失败兜底 |
skein setup 报错 |
读 manifest JSON error 字段定位 (权限 / 路径占用 / 已存在) |
仍失败 → 报用户, 禁手工拼凑 .skein/ |
skein-spec reindex 报错 |
读 stderr 定位 (类目名非法 / 路径) |
仍失败 → 停手报用户, 禁半写坏索引 |
| trellis 迁移中断 |
数据仍在 .trellis/ (兼容模式未删), 重跑迁移 |
仍中断 → 报用户, 禁手工拼凑 .skein/ |
1---2name: skein-setup3description: SKEIN 工作区初始化 + 结构维护。未初始化仓库 (无 .skein/ 或 SessionStart 提示) 一键 scaffold; 已初始化时按需手动优化 .skein 结构 (spec 类目重组 / 调规则 inclusion 加载策略 / config 调参), 改盘后 reindex。既有 trellis 仓迁移见 references/trellis-migration.md。幂等可重跑。4---56# skein-setup — 初始化 / 结构维护78> 🔒 全局流程规则（状态机/调度/优先级等）以 skein-flow/references/ 为单一真值源。910两用途：**① 未初始化仓库 → 建 `.skein/` 工作区**；**② 已初始化 → 手动优化 `.skein/` 结构**。**幂等** — 重跑安全。1112> 触发: 用户显式要求初始化 / 迁移 / 维护 SKEIN 工作区, 或 SessionStart hook 注入「无 `.skein/`」提示后 main 主动调用。1314## 分流1516```bash17skein setup # 幂等 scaffold + 输出 manifest JSON18```1920| manifest / 现状 | 用途 | 见 |21|---|---|---|22| 无 `.skein/` (`trellis_present:false`) | **① 初始化** — main 直接跑, 纯机械 | 下 §初始化 |23| 已有 `.skein/`, `spec/` 已是 `rules/product/map/external` 新结构 | **② 结构维护** — 用户手动优化 | 下 §结构维护 |24| 已有 `.skein/`, 检出 `spec/core/` (旧两层结构残留) | **② 的前置** — 提示迁移新 namespace 结构, 用户拒绝仍可继续②用旧路径 | `../skein-spec/references/migration-v2.md` |25| 检测到 `.trellis/` (`trellis_present:true`) | ① 的一种场景 — 派 agent 语义迁移 | `references/trellis-migration.md` |2627## ① 初始化 (未初始化仓库)28291. **新仓** → main 直接跑 `skein setup` (纯机械, 不派 agent): 建 `.skein/` + config + gitignore + 本地 `.skein/spec` 库 (直接落 `rules/product/map/external` 四 namespace 目录, 不经过旧两层结构)。完成即可用。302. **既有 trellis 仓 (`.trellis/`)** → 🛑 检测到 `.trellis/` 时 main 用 `AskUserQuestion` 让用户选迁移模式 (缺省兼容 · STOP, `--full` 整删不可逆): 兼容 (留 `.trellis/` 数据) / `--full` (整删 `.trellis/`); 接线 (hooks/scripts/settings) 两模式都删。据选定跑 `setup` 或 `setup --full`, 语义迁移 (派 skein-setup agent) 详见 `references/trellis-migration.md` (目标结构同 §②旧结构检出: 四 namespace)。3132## 旧两层结构检出 (`spec/core/` 存在, 独立于 trellis 迁移)3334已初始化仓 (`.skein/` 已存在) 若检出 `spec/core/` 目录 (旧 core/recall 两层, 迁移新 namespace×inclusion 结构前的遗留) → 🛑 main 用 `AskUserQuestion` 提示「检测到旧两层结构, 是否迁移新 namespace 结构 (rules/product/map/external)」。用户同意 → 走 [migration-v2.md](../skein-spec/references/migration-v2.md) 两阶段流程 (阶段 1 机械改名无损, 阶段 2 语义分拣 product/map 无硬性完成线)。用户拒绝 → 旧结构继续可用 (`skein-spec` 各命令兼容旧路径读取, 新写入统一走新结构), 不阻塞正常使用, 不强迁。3536## ② 结构维护 (已初始化, 用户手动优化)3738用户想调整 `.skein/` 布局时用。可调项 + 落地方式：3940| 想改 | 怎么改 | 收尾 |41|---|---|---|42| 并发上限 (max_active) | 直接 Edit `.skein/config.yaml` | 无 |43| spec 类目重组 (类目 = namespace 内子目录, 自由取名 git/test/arch/build/style/domain/ops...) | 移动 / 改名 `.skein/spec/<namespace>/<category>/*.md` (`namespace` 自由目录, 默认 `rules/product/map/external`) | `skein-spec reindex` |44| 调加载策略 (页过重超 `spec.always_budget` 会告警, 数值见 `.skein/config.yaml`) | 改规则文件 frontmatter 的 `inclusion:` (`always`/`auto`/`fileMatch`/`manual` 四值, 与 namespace 正交), **不要搬文件** — 目录 = namespace(内容类型), 与加载策略无关; 或跑 `skein-spec degrade <cat>/<name>` 自动改 (`always`→`auto`) | `skein-spec reindex` |45| 新增一条规则 | `skein-spec sediment --namespace <ns> [--inclusion always\|auto] --category <cat> --topic <主题> --title <T>` | 追加为主题文件章节 + 自动 reindex |4647- **改 spec 盘后必 `reindex`** — 索引 (三份 index.md) 落后于实际盘面 = 召回失效。48- **task.json / task.md 禁手改** — 经 `skein task create/confirm/...` 命令维护, PreToolUse hook 硬阻直接写。4950## 铁律 (通用)5152- **幂等** — 已初始化重跑不覆盖 (config/spec 存在则跳过); `.skein/spec` 已存在则不重复拷贝。53- **spec 盘面变更后 reindex** — 手动重组 / 迁移后同步索引。54- **task 状态经脚本** — 不直接编辑 `.skein/task*`。5556## ✅ 正向配方 (命中反面=流程错误)5758> 🔒 铁律: 幂等可重跑; task.json/task.md 经脚本不经手改 (PreToolUse hook 硬阻)。5960| 场景 | 正确做法 (❌ 反面) |61|---|---|62| 改 `.skein/task*` | 经 `skein task create/confirm/...` 命令改 (❌ 手改绕脚本 → PreToolUse hook 硬阻 + 破坏索引一致性) |63| 改 spec 盘面后 | 必跑 `skein-spec reindex` (❌ 不 reindex → 三份 index.md 落后盘面 = 召回失效) |64| 检测到 `.trellis/` | 先 `AskUserQuestion` 选兼容 / `--full` 再迁移 (❌ 直接 `setup --full` → 未问用户整删可能丢数据) |65| 已初始化仓重跑 | 正常重跑, config/spec 存在则跳过 (❌ 当报错 → setup 幂等, 重跑安全不覆盖) |66| 规则归类 | 默认 `namespace=rules` + `inclusion=auto`, `inclusion=always` 只留命令式硬契约 (❌ 什么都堆进 always 常驻 → 超预算告警, 稀释硬约束) |67| 检出 `spec/core/` 旧结构 | `AskUserQuestion` 征同意再走 migration-v2 两阶段迁移 (❌ 不问用户直接批量改路径, 或放任旧结构不提示) |6869## 失败模式 (if-then 三段式: 触发 → 一线修复 → 仍失败兜底)7071| 触发 | 一线修复 | 仍失败兜底 |72|---|---|---|73| `skein setup` 报错 | 读 manifest JSON `error` 字段定位 (权限 / 路径占用 / 已存在) | 仍失败 → 报用户, 禁手工拼凑 `.skein/` |74| `skein-spec reindex` 报错 | 读 stderr 定位 (类目名非法 / 路径) | 仍失败 → 停手报用户, 禁半写坏索引 |75| trellis 迁移中断 | 数据仍在 `.trellis/` (兼容模式未删), 重跑迁移 | 仍中断 → 报用户, 禁手工拼凑 `.skein/` |
lazygophers