From d7b348f3a6d09983df9197ac758ed9548d983e9f Mon Sep 17 00:00:00 2001 From: Harvey Zhao Date: Thu, 10 Sep 2026 17:58:40 +0800 Subject: [PATCH] docs(refactor): [DOC-06] authorize dependencies and project scripts --- AGENTS.md | 4 +++ refactor/ai-workflow.md | 1 + ...6-09-10-DOC-06-dependencies-and-scripts.md | 29 +++++++++++++++++++ refactor/changes/TEMPLATE.md | 1 + refactor/decisions.md | 1 + refactor/plan.md | 8 +++-- refactor/progress.md | 4 ++- refactor/quality-contract.md | 2 ++ refactor/tasks.json | 20 ++++++++++++- refactor/toolchain-release.md | 15 ++++++++++ 10 files changed, 80 insertions(+), 5 deletions(-) create mode 100644 refactor/changes/2026-09-10-DOC-06-dependencies-and-scripts.md diff --git a/AGENTS.md b/AGENTS.md index c60215e9c..4056ceda2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,10 @@ The user requires one separate local Git commit for each completed refactor task Include the task ID in the commit subject and include its implementation, tests, documentation, and status updates together. Verify the commit before starting the next task. Do not bundle multiple newly completed tasks or include unrelated work. This does not authorize pushing or publishing. +The user also authorizes installing needed dependencies and adding or improving reasonable +project scripts for the refactor without asking again for routine tooling choices. +Record their purpose and versions, use the appropriate workspace/dependency category, update +the lockfile when applicable, and verify compatibility and reproducible execution. ## Project Summary diff --git a/refactor/ai-workflow.md b/refactor/ai-workflow.md index 9bf4f8a24..0cfd7a349 100644 --- a/refactor/ai-workflow.md +++ b/refactor/ai-workflow.md @@ -14,6 +14,7 @@ AI 用于源码分析、任务拆分、实现、测试和差异审查。现代 - 单次任务尽量只改变一个行为或一个模块。不要同时全量改名、格式化、更新依赖和重写逻辑。 - 用户已授权主动改进不合理的内部设计。任务范围可按发现扩展，但需补充任务、依赖和证据；不因初始清单未列出而忽略问题。 +- 用户已授权自主安装所需依赖和添加合理脚本。按任务需要直接执行常规选择，同步记录目的、版本、正确依赖归属和使用方式，验证兼容与可复现执行；不再逐项请求工具安装确认。 - 不用 any、ts-nocheck、大量类型断言、删除失败测试、批量更新快照或提高超时掩盖缺陷。 - 不擅自收紧公共类型、统一同步/异步接口或删除旧入口/别名。 - 不手改生成产物，使用项目脚本；验证阶段用只读命令。新的计划命令在尚未实现时必须明确标注。 diff --git a/refactor/changes/2026-09-10-DOC-06-dependencies-and-scripts.md b/refactor/changes/2026-09-10-DOC-06-dependencies-and-scripts.md new file mode 100644 index 000000000..1df66a054 --- /dev/null +++ b/refactor/changes/2026-09-10-DOC-06-dependencies-and-scripts.md @@ -0,0 +1,29 @@ +# DOC-06 自主选择依赖与添加脚本 + +- 日期：2026-09-10。 +- 分支：`codex/compatible-modernization`。 +- 基线提交：`570600d2`。 +- 提交主题：`docs(refactor): [DOC-06] authorize dependencies and project scripts`。 +- 关联决策：ADR-015。 + +## 用户要求与交付 + +用户明确允许按重构需要自主安装新依赖、添加合理脚本，并要求持久记录。现在根 AGENTS.md、质量要求、工具链规范、AI 工作流程及变更模板均明确此授权；常规选择不再重复请求确认。 + +记录用途、版本、所属 workspace/依赖类别，按需同步锁文件、CI、文档及验证。新脚本说明输入、输出和修改行为；新的运行依赖继续验证旧接口和产物兼容。执行顺序遵循实际任务，不提前批量安装工具。 + +## 范围与兼容 + +本次仅修改规则文档、任务数据及生成计划表。没有安装新依赖，没有修改 package.json、锁文件或生产脚本，也没有改变用户 API。 + +## 验证 + +- `node refactor/scripts/plan.mjs --write` 与 `--check`：生成同步、192 项任务、22 包覆盖、依赖与本地链接检查。 +- `git diff --check` 和暂存后的 `git diff --cached --check`：格式检查。 +- 提交后核对 `git log -1 --format='%h %s'` 与 `git status --short`。 + +本次为文档任务，未运行生产测试。实际提交通过主题中的 `[DOC-06]` 追溯，不在提交内容中预填自身 SHA。 + +## 后续 + +下一实施任务仍为 BASE-01。需要具体依赖和脚本时由对应 ENG/CORE/PKG/MOD 等任务选型、安装、验证并独立提交。必要时可以单独回退本次规则文档提交。 diff --git a/refactor/changes/TEMPLATE.md b/refactor/changes/TEMPLATE.md index 55a93e8cf..2f123aec7 100644 --- a/refactor/changes/TEMPLATE.md +++ b/refactor/changes/TEMPLATE.md @@ -14,6 +14,7 @@ ## 改动与理由 记录最终方案、内部职责变化、资源所有者、错误/取消/事件语义。必要时解释放弃的备选方案。 +新增依赖或脚本时，记录用途、版本、所属包/依赖类别、命令输入输出与副作用、锁文件和 CI/用户产物影响。 ## 兼容评估 diff --git a/refactor/decisions.md b/refactor/decisions.md index 4370ed080..dd6b71b48 100644 --- a/refactor/decisions.md +++ b/refactor/decisions.md @@ -18,6 +18,7 @@ | ADR-012 | 已拒绝 | 一次性重写核心并同时更换包管理器、bundler、测试框架 | 变量过多，难以定位回归和回退 | | ADR-013 | 采用方向 | 用户授权在旧接口兼容前提下主动改善全部不合理内部设计 | 2026-09-10 明确要求：TS 迁移伴随清晰拆分、充分有效测试、持续文档和 AI 接续能力；任务清单可按证据扩展 | | ADR-014 | 采用方向 | 每完成一个任务立即创建独立本地 commit | 用户明确要求；实现/测试/文档/状态同次提交，主题带任务 ID，核实成功后再开始下一任务；不等同推送授权 | +| ADR-015 | 采用方向 | 自主安装所需依赖并添加合理脚本 | 用户明确授权；按具体任务选型，记录用途/版本/环境/依赖归属，验证旧接口、产物与可复现执行，随任务独立提交 | ## 开始实现前需补齐的决定 diff --git a/refactor/plan.md b/refactor/plan.md index 90d08ac19..ee2a53fe5 100644 --- a/refactor/plan.md +++ b/refactor/plan.md @@ -2,9 +2,9 @@ > 由 tasks.json 生成。请修改数据后运行 `node refactor/scripts/plan.mjs --write`，不要手改本表。 -基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 191 项，范围 22 个包及工作区/示例。 +基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 192 项，范围 22 个包及工作区/示例。 -状态：todo 186 / doing 0 / blocked 0 / done 5 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。 +状态：todo 186 / doing 0 / blocked 0 / done 6 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。 前置依赖是启动条件；验收是完成条件。任务可以继续拆分，但不能复用或悄悄删除旧 ID。 @@ -46,12 +46,13 @@ | DOC-03 | workspace
建立计划、契约、决策和协作记录 | DOC-02 | refactor 文档集与任务数据 | 每包有独立步骤、依赖、交付物和验收条件 | L | done | | DOC-04 | workspace
验证文档完整性与生成表 | DOC-03 | 计划生成校验工具、AGENTS 入口 | 依赖无环、包覆盖、生成同步、文档链接通过 | L | done | | DOC-05 | workspace
建立每任务提交规则并提交文档基线 | DOC-04 | 根指令、质量要求、AI 流程、变更记录与初始文档提交 | 文档与计划检查通过，独立 DOC-05 commit 保存本次交付；提交后核实 SHA 和工作区 | L | done | +| DOC-06 | workspace
记录自主安装依赖与添加脚本授权 | DOC-05 | 根指令、工具链规范、AI 流程、决策及变更记录 | 授权、依赖归属、脚本文档和兼容验证要求明确，计划校验通过并独立提交 DOC-06 | L | done | ## 1 基线 | ID | 范围 / 步骤 | 前置依赖 | 交付物 | 验收条件 | 风险 | 状态 | | --- | --- | --- | --- | --- | --- | --- | -| BASE-01 | workspace
固定消费者发布基线 | DOC-05 | 各包 npm tarball/integrity、源码 SHA、历史支持矩阵 | 区分源码版本与实际已发布版本，最低核心/TS/浏览器支持有证据 | H | todo | +| BASE-01 | workspace
固定消费者发布基线 | DOC-06 | 各包 npm tarball/integrity、源码 SHA、历史支持矩阵 | 区分源码版本与实际已发布版本，最低核心/TS/浏览器支持有证据 | H | todo | | BASE-02 | workspace
捕获公共 API 和属性描述符 | BASE-01 | 构造参数/默认值/静态及实例 API 快照 | 真实发布包反射与旧用户调用可重跑，未验证项明确 | H | todo | | BASE-03 | workspace
捕获事件、异步和生命周期 | BASE-02 | ready/restart/destroy、Promise、切源/插件事件 trace | 成功、失败、重入和多实例有断言，历史缺陷有标记 | H | todo | | BASE-04 | workspace
捕获 DOM、CSS 和官方 demo | BASE-02 | 模板/类名/变量及全部 demo 映射 | 用户样式覆盖、移动端与自定义 controls/setting 用法已记录 | M | todo | @@ -370,3 +371,4 @@ - DOC-03: [记录](progress.md) - DOC-04: [记录](progress.md) - DOC-05: [记录](changes/2026-09-10-DOC-05-task-commits.md) +- DOC-06: [记录](changes/2026-09-10-DOC-06-dependencies-and-scripts.md) diff --git a/refactor/progress.md b/refactor/progress.md index fbf44d7a2..5d4b3278b 100644 --- a/refactor/progress.md +++ b/refactor/progress.md @@ -41,7 +41,9 @@ ## 下一步 -2026-09-10 新增 DOC-05，记录并落实“每完成一项任务立即独立本地 commit”。总任务现为 191 项，DOC-01 至 DOC-05 的规划交付与 186 个待执行任务以 tasks.json 为准。DOC-05 的范围是文档初始化和提交纪律，不包含生产实现；具体检查与提交主题见 changes/2026-09-10-DOC-05-task-commits.md。 +2026-09-10 新增 DOC-06：用户授权自主安装需要的新依赖、添加或改进合理脚本。已写入根指令、质量要求、工具链规范、AI 流程和 ADR-015；没有在这次记录任务中安装依赖或修改生产脚本。任务总数现为 192，6 个规划任务与 186 个待执行任务以 tasks.json 为准。DOC-05 已提交为 `570600d2`；DOC-06 的本地提交通过 Git 主题中的 `[DOC-06]` 追溯。 + +2026-09-10 新增 DOC-05，记录并落实“每完成一项任务立即独立本地 commit”。当时总任务为 191 项。DOC-05 的范围是文档初始化和提交纪律，不包含生产实现；具体检查与提交主题见 changes/2026-09-10-DOC-05-task-commits.md。 2026-09-10 用户补充要求已落实到 quality-contract.md、ADR-013、根 AGENTS.md、AI 工作流程和变更模板：自主改进不合理内部设计、TS 化同时拆清模块、增加风险对应的有效测试，并持续维护包内架构和后续 AI 接续文档。初始任务数量保持 190，可按后续发现扩展；这次更新不代表开始或完成任何生产代码重构。 diff --git a/refactor/quality-contract.md b/refactor/quality-contract.md index 6fa64064c..dd16960df 100644 --- a/refactor/quality-contract.md +++ b/refactor/quality-contract.md @@ -8,6 +8,8 @@ 这项授权允许修复和改进内部实现，包括消除重复逻辑、整理依赖、调整目录、明确异步状态、资源回收和工程流程；不能把改变公开接口、默认产品行为或未经验证的依赖大升级当作内部整理。遇到实际兼容冲突，优先使用兼容门面、旧入口转发或能力 fallback，无法兼容时明确记录取舍。 +用户还明确授权：可以自主选择并安装重构需要的新依赖，新增或改进合理的开发、构建、类型、测试、文档及维护脚本，无需为常规工具选择逐项询问。按实际任务引入，记录用途、版本、所属包和运行环境，并验证旧接口及分发兼容；具体执行规则见 toolchain-release.md。这是依赖和脚本改造授权，不要求提前安装所有可能用到的工具。 + ## 1. TypeScript 与文件拆分 - 迁移覆盖自有生产源码；同时整理职责、依赖和状态归属，不以改扩展名或补类型断言作为完成。 diff --git a/refactor/tasks.json b/refactor/tasks.json index 47ed1f007..70d02539b 100644 --- a/refactor/tasks.json +++ b/refactor/tasks.json @@ -93,6 +93,24 @@ "changes/2026-09-10-DOC-05-task-commits.md" ] }, + { + "id": "DOC-06", + "phase": "0 规划", + "title": "记录自主安装依赖与添加脚本授权", + "scope": [ + "workspace" + ], + "dependsOn": [ + "DOC-05" + ], + "status": "done", + "risk": "L", + "deliverable": "根指令、工具链规范、AI 流程、决策及变更记录", + "acceptance": "授权、依赖归属、脚本文档和兼容验证要求明确，计划校验通过并独立提交 DOC-06", + "evidence": [ + "changes/2026-09-10-DOC-06-dependencies-and-scripts.md" + ] + }, { "id": "BASE-01", "phase": "1 基线", @@ -101,7 +119,7 @@ "workspace" ], "dependsOn": [ - "DOC-05" + "DOC-06" ], "status": "todo", "risk": "H", diff --git a/refactor/toolchain-release.md b/refactor/toolchain-release.md index 65cde9f98..58a628b18 100644 --- a/refactor/toolchain-release.md +++ b/refactor/toolchain-release.md @@ -6,6 +6,21 @@ TypeScript 用于自有源码、检查与声明生成；Vite/Rollup 保留现有 这是项目方向，不是已完成的切换。工具版本必须在 ENG-01 / MOD-01 通过干净环境试点后固定，不能沿用开发机器上偶然存在的传递依赖。 +## 新依赖与脚本的自主选择 + +用户已授权按重构需要安装新依赖、添加及改进合理脚本，常规选择不需要再次确认。此授权覆盖测试、类型检查、声明生成、构建、文档和代码维护工具，以及确有必要的运行依赖。 + +- 以正在解决的问题为依据引入工具；记录用途、选定版本及相对现有方案的收益，避免用途相同的工具长期重复堆积。 +- 区分 devDependencies、dependencies 和 peerDependencies，放入正确 workspace。开发工具不应意外进入消费者浏览器 bundle。 +- 更新 manifest、适用的锁文件、CI 和使用文档；检查干净安装和执行，不能依赖全局安装或偶然存在的传递依赖。 +- 运行依赖需要比较包体积、浏览器/Node/TS 要求、许可和分发影响；必要升级单独记录，继续保持旧用户接口可用。 +- 脚本职责清楚，名称易理解，支持自动化所需的非交互参数和可靠退出码；兼顾本地 Windows 与 CI 环境。 +- 区分只读检查、自动修复、构建生成和发布命令。旧脚本入口已有用户时保留转发或兼容调用。 +- 文档写明脚本输入、输出、是否修改文件、运行环境和示例；复用成熟工具，避免无必要地自建复杂框架。 +- 在对应任务 commit 中一起保存依赖/脚本、测试、锁文件及文档；不因安装了工具就宣称迁移完成。 + +工具选择可以根据证据调整既有计划，在 decisions.md 更新理由。旧 API 和产物能力仍是验收条件；本地工具授权不等同推送或公开发布授权。 + ## TypeScript 1. 根目录管理基础配置，核心、插件、工具、构建脚本、worker/Worklet 各自配置环境。