镜像自地址
https://github.com/lhly/cloud-drive-renamer.git
已同步 2026-10-20 05:37:47 +08:00
1176d08224
新增 OneDrive 个人版适配器、MAIN 桥接、名称校验与冲突检测、目录身份与分页遍历。同步更新三语简介、商店素材、仓库描述及 manifest 域名注册。修复面板键盘冒泡至宿主页面的隔离与工具栏 Escape 作用域。修正 OneDrive 同步结果语义为手动刷新提示， 避免误报同步失败。补全对应单测与浏览器验收脚本。
66 行
7.5 KiB
Markdown
66 行
7.5 KiB
Markdown
# OneDrive 个人版实施方案
|
||
|
||
## 目标与范围
|
||
|
||
为现有扩展增加 OneDrive 个人版“我的文件”普通目录支持：完整文件列表、扩展内选择、规则预览、批量重命名、冲突提示、失败重试、上一批撤销。继续使用网页登录态，不增加独立 OAuth。首版明确排除企业/学校版、共享视图、搜索/最近/照片、个人保管库及远程快捷方式。
|
||
|
||
用户已要求制定方案后交由 Luna 实现，无需额外方案批准。主代理负责协议验证、方案维护、审查及最终验收；Luna 负责业务代码和自动化测试。双方共享工作目录，主代理不同时编辑 Luna 正在实现的代码。
|
||
|
||
## 阶段与交付物
|
||
|
||
1. **协议确认（主代理）**：复用现有浏览器登录会话，确定根目录/子目录读取、文件身份、摘要和重命名调用。写入验证只使用本次创建的专用测试文件，改名后恢复并清理；不改动用户原有文件。确认结果追加至 findings.md 并发送给 Luna。
|
||
2. **平台适配（Luna）**：新增 onedrive adapter、MAIN world 脚本、桥接与必要的类型/纯函数模块。按确认接口实现，未确认的接口不得以猜测冒充已支持。
|
||
3. **集成与平台语义（Luna）**：接入 manifest、Vite、平台检测、content 工厂、后台广播、平台文案及 README。补足名称验证、大小写冲突、目录隔离、分页防循环、会话/摘要失效与 Retry-After 处理；其他平台保持原行为。
|
||
4. **验证与修正（主代理 + Luna）**：Luna 完成针对性单测与 typecheck；主代理审查实际 diff、运行完整构建所包含的 lint/typecheck/coverage，针对发现反馈给 Luna 修复。浏览器检查实际注入与文件读取，能加载扩展时用专用测试文件验证执行和撤销。
|
||
|
||
## 实现约束
|
||
|
||
- 优先复用已有界面与规则引擎，不新增一套 UI。
|
||
- `OneDriveAdapter` 继承基础适配接口；原生 DOM 选中只能作为增强，不能代替 API 全量列表。现有面板直接使用 getAllFiles，可在扩展内选择。
|
||
- 获取页面上下文必须通过 MAIN world 桥接，不能在隔离 content world 直接读取 `_spPageContextInfo`。桥接只暴露需要的非敏感上下文和具体文件操作，避免接受任意跨域 URL。
|
||
- 稳定 ID 必须带站点/列表命名空间，重命名后不失效。目录键需隔离账户、站点、目录；未知视图/目录不能默默回退根目录。
|
||
- 子目录来自当前路由与站点上下文；路径编码只做一层明确解码，并验证站点/文档库边界。不依赖 `data-selection-index` 作为文件 ID。
|
||
- 文件详情从 API 读取，撤销不能依赖当前可见 DOM。远程快捷方式、目录、保管库等不进入可改名文件集合；冲突检查需包含同目录文件夹。
|
||
- 分页跟随服务器 continuation，检查 origin/站点/路径范围并防循环。缺少或格式错误的列表不能当空目录处理。
|
||
- 写入只更新名称，保留文件内容；请求摘要按服务器期限缓存并刷新；使用实际版本条件或明确冲突策略，禁止覆盖其他文件。
|
||
- 新名称检查覆盖空白、非法字符、首尾空格/尾点、保留名、长度/路径限制；OneDrive 大小写冲突归一化只能影响该平台。执行前和预览前尽可能共用验证逻辑。
|
||
- 429/503 遵循 Retry-After 并有有限重试；400/401/403/404/409/412 不进行盲目重复写入。写入超时等结果不明时通过重新读取确认，不能直接重复覆盖。
|
||
- 页面同步优先重新取数/原生刷新；无法可靠更新时准确提示刷新，不伪报成功。
|
||
- 域名仅新增 `https://onedrive.live.com/*`。精确 hostname + 已支持路径判断，登录页与其他 Microsoft 站点不注入平台行为。
|
||
- 不记录 Cookie、摘要、令牌；不新增依赖、提交或推送，除非实现确实需要并有说明。
|
||
|
||
## 自动化验收
|
||
|
||
- 根目录、子目录、路由不支持和账户/目录切换；身份与目录键隔离。
|
||
- 空目录、多页、重复 continuation、非预期域名 continuation、异常响应；目录/保管库/远程项目排除。
|
||
- 单文件重命名、稳定 ID 读取、名称冲突/大小写碰撞、非法名、409/412，批量部分失败与撤销兼容。
|
||
- 摘要有效/过期/刷新失败、401/403、429/503 Retry-After、请求超时与结构化错误跨桥接传递。
|
||
- manifest/content/page-script 构建条目、平台注册与国际化一致性；既有平台回归。
|
||
|
||
## 完成标准
|
||
|
||
交付实现代码、针对性测试、构建产物与验证记录；清楚区分自动化验证、页面 API 实测和实际扩展端到端验证。若浏览器扩展加载受环境限制，保留实现并准确说明该项未验证，不把工具限制描述为功能验收成功。
|
||
|
||
## 协议定稿补充（2026-09-27）
|
||
|
||
浏览器确认采用混合接口：同源 `/_api/v2.0/drive` 读取 DriveItem（显式选择 sharepointIds），通过 `sharepointIds.listItemUniqueId` 映射到 SharePoint `GetFileById(guid)/ListItemAllFields`。先 GET verbose 取得类型及 etag，再 POST MERGE `FileLeafRef`，携带有效摘要与 If-Match。该路径已对专用新建文件验证成功并清理。v2.0 PATCH 实测403，不用于本实现。
|
||
|
||
## 已完成的协议验收
|
||
|
||
- 当前网页登录态的 v2 根目录、子目录路径解析、文件详情和 continuation 读取均返回200。
|
||
- 首次v2上传/重命名均403；已改用SP写入并明确记录，未通过无权限路径反复重试。
|
||
- 两个随机命名专用测试文件均由本次创建，SP重命名成功，第二个完成改回原名；v2读取确认ID稳定与名称一致。两个测试文件均清理成功。
|
||
- 原生子目录URL为 `/my?id=<server-relative-path>&viewid=...`。
|
||
- 本机Edge独立临时profile可加载dist扩展。实现完成后运行同源fixture界面验收，和已登录页面上的实际桥接代码验证。
|
||
|
||
## 实现与验收结果
|
||
|
||
- Luna完成OneDrive adapter、模型、专用MAIN桥接、平台接线、名称/冲突/重试策略及相关单测。主代理复核并反馈修正了原对象变更影响撤销、SP字段显式选择、etag位置、目录竞态及整体请求截止时间等问题。
|
||
- `pnpm run build`：通过；48个测试文件、389项测试全通过；typecheck及Vite通过。完整build日志保存在本机 `/tmp/cdr-onedrive-build.log`。
|
||
- 真实登录页面上的实际adapter+MAIN脚本：列举文件、重命名专用文件、按原ID获取详情、撤销恢复全部通过，原始FileItem对象保持不变；测试文件清理成功。采用临时bundle注入验证，未在用户浏览器安装或重载扩展。
|
||
- 实际打包扩展在隔离Edge profile中验证：MAIN脚本注入、两页2个文件、前缀批量改名、撤销共4次写入，0页面异常。该测试使用模拟OneDrive页面/API，不消耗真实账户数据；脚本已保存到 `scripts/verify-onedrive-extension.cjs`，使用 `pnpm run verify:onedrive` 可复跑；最终脚本复跑通过。
|
||
- 首版原生OneDrive列表同步采用准确提示刷新；扩展内执行结果正常更新。仍不支持企业/学校版、共享/搜索/最近/照片/保管库等特殊视图，也不承诺导入网页原生选中状态。
|
||
|
||
## 同步提示修正
|
||
OneDrive原生列表仍需手动刷新。适配器通过明确的`manual-refresh`结果通知界面，界面显示本地化普通提示（`refresh-required`），不再将能力限制呈现为红色同步失败或提供无效的重新同步按钮。真正的同步失败仍保留错误及重试入口。
|