Skip to content

development.md

Latest commit

 

History

History
105 lines (75 loc) · 7.87 KB

development.md

File metadata and controls

105 lines (75 loc) · 7.87 KB
Raw

开发与文档维护流程

更新：2026-10-29。适用于新增工具、扩展模式、修复行为、修改共享 UI 以及整理文档。协作规则见 AGENTS.md。

本地开发

pnpm install --frozen-lockfile
pnpm dev

Node 版本和包管理器要求见 README。不要无关升级依赖；不要新增 npm/yarn 锁文件。开始修改前查看 git status，保留用户已有变更，并阅读相关实现和参数定义。

命令 用途
pnpm dev 本机开发服务器、热更新；不是离线验收服务器
pnpm docs:check 校验文档本地链接、91 项工具登记、参数和枚举模式覆盖
pnpm typecheck TypeScript 无输出检查
pnpm lint ESLint 逻辑、类型和 Hooks 规则
pnpm format:check 全仓 Prettier 检查；失败需区分本次与既有问题
pnpm test Vitest 全量；可追加测试路径作针对验证
pnpm build TypeScript 检查、Vite 产物、静态工具入口和离线清单
pnpm preview 预览已生成的 dist/，默认端口以终端输出为准

仅格式化相关文件，例如 pnpm exec prettier --write README.md docs/tools.md。pnpm format 会改全仓，不能用于掩盖无关格式问题。

新增一个工具

  1. 先确认边界：能否纯本地完成、是否涉及秘密或文件、结果和错误如何表示、浏览器 API 是否有降级。复用已有能力，避免只换名字的重复入口。
  2. 登记入口：修改 src/tools/metadata.json，提供稳定 id / slug、已有分类、排序、翻译 key、中英文搜索别名及可运行示例。同步工具数相关展示与 src/i18n/i18n.test.ts 的显式数量断言。
  3. 定义参数：在 src/tools/schema.ts 的 fields 增加字段、默认值与枚举。noInputTools / visualTools 只在符合实际交互时添加，不凭名称猜测。
  4. 实现转换：通常接入 src/tools/transform.ts 和已有领域模块；参数校验使用 validateParams。依赖 DOM / Canvas 的流程参考 browser.ts；重 CPU 任务放 Worker，不把任意用户输入作为代码执行。
  5. 接入界面：沿用 ToolPage、Editor、Select 与语义 tokens。下拉框使用自定义 Select 的 value / onValueChange，并提供可访问名称，不另建原生 select。需要文件、辅助输入、二进制下载或预览时显式接入；现有 ToolPage 的工具 ID 集合不是自动推断，必须检查。
  6. 隐私与双语：秘密数据工具加入 src/lib/sensitive-tools.ts，双语资源同时补标题、描述、参数、状态、错误和 aria 文案。普通草稿也不能保存文件。
  7. 验证与文档：添加有价值的算法边界测试、运行必要的浏览器检查；同步下表所列文档，记录真正执行的结果。
  8. 构建与离线：元数据自动驱动 scripts/offline.mjs 生成路由。仍需检查 Worker / 新依赖进入资源清单，下载资源后断网运行新工具；不要只验证旧 Base64 路由。

文档同步矩阵（同次变更完成）

变更 必须更新 重点
新工具 / 分类 / 工具总数 docs/tools.md、README、docs/requirements.md、验证记录；必要时 AGENTS 当前概览 独立入口计数、路由、能力、输入输出、示例和限制
新模式 / 参数 / 默认值 / 输出 工具手册对应段落、验证记录；改变产品范围时更新需求 参数键、所有枚举选项、默认值、模式适用条件和失败边界
共享 UI / 快捷键 / 状态交互 docs/design-style.md、docs/interaction-style.md、验证记录 检查其他调用方、双语、主题、窄屏、键盘
Worker / 存储 / 数据流 docs/code-style.md、需求或交互、验证记录 调度、取消、生命周期、隐私和能力要求
依赖或构建命令 docs/dependencies.md、README、本文、相关架构 / 验证记录 实际版本、许可证、用途、本地加载、部署路径和成本
隐私 / 文件上限 / 敏感字段 README、需求、手册、相应交互和验证记录 代码边界、落盘策略、上传与权限变化
仅纠正文档 对应文档；必要时同步导航和 AGENTS 来源核对、链接、术语与当前状态，不声称完成未执行测试

文档校验能阻止漏记新入口、参数、枚举及失效本地链接；不会验证全部语义、默认值是否准确或发布兼容性。改默认值、行为和限制仍需人工核对。不要只在末尾追加一段与前文矛盾的“新版本说明”。

新工具文档模板

在 docs/tools.md 对应分类下新增唯一标题，格式与校验脚本一致：

### `tool-id` · 中文工具名称

**状态**：已实现。**路由**：`/tools/tool-id`。**持久草稿**：禁用 / 用户主动开启后可保存。

- **用途**：说明解决的任务。
- **输入**：类型、文件或辅助输入。
- **输出**：文本、代码、文件或报告。
- **使用注解与限制**：格式、条数、大小、数据保真、隐私和不支持项。
- **实现**：链接到真实源码。

**参数**：

| 参数键 / 界面名称 | 默认值     | 可选值或类型       |
| ----------------- | ---------- | ------------------ |
| `mode` · 模式     | `"encode"` | `encode`、`decode` |

**示例输入**：可直接用于页面示例的非敏感内容。

以上 tool-id 是模板占位符，不应作为真实功能进入元数据。只读工具可以说明无转换参数、无通用导出。

验证和记录

  • 根据变更执行相关检查；功能修改通常包括 docs:check、类型、Lint、测试和构建。只改 Markdown 时至少做文档一致性、链接和格式检查。
  • 记录日期、版本或环境、操作、通过 / 失败 / 待验证和局限。自动测试不替代视觉、文件、取消、剪贴板、离线与辅助技术验收。
  • 行为变更用正常/错误/边界案例；样式变更用实际截图和浏览器检查，不写只复述类名的测试。
  • 历史记录和当前状态分开，保留有效证据但不要把旧工具数、旧性能或旧检查结果当作当前结论。

静态部署与离线验证

默认根路径构建：pnpm build。子路径托管用环境变量 VITE_BASE_PATH，格式为以 / 开头和结束的路径段，例如 /DevKit/。

PowerShell 示例：

$env:VITE_BASE_PATH = '/DevKit/'
pnpm build
Remove-Item Env:VITE_BASE_PATH

POSIX shell 示例：

VITE_BASE_PATH=/DevKit/ pnpm build

现有 .github/workflows/ci.yml 执行检查；pages.yml 在 main 推送或手动触发时检查、构建、上传 Pages 产物并部署。本指南不代表授权推送或部署。修改 workflow 或产物不能替代实际远程验收。

本地验收：构建 → preview → 在设置下载离线资源 → 等待完成 → 断网 → 直接进入新路由 → 运行示例与 Worker → 检查导出、恢复联网和更新。测试多标签、配额不足、缓存损坏等额外情形时逐项记录。