diff --git a/.planning/phases/10-docs-restructure/10-14-SUMMARY.md b/.planning/phases/10-docs-restructure/10-14-SUMMARY.md new file mode 100644 index 0000000..6ddda48 --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-14-SUMMARY.md @@ -0,0 +1,131 @@ +--- +phase: 10-docs-restructure +plan: 14 +subsystem: docs +tags: [vitepress, documentation, plugin-system, lifecycle, dependencies, data-engine] + +# Dependency graph +requires: + - phase: 10-docs-restructure + provides: "中级教程的插件基础用法、数据端总览,以及 10-13 的「声明规则、引擎在合适时机执行」模型" +provides: + - "docs/advanced/plugin-system.md(高级 I 第二篇)" +affects: ["10-15", "10-16", "10-17"] + +actuals: + tokens: 3800 + tasks: 2 + commits: 2 + plan_head_before: eb14b4daee24b09d392af12ce75fdbc4758c0239 + +tech-stack: + added: [] + patterns: + - "先讲问题与最小插件,再展开生命周期、依赖排序与失败语义" + - "通用模板单独成节,现有插件只当示例逐段导读" + - "插件 id 与可存档 id 分表对照,强调两套命名" + - "失败语义按源码事实描述:循环依赖 76、缺失依赖 77、重复 id 78" + +key-files: + created: + - docs/advanced/plugin-system.md + modified: [] + +key-decisions: + - "按 CoreState 实际执行顺序讲三个时机:构造期 awake、load() 前 initialize、加载后 afterLoad" + - "排序只承诺「被依赖者先完成」,不把登记顺序写成绝对契约" + - "商店插件作为示例逐段导读,不作为通用模板;模板另立小节" + - "高级 I/II 内容用代码 span 与 HTML 注释占位,不写真实链接" + - "加粗改用 HTML strong,避免 D-52 flanking 问题" + +patterns-established: + - "插件实操:目录形状 + list.ts 注册 + [模板]/[需改] 骨架 + 四项验证" + - "插件互调:优先依赖参数,其次 getDataPlugin 并判空、查 status" + +requirements-completed: [] + +coverage: + - id: D1 + description: "高级 I 第二篇:插件系统(自定义插件、生命周期、依赖排序与失败语义、插件互调、id 稳定性与迁移)" + verification: + - kind: other + ref: "cmd /c \"pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build\" -> build complete, dead link = 0" + status: pass + human_judgment: true + rationale: "文档质量需用户人工审阅(D-46 第 2 阶段),自动化只能验证构建与链接" +--- + +# Phase 10 Plan 14: 插件系统 Summary + +**高级 I 第二篇落地:从最小插件讲到三个生命周期时机、`dependencies` 拓扑排序与阻断语义、插件互调、插件 id 与存档 id 分离,并给出可复制骨架与现有插件逐段导读** + +## Performance + +- **Duration:** ~25 min +- **Started:** 2026-10-20T04:15:00Z +- **Completed:** 2026-10-20T04:42:00Z +- **Tasks:** 2 +- **Files modified:** 1 created + +## Accomplishments + +- 新建 `docs/advanced/plugin-system.md`(单 H1、CRLF、数据端 only),承接 10-13 的声明式模型与中级 `data-plugins.md`。 +- 用 `CoreState` 的真实流程讲清三个时机:构造期同步 `awake`、`load()` 前 `initialize`、加载后 `afterLoad`,并说明两个异步阶段的阻塞效果。 +- 按 `orderPlugins` 的真实返回讲排序与失败语义:`order` / `cyclic` / `missing`,循环依赖(76)与缺失依赖(77)连同下游一起被排除;重复 id 报 78。 +- 区分 `dependencies` 的两种形态(声明是 id 数组、方法参数是插件对象数组),并给出依赖直调与 `getDataPlugin` 两种互调写法。 +- 分表讲清插件 id(`data-shop-plugin`)与可存档 id(`@plugin/shop`)是两套命名,给出四条最小迁移做法。 +- 独立「模板:一个插件的最小骨架」小节(`[模板]` / `[需改]`),示例只用于说明;`DataShopPlugin` 与 `MainDataPlugin` 逐段对照真实源码。 +- 明确「不懂代码优先改内置」,并给出四项可操作的验证步骤。 +- prettier 通过;`pnpm docs:build` 输出 `build complete`,无 dead link。 + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: 编写 plugin-system.md 正文** - `1b92ee4` (docs) +2. **Task 2: 源码核对、格式与构建收口** - `876529b` (docs) + +**Plan metadata:** `docs(10-14): complete plugin-system plan`(本 SUMMARY 的提交) + +## Files Created/Modified + +- `docs/advanced/plugin-system.md` - 插件系统高级教程:最小插件、生命周期、依赖排序、互调、id 稳定性、模板与示例 + +## Decisions Made + +- 排序表述以源码为准:只保证「被依赖者先完成同一阶段」;无依赖关系时按登记顺序扫描,但明确写成不可依赖的契约。 +- `awake` 用「引擎不会等待返回值」解释,避免读者写成 `async awake` 后误以为会被等待。 +- 生命周期状态用 `PluginStatus` 四态表呈现,并说明依赖的状态会随阶段推进。 +- 迁移章节把插件 id 与存档 id 分开:改名插件 id 断依赖链,改存档 id 断旧存档。 +- 在「注册与目录」补充 `entry.ts` 的数组拼装(主插件在前、`dataPlugins` 展开在后),说明日常只改 `list.ts`。 + +## Deviations from Plan + +None - plan executed exactly as written. + +(Task 1 验证阶段的加粗 flanking 自检与 Task 2 的 `entry.ts` 补句,都在对应任务的提交前完成,未产生计划外提交。) + +## Issues Encountered + +- `pnpm exec tsx docs/.vitepress/init.ts` 触发了 workspace 安装并改写了 `pnpm-lock.yaml`(删除已不再引用的 `@user/entry-client` / `@user/entry-data` 链接)。这属于本计划范围外的既有不一致,已用 `git checkout -- pnpm-lock.yaml` 还原,未纳入提交。 + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +- 10-15(可存档内容)可直接引用本篇的「在 `awake` 里注册可存档内容」与插件 id / 存档 id 的区分。 +- 10-16、10-17 可把本篇作为「插件承载钩子与录像行为」的前置。 +- 待用户按 D-46 第 2 阶段做人工审阅。 + +## Self-Check: PASSED + +- `docs/advanced/plugin-system.md` exists. +- `1b92ee4`, `876529b` exist in git history. +- Static gate: `STATIC-OK`; build gate: `GATE-OK` (build complete, dead link = 0). + +--- + +_Phase: 10-docs-restructure_ +_Completed: 2026-10-20_