@creatoria/miniapp-mcp 0.1.3 → 0.2.2

package/docs/current/README.md

@@ -0,0 +1,226 @@
+# 当前待实施改动总览
+
+> 最后更新: 2025-12-27
+> 版本: 0.3.0 (规划中)
+
+## 概述
+
+本目录包含两个待实施的改动计划：
+
+1. **架构迁移**：完全使用新架构（capabilities + runtime）
+2. **截图修复**：解决截图超时卡住问题
+
+---
+
+## 改动一览
+
+| 改动 | 类型 | 优先级 | 预计工时 | 文档 |
+|------|------|--------|---------|------|
+| 架构迁移 | 重构 | 高 | 18-25h | [01-architecture-migration.md](./01-architecture-migration.md) |
+| 截图修复 | Bug Fix | 紧急 | 8-9h | [02-screenshot-timeout-fix.md](./02-screenshot-timeout-fix.md) |
+
+---
+
+## 改动一：架构迁移
+
+### 背景
+
+项目当前处于混合架构状态：
+- 运行时服务 (runtime/) 已完成迁移：100%
+- 工具实现 (tools/) 完全未迁移：0%
+- 能力框架 (capabilities/) 仅作为代理：50%
+
+### 目标
+
+将 5,244 行工具代码从 `src/tools/` 迁移到 `src/capabilities/`，实现：
+- 模块化工具组织
+- Schema 驱动的输入验证
+- 动态工具加载
+- 删除旧的 tools/ 和 core/ 目录
+
+### 核心改动
+
+```
+当前结构:                         目标结构:
+src/                              src/
+├── tools/          ❌ 5,244行     ├── capabilities/    🆕 模块化
+│   ├── index.ts    1,645行       │   ├── automator/
+│   ├── automator.ts              │   │   ├── schemas/
+│   ├── miniprogram.ts            │   │   └── handlers/
+│   └── ...                       │   ├── miniprogram/
+├── core/           ❌ 兼容层      │   │   ├── schemas/
+│   └── *.ts        → runtime     │   │   └── handlers/
+└── runtime/        ✅ 保持       │   ├── page/
+                                  │   ├── element/
+                                  │   ├── loader.ts     🆕
+                                  │   └── registry.ts   🆕
+                                  └── runtime/          ✅ 保持
+```
+
+### 工作量
+
+| 阶段 | 内容 | 预计时间 |
+|------|------|---------|
+| Phase 1 | 基础设施（loader/registry） | 3-4h |
+| Phase 2 | Automator 迁移（4工具） | 2-3h |
+| Phase 3 | MiniProgram 迁移（6工具） | 2-3h |
+| Phase 4 | Page 迁移（8工具） | 2-3h |
+| Phase 5 | Element 迁移（23工具） | 3-4h |
+| Phase 6 | Assert/Snapshot/Record/Network | 4-5h |
+| Phase 7 | 清理与测试 | 2-3h |
+| **总计** | - | **18-25h** |
+
+---
+
+## 改动二：截图超时修复
+
+### 问题
+
+`miniprogram_screenshot` 工具调用时经常卡住：
+- 无超时保护：Promise 永不 resolve/reject
+- base64 返回被删除：必须走文件保存路径
+- 级联影响：所有 snapshot 工具都会卡住
+
+### 根本原因
+
+```typescript
+// ❌ 当前代码 - 无超时保护
+const screenshotBuffer = await session.miniProgram.screenshot({
+  path: fullPath,
+  fullPage,
+})
+
+// ✅ 应该使用 withTimeout
+const screenshotBuffer = await withTimeout(
+  session.miniProgram.screenshot({ ... }),
+  timeoutMs,
+  'Screenshot capture'
+)
+```
+
+### 核心改动
+
+1. **P0**：为 screenshot 添加 withTimeout 保护
+2. **P0**：恢复 returnBase64 参数和 base64 返回
+3. **P1**：为其他 miniprogram 操作添加超时
+4. **P1**：添加重试机制
+5. **P2**：优化 fullPage 超时配置
+
+### 工作量
+
+| 任务 | 预计时间 | 优先级 |
+|------|---------|--------|
+| screenshot 超时保护 | 1h | P0 |
+| 恢复 base64 返回 | 1h | P0 |
+| 其他操作超时保护 | 2h | P1 |
+| 重试机制 | 1.5h | P1 |
+| 配置优化 | 1h | P2 |
+| 测试 | 2h | P1 |
+| **总计** | **8-9h** | - |
+
+---
+
+## 建议实施顺序
+
+### 方案 A：先修复后迁移（推荐）
+
+```
+Week 1: 截图修复 (8-9h)
+  ├─ Day 1-2: P0 任务（超时保护 + base64）
+  └─ Day 3-4: P1 任务（其他超时 + 重试）
+
+Week 2-3: 架构迁移 (18-25h)
+  ├─ Day 1: Phase 1（基础设施）
+  ├─ Day 2-3: Phase 2-4（核心工具）
+  ├─ Day 4-5: Phase 5-6（剩余工具）
+  └─ Day 6: Phase 7（清理测试）
+```
+
+**优势**：
+- 先解决紧急问题
+- 迁移时可以同时应用超时保护
+
+### 方案 B：迁移时同步修复
+
+```
+直接进行架构迁移，迁移 miniprogram 工具时顺带修复超时
+```
+
+**优势**：
+- 避免重复修改同一文件
+- 代码只需 review 一次
+
+**劣势**：
+- 紧急问题需要等待更长时间
+
+---
+
+## 文件变更汇总
+
+### 新建文件（约 40 个）
+
+| 目录 | 文件数 | 描述 |
+|------|--------|------|
+| capabilities/*/schemas/ | ~20 | Zod schema 定义 |
+| capabilities/*/handlers/ | ~12 | 工具处理器 |
+| capabilities/ | 3 | loader/registry/index |
+| runtime/retry/ | 2 | 重试机制 |
+| tests/ | 3 | 新增测试 |
+
+### 修改文件（约 10 个）
+
+| 文件 | 改动 |
+|------|------|
+| src/server.ts | 使用新的 capabilities 入口 |
+| src/tools/miniprogram.ts | 添加超时保护（临时，迁移后删除） |
+| src/config/defaults.ts | 新增超时配置 |
+| src/types.ts | 更新类型定义 |
+| tests/**/*.test.ts | 更新导入路径 |
+
+### 删除文件（约 17 个）
+
+| 目录 | 文件数 | 描述 |
+|------|--------|------|
+| src/tools/ | 9 | 全部工具文件 |
+| src/core/ | 8 | 全部兼容层文件 |
+
+---
+
+## 风险评估
+
+| 风险 | 概率 | 影响 | 缓解措施 |
+|------|------|------|---------|
+| 迁移过程中引入 bug | 中 | 高 | 逐阶段提交，完整测试 |
+| 超时时间设置不合理 | 低 | 中 | 配置化，允许用户调整 |
+| 测试覆盖不足 | 低 | 中 | 先补充测试再迁移 |
+| 文档不同步 | 低 | 低 | 同步更新 README |
+
+---
+
+## 验收标准
+
+### 架构迁移
+
+- [ ] 所有 65 个工具迁移到 capabilities/
+- [ ] tools/ 和 core/ 目录删除
+- [ ] 所有工具有 Zod schema
+- [ ] 单元测试 100% 通过
+- [ ] 集成测试通过
+- [ ] TypeScript 编译无错误
+
+### 截图修复
+
+- [ ] 截图 10s 内返回或超时
+- [ ] fullPage 截图 30s 内返回或超时
+- [ ] returnBase64=true 正确返回 base64
+- [ ] 所有 miniprogram 操作有超时保护
+- [ ] 超时测试覆盖
+
+---
+
+## 相关文档
+
+- [01-architecture-migration.md](./01-architecture-migration.md) - 架构迁移详细计划
+- [02-screenshot-timeout-fix.md](./02-screenshot-timeout-fix.md) - 截图修复详细方案
+- [../directory-structure-and-code-style-best-practices.md](../directory-structure-and-code-style-best-practices.md) - 代码规范
+- [../migration/](../migration/) - 历史迁移文档

package/docs/directory-structure-and-code-style-best-practices.md

@@ -0,0 +1,91 @@
+# Creatoria MiniApp MCP 目录结构与代码规范建议
+
+本文档总结 Creatoria MiniApp MCP 迁移阶段的目录与代码规范建议，帮助团队在重构过程中保持一致的工程节奏。
+
+## 目标与原则
+- **分层清晰**：运行时（runtime）、应用入口（app）、能力工具（capabilities）各自独立，减少跨层耦合。
+- **能力可扩展**：工具数量超过 60 个，必须按能力分组并支持自动生成文档与类型。
+- **交付可验证**：每一步都应有脚本化校验（lint、typecheck、tests、smoke）。
+- **文档同步**：代码、schema、使用手册保持同源，避免漂移。
+
+## 推荐目录蓝图
+```
+.
+├── docs/
+│   ├── migration/                  迁移策略与阶段总结
+│   └── playbook/                   操作手册、调试指南
+├── examples/
+│   └── scenarios/                  可复用的自动化脚本示例
+├── scripts/
+│   ├── generate-tools-docs.ts      根据 schema 生成工具文档
+│   └── verify-release.ts           发布前巡检脚本（lint/typecheck/tests）
+├── src/
+│   ├── app/
+│   │   ├── cli/                    CLI 解析、日志初始化
+│   │   └── server/                 MCP server 入口
+│   ├── runtime/
+│   │   ├── session/                会话存储、清理、钩子
+│   │   ├── logging/                统一日志接口与实现
+│   │   ├── outputs/                会话产物（截图、报告）管理
+│   │   ├── timeout/                超时与重试策略
+│   │   ├── validation/             输入校验工具
+│   │   └── element/                ElementRef 解析与缓存
+│   ├── capabilities/
+│   │   ├── automator/
+│   │   ├── miniprogram/
+│   │   ├── page/
+│   │   ├── element/
+│   │   ├── assert/
+│   │   ├── snapshot/
+│   │   ├── record/
+│   │   └── network/
+│   │       └── schemas/            Zod 输入输出 schema
+│   ├── adapters/
+│   │   ├── wechat-devtools/        IDE 进程、端口管理
+│   │   └── storage/                产物持久化策略
+│   ├── config/                     默认配置、加载器、环境变量映射
+│   ├── types/                      公共类型与错误定义
+│   └── index.ts                    项目主导出
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   └── smoke/                      CLI+会话生命周期巡检
+└── tools.json                      自动生成的工具清单
+```
+
+## 代码规范要点
+- **Schema 驱动**：
+  - 使用 `zod` 描述每个工具的输入/输出，导出 `z.infer` 类型给实现复用。
+  - 借助 `zod-to-json-schema` 生成 MCP `inputSchema`，统一由脚本写回文档。
+- **Session 管理**：
+  - Session 日志统一走 `runtime/logging`，避免直接使用 `console.*`。
+  - 在 `runtime/session` 内新增 `SessionHooks`（beforeCleanup/afterCleanup）便于扩展 trace、性能采集。
+- **错误处理**：
+  - 定义 `McpError` 树（配置错误、执行错误、底层自动化错误），在 server 层统一序列化。
+  - 提供 `wrapToolError(handler)` 高阶函数约束日志格式。
+- **产物输出**：
+  - 将截图、DOM dump、网络日志统一放在 `~/.creatoria-miniapp-mcp/<session-id>`。
+  - OutputManager 负责命名策略与元数据回写。
+- **Runtime 实现**：
+  - `src/runtime/**` 已承载 session/logging/timeout/validation/element 等核心实现；`src/core/**` 仅保留兼容性再导出，后续可逐步清理。
+- **TypeScript 设定**：
+  - 保持 `strict`，启用 `exactOptionalPropertyTypes`、`moduleDetection: "force"`。
+  - 为测试单独维护 `tsconfig.test.json`，保持编译边界干净。
+- **Lint & Format**：
+  - 使用 `@typescript-eslint` 严格模式（`plugin:@typescript-eslint/recommended-type-checked`）。
+  - Markdown 文档执行 `prettier --check` 或 markdownlint，保证 changelog、指南格式一致。
+- **测试策略**：
+  - Unit：覆盖 `runtime`、`config`、`adapters` 等纯逻辑模块。
+  - Integration：基于 `test-miniapp/` 执行真实 automator 流程。
+  - Smoke：`scripts/smoke-test.sh` 验证 CLI、session 生命周期。
+  - 推荐在 CI 中分段执行：`lint → typecheck → unit → integration → smoke`。
+- **发布前检查**：
+  - `verify-release.ts` 聚合 build、工具文档生成、smoke test。
+  - `package.json` 中 `files` 字段保留 `dist/*.d.ts` 与 `tools.json`，确保发布包自带类型与元数据。
+
+## 文档协同
+- 迁移相关资料统一放入 `docs/migration/`，并通过 `docs/migration/README.md` 汇总索引。
+- 各能力目录可在 `docs/playbook/` 内补充操作示例或故障排查手册。
+- 更新文档时与 `.llm/task_cards/` 对应任务保持同步，确保任务状态可追踪。
+
+以上规范为迁移阶段的基线，可在任务卡执行过程中持续补充细节。

package/docs/migration/README.md

@@ -0,0 +1,34 @@
+# Creatoria MiniApp MCP 迁移总览
+
+本页汇总迁移阶段的关键资料、任务卡与协作规则，便于团队快速掌握当前进展。
+
+## 当前分支与目标
+- **分支**：`migration-structure-prep`
+- **阶段**：迁移规划与骨架搭建
+- **目标**：在保持现有 0.1.x 功能稳定的前提下，完成目录重组、schema 策略制定与文档对齐。
+
+## 已完成迁移
+- Session / Outputs / Logging / Timeout / Validation / ElementRef 实现已迁移至 `src/runtime` 对应目录。
+- Automator 工具首批 Zod schema 与 `scripts/generate-tool-schemas.ts` 已落地，可通过 `pnpm generate:schemas` 产出 JSON Schema。
+- `src/core` 目录目前仅保留再导出，未来阶段可清理或移除。
+
+## 关键文档
+- `docs/directory-structure-and-code-style-best-practices.md`：目录规划与代码规范建议
+- `docs/migration/runtime-skeleton.md`：旧实现与新骨架的映射表
+- `docs/migration/tool-schema-strategy.md`：工具 schema 驱动方案
+- `.llm/task_cards/`：迁移阶段的 6A 任务卡集合
+
+## 任务追踪
+- `.llm/state.json`：记录当前阶段、待办任务、已完成卡片
+- 建议流程：完成任务卡 → 更新对应文档 → 同步 `.llm/state.json` → 准备评审
+
+## 协作守则（摘录）
+1. **不破坏现有 CLI/工具行为**：所有代码迁移需先创建桥接层，再逐步替换实现。
+2. **文档与代码同步**：新增或调整目录后必须更新映射表与任务卡。
+3. **Schema 先行**：在实现新工具或改动入参前，优先补充 Zod schema 与自动化脚本。
+4. **语言一致性**：中文文档保持术语一致（例如“能力”“工具”“会话”），英文文档聚焦使用指南。
+
+## 下一步
+- 审阅开放问题（详见 `tool-schema-strategy.md`），确认输出 schema 与 JSON Schema 的存放策略。
+- 扩展剩余能力（MiniProgram/Page/Element 等）的 schema 与自动生成流程。
+- 评估 `src/core` 再导出是否可以在下一阶段完全移除，并更新发布脚本。

package/docs/migration/TC-ALIGN-01-notes.md

@@ -0,0 +1,35 @@
+# TC-ALIGN-01 · Migration Scope Alignment Notes
+
+## Scope Focus (Cycle 1)
+- 引入 `src/app`, `src/runtime`, `src/capabilities` 三层骨架，并通过 re-export 保持现有入口 (`src/server.ts`, `src/index.ts`, `dist/cli.js`) 行为不变。
+- 先行整理 `runtime/session` 与 `runtime/logging` 的职责边界，拆分清理/产物逻辑，准备后续测试。
+- 设计 schema 驱动的工具目录结构，但首轮仅输出目录与文档占位符，代码迁移留待后续任务。
+- 建立 `docs/migration` 板块作为迁移期间的单一信息源，配套更新 `.llm/task_cards/` 进度。
+
+## Stability Requirements
+- **CLI 接口**：`pnpm build/start`, `dist/cli.js`, `bin.miniprogram-mcp` 与 `creatoria-miniapp-mcp` 命令、现有 CLI 参数必须保持兼容，帮助文本暂不调整。
+- **配置加载**：`loadConfig` 行为与优先级（CLI > env > config > defaults）不能改变，`package.json` 中 `main` 和 `files` 字段保持当前路径。
+- **工具清单**：`scripts/update-readme.ts` 与 smoke test 依赖 65 个工具计数，迁移前不得移除或重命名现有工具导出。
+- **测试与脚本**：`pnpm lint|typecheck|test:unit|test:integration|smoke-test` 需要可执行，即使短期跳过某些校验，也必须在文档中说明原因。
+- **发布资产**：`dist/` 结构、类型声明、NPM 发布配置不做变更；保留 `README.md`、`CHANGELOG.md` 与现有示例的可访问性。
+
+## Immediate Priorities
+1. 整理 `runtime` 与 `capabilities` 的目录映射表，为后续任务卡（TC-STRUCT-02）提供输入。
+2. 与维护者确认 `.workflow/` 与历史文档删除是否属于旧进度清理，防止误删必需资产。
+3. 建立迁移状态同步节奏：完成每张任务卡后更新 `.llm/state.json` 的 `open_tasks` 与 `stage`。
+
+## Deferred Topics
+- Schema 自动化脚本实现（归入 TC-SCHEMA-03）。
+- 重命名或裁剪工具清单（待完成新架构后评估）。
+- 引入新的依赖（如 `zod-to-json-schema`）需等到策略确认。
+
+## Open Questions
+| 编号 | 问题 | 建议负责人 | 备注 |
+|------|------|------------|------|
+| Q1 | `.workflow/` 目录是否属于后续自动化需求？ | Samuel / 项目 Owner | 当前仓库中出现为未跟踪文件，需要确认保留或清理。 |
+| Q2 | 迁移阶段是否需要锁定 `pnpm` 版本或提供 npm/yarn 指南？ | Maintainers | Smoke test 与发布脚本依赖 pnpm@9，需确认团队环境。 |
+| Q3 | 是否需要在迁移前建立快照（tag 或 release branch）以便回滚？ | Maintainers | 当前版本为 v0.1.3，建议在结构调整前做标记。 |
+
+## Next Steps
+- 将本笔记分享给相关干系人确认（完成 6A 中的 Approve）。
+- 根据反馈更新任务卡或新增卡片，然后进入 TC-STRUCT-02 执行阶段。

package/docs/migration/runtime-skeleton.md

@@ -0,0 +1,50 @@
+# Runtime Skeleton Mapping
+
+本文件用于跟踪迁移阶段的新目录骨架与现有实现之间的对应关系，确保在逐步搬迁代码时不会破坏对外接口。
+
+## 应用层 (src/app)
+| 新路径 | 现有实现 | 说明 |
+|--------|----------|------|
+| `src/app/server/index.ts` | `src/server.ts` | 暂时对外导出 `startServer` 与 `ServerConfig` 类型，后续将 server 启动逻辑迁移至该目录。 |
+| `src/app/cli/index.ts` | `src/cli.ts` | 占位导出，保持 CLI 入口仍由 legacy 文件提供。 |
+| `src/app/index.ts` | 组合 `app/server` 与 `app/cli` | 为未来统一应用入口做准备。 |
+
+## 运行时层 (src/runtime)
+| 新路径 | 现有实现 | 说明 |
+|--------|----------|------|
+| `src/runtime/session/index.ts` | `src/runtime/session/store.ts` | 暴露 SessionStore 及清理工具函数。 |
+| `src/runtime/session/store.ts` | `src/core/session.ts` | SessionStore 实现迁移至 runtime。 |
+| `src/runtime/session/utils/cleanup.ts` | `src/core/session.ts` | 会话资源清理逻辑独立封装。 |
+| `src/runtime/element/element-ref.ts` | `src/core/element-ref.ts` | 元素定位与缓存逻辑迁移至 runtime。 |
+| `src/runtime/logging/index.ts` | `src/runtime/logging/*` | 汇总日志接口，指向新的 runtime 实现。 |
+| `src/runtime/logging/logger.ts` | `src/core/logger.ts` | 结构化日志实现迁移至 runtime。 |
+| `src/runtime/logging/tool-logger.ts` | `src/core/tool-logger.ts` | ToolLogger 封装迁移至 runtime。 |
+| `src/runtime/outputs/index.ts` | `src/runtime/outputs/*` | 聚合产物与报告逻辑。 |
+| `src/runtime/outputs/output-manager.ts` | `src/core/output.ts` | 输出管理器实现迁移至 runtime。 |
+| `src/runtime/outputs/report-generator.ts` | `src/core/report-generator.ts` | 会话报告生成迁移至 runtime。 |
+| `src/runtime/timeout/index.ts` | `src/runtime/timeout/timeout.ts` | 暴露超时工具。 |
+| `src/runtime/timeout/timeout.ts` | `src/core/timeout.ts` | 超时实现迁移至 runtime。 |
+| `src/runtime/validation/index.ts` | `src/runtime/validation/validation.ts` | 暴露校验工具。 |
+| `src/runtime/validation/validation.ts` | `src/core/validation.ts` | 校验工具实现迁移至 runtime。 |
+| `src/runtime/index.ts` | 聚合上述模块 | 统一导出 runtime 功能，为后续模块化做准备。 |
+
+## 能力层 (src/capabilities)
+| 新路径 | 现有实现 | 说明 |
+|--------|----------|------|
+| `src/capabilities/automator/index.ts` | `src/tools/automator.ts` | 直接 re-export。 |
+| `src/capabilities/automator/schemas/*.ts` | 新增 | Automator 工具 Zod schema 定义（launch/connect/disconnect/close）。 |
+| `src/capabilities/miniprogram/index.ts` | `src/tools/miniprogram.ts` | 直接 re-export。 |
+| `src/capabilities/page/index.ts` | `src/tools/page.ts` | 直接 re-export。 |
+| `src/capabilities/element/index.ts` | `src/tools/element.ts` | 直接 re-export。 |
+| `src/capabilities/assert/index.ts` | `src/tools/assert.ts` | 直接 re-export。 |
+| `src/capabilities/snapshot/index.ts` | `src/tools/snapshot.ts` | 直接 re-export。 |
+| `src/capabilities/record/index.ts` | `src/tools/record.ts` | 直接 re-export。 |
+| `src/capabilities/network/index.ts` | `src/tools/network.ts` | 直接 re-export。 |
+| `src/capabilities/index.ts` | `src/tools/index.ts` | 暂时继续导出全部工具注册逻辑，后续将拆分能力开关。 |
+
+## 后续动作提示
+1. 当实际逻辑迁移至新目录时，更新本表，确保每个功能模块都有明确归属。
+2. 在 TC-SCHEMA-03 中补充 schema 目录 (`src/capabilities/*/schemas`) 与自动生成脚本。
+3. 使用 `pnpm generate:schemas` 从注册表导出 JSON Schema，保持 MCP 契约同步。
+4. Session/输出模块迁移后，旧 `src/core/*` 文件仅保留再导出，后续可以清理。
+5. 完成迁移后，逐步让现有模块引用新路径，最终删除 legacy 文件。

package/docs/migration/tool-schema-strategy.md

@@ -0,0 +1,75 @@
+# Tool Schema Strategy
+
+本策略用于规划 Creatoria MiniApp MCP 在迁移阶段的工具 schema 体系，目标是在保持现有 65 个工具可用的前提下，引入可维护、可生成文档的 Zod 驱动流程。
+
+## 目标
+- **统一定义**：每个工具的输入/输出同源于 Zod schema，避免 TypeScript 定义、JSON Schema、文档三者漂移。
+- **自动产出**：通过 `scripts/generate-tool-schemas.ts` 生成 MCP `inputSchema`，后续扩展类型声明与文档片段，减少手工维护成本。
+- **渐进迁移**：保留当前 `src/tools/index.ts` 行为，逐步让工具依赖新 schema，而非一次性重写。
+
+## 模块组织
+```
+src/
+└── capabilities/
+    ├── automator/
+    │   ├── handlers/              # 现有工具实现（后续迁移）
+    │   └── schemas/
+    │       ├── launch.ts          # Zod schema 定义
+    │       └── index.ts           # 导出所有 automator schema
+    ├── miniprogram/
+    │   └── schemas/
+    ├── ...
+    └── schema-registry.ts         # 聚合所有 capability schema
+```
+
+- **命名约定**：`<tool-name>.schema.ts` 或在共享情况下使用 `<domain>.shared.ts`。
+- **导出格式**：每个 schema 文件导出 `inputSchema`, `outputSchema?`, `ToolMetadata`（含描述、能力标签）。
+- **类型复用**：结合 `z.infer<typeof schema>` 声明 TypeScript 类型，供 handlers 引用。
+
+## 运行时集成
+1. **Zod 校验**：在 `schema-registry.ts` 中维护 `Record<string, ToolSchema>`，加载时完成 `inputSchema.parse(args)`，替换现有手写校验。
+2. **JSON Schema 生成**：新增 `scripts/generate-tool-schemas.ts`，使用 `zod-to-json-schema` 导出 JSON Schema：
+   ```ts
+   import { zodToJsonSchema } from 'zod-to-json-schema'
+   const jsonSchema = zodToJsonSchema(schema, toolName)
+   ```
+3. **工具注册**：`src/tools/index.ts` 不再声明 `inputSchema`，改为从生成的 `dist/schemas/<tool>.json` 读取或直接从 registry 获取。
+4. **构建产物**：在 `pnpm build` 前执行 schema 生成，确保 `dist/` 中包含 JSON schema 与 `.d.ts`。
+5. **错误处理**：为每个 schema 注册友好的校验错误格式（例如 `schema.safeParse` + 自定义错误信息）。
+
+## 文档生成流程
+- 扩展现有 `scripts/update-readme.ts`：读取 schema registry，输出参数表（字段、类型、必填、描述）。
+- 新增 `docs/playbook/tool-reference.md`（自动生成），列出每个工具的入参/出参。
+- 通过 `package.json` 增加脚本：
+  ```json
+  {
+    "scripts": {
+      "generate:schemas": "tsx scripts/generate-tool-schemas.ts"
+    }
+  }
+  ```
+- 在 CI / smoke-test 中插入 `pnpm generate:schemas && pnpm docs:tools`，保证文档与实现同步。
+
+## 渐进落地步骤
+1. **阶段一**：引入 schema 目录与 registry（无行为改动），在 `tools/index.ts` 中引入可选的 `useSchemas` flag。
+2. **阶段二**：为 Automator 工具编写首批 schema，验证生成脚本；文档仍引用旧结构。
+3. **阶段三**：完成所有工具的 schema，切换工具注册逻辑；废弃 legacy JSON schema。
+4. **阶段四**：拓展输出 schema、错误定义，并与测试（unit/integration）结合验证。
+
+## 兼容性与风险
+- 保留现有 `scripts/update-readme.ts` 行为，直到新脚本产出结果等效。
+- 更新依赖需评估包体：`zod-to-json-schema`、可能的 `ts-node`/`tsx` 版本。
+- 生成 JSON Schema 时注意 `z.union`、`z.discriminatedUnion` 与 `enum` 的映射，避免客户端解析问题。
+- 调整 `SessionStore` 或工具 handler 时，确保 `args` 类型已切换为 schema 导出的类型。
+
+## 开放问题
+| 编号 | 问题 | 负责人 | 备注 |
+|------|------|--------|------|
+| Q1 | 是否需要为所有工具定义输出 schema，还是仅在需要结构化响应时启用？ | Maintainers | 当前 MCP 仅要求输入校验，但输出 schema 有助于客户端推断类型。 |
+| Q2 | JSON Schema 存储位置选择：保存在 `dist/schemas/` 还是内嵌到构建产物？ | Maintainers | 影响发布包体积与消费方式。 |
+| Q3 | 是否需要向后兼容旧 JSON schema 导出的文档格式？ | Docs Owner | 现有 README 表格依赖固定格式，需要确认迁移策略。 |
+
+## 下一步
+- 评审此策略并确认落地顺序。
+- 在 TC-DOCS-04 中更新文档导航，提示 schema 目录及脚本位置。
+- 进入下一阶段前，为 Automator 工具起草首个 schema 示例，验证生成脚本可行性。

package/docs//345/256/214/346/225/264/345/256/236/347/216/260/346/226/271/346/241/210.md

@@ -2,8 +2,8 @@
 
 ## 1. 背景与目标
 - 将微信官方自动化 SDK（`miniprogram-automator`）包装为符合 Model Context Protocol (MCP) 的服务，供各类 LLM / Agent 以自然语言编排端到端测试与运维流程。
-- 参考 `playwright-mcp` 的成熟实践，形成工具粒度清晰、配置灵活、可观测性良好的工程体系。
-- 保持与需求文档、《微信小程序自动化 API 完整文档》一致的能力覆盖，同时吸收 Playwright MCP 的上下文管理、能力开关、自动文档等工程手段。
+- 构建工具粒度清晰、配置灵活、可观测性良好的工程体系，聚焦 Creatoria MiniApp MCP 的落地实践。
+- 保持与需求文档、《微信小程序自动化 API 完整文档》一致的能力覆盖，同时吸收成熟的上下文管理、能力开关、自动文档等工程手段。
 
 ## 2. 总体架构
 ```
@@ -21,7 +21,7 @@
 [本地小程序项目]
 ```
 - MCP Server 负责解析工具调用、维护会话状态、调度 `miniprogram-automator` 与 IDE 自动化端口。
-- 会话上下文仿照 Playwright MCP：懒加载启动 IDE、持有 MiniProgram/Page/Element 句柄、统一回收资源。
+- 会话上下文遵循统一管理：懒加载启动 IDE、持有 MiniProgram/Page/Element 句柄、统一回收资源。
 - 支持多 Host 并发接入，通过 MCP sessionId 隔离状态。
 
 ## 3. MCP 服务设计
@@ -39,16 +39,16 @@
   - `elements`: refId → Element 缓存（页面切换后自动失效）。
   - `outputs`: 当次会话的截图/数据快照目录。
 - 生命周期：首次请求创建，`miniProgram.close` 或会话断开时释放；异常时触发兜底清理。
-- 参考 Playwright 的 Context：加入 `outputFile()`、`log()`、`lookupSecret()` 等辅助方法以统一产物写入和敏感信息保护。
+- 引入统一的 Context 能力：加入 `outputFile()`、`log()`、`lookupSecret()` 等辅助方法以统一产物写入和敏感信息保护。
 
 ### 3.3 工具体系
 - **Automator 级**：`launch`、`connect`、`disconnect`、`close`。
 - **MiniProgram 级**：导航（`navigate_to`/`redirect_to`/`switch_tab`/...）、系统信息、`call_wx_method`、`mock_wx_method`、`evaluate`、`screenshot`、`page_scroll_to`、`test_accounts` 等。
 - **Page 级**：`wait_for`、`query`/`query_all`、`xpath` 系列、`data`/`set_data`、`call_method`、`size`、`scroll_top`。
 - **Element 级**：`text`、`attribute`、`value`、`property`、`style`、`tap`、`longpress`、`trigger`、`touch*`、子类专属（`input`、`scroll_to`、`swipe_to`、`move_to`、`slider_slide_to`、`context_call`、`custom_set_data` 等）。
-- **扩展工具**（对标 Playwright capabilities）：
+- **扩展工具**（覆盖高级能力开关）：
   - `snapshot_page`（结构化 DOM 报文）；
-  0  `assert` 系列（exists/text/data 等）；
+  - `assert` 系列（exists/text/data 等）；
   - `record_actions` / `replay_actions`；
   - `storage_get/set/clear`；
   - `network_mock`（基于 `mockWxMethod` 或注入脚本）；
@@ -67,7 +67,7 @@ type ElementRef = {
 };
 ```
 - 优先级：`refId` > `xpath` > `selector`；若页面刷新导致失效，自动抛错并提示重新查询。
-- 解析成功后按需缓存，类似 Playwright 的 `Tab` 对象管理。
+- 解析成功后按需缓存，类似常见的多标签页面管理模式。
 
 ## 4. API 映射策略
 - 对照《微信小程序自动化 API 完整文档》，确保 MiniProgram/Page/Element 方法全部可通过工具触达。
@@ -76,7 +76,7 @@ type ElementRef = {
 
 ## 5. 配置体系
 ### 5.1 配置来源
-1. **CLI 参数**（与 Playwright 对齐）：项目路径、CLI 路径、自动化端口、headless、输出目录、超时、能力开关等。
+1. **CLI 参数**：项目路径、CLI 路径、自动化端口、headless、输出目录、超时、能力开关等。
 2. **配置文件**：JSON/TS（通过 `--config` 指定），可嵌套定义项目列表、默认页面、Mock 脚本、Secrets。
 3. **环境变量**：用于注入敏感信息（token、账号），配合 `lookupSecret` 管理。
 
@@ -97,13 +97,13 @@ type ElementRef = {
 | `snapshot` | 页面结构化快照 + 截图 | `snapshot_page`、`capture_artifacts` |
 | `record` | 录制/回放工具 | Action Recorder 存储 |
 | `network` | `mock_wx`、`mock_plugin_wx` 扩展 | 注入脚本/Mock 配置 |
-| `tracing` | 每会话生成行为日志（对应 Playwright trace 思路） | 输出目录 |
+| `tracing` | 每会话生成行为日志（与行业 trace 实践一致） | 输出目录 |
 | `vision` | 未来支持坐标/截图分析（可选） | 视觉模型/IDE 截图 |
 
 ## 6. 输出与观测
 - **日志**：
   - 控制台输出结构化 JSON（tool、duration、result），便于 Host 呈现。
-  - 可选写入 `session.log`，仿照 Playwright 的 `SessionLog`。
+  - 可选写入 `session.log`，遵循统一的会话追踪格式。
 - **产物**：
   - 截图：`miniProgram.screenshot`；失败时自动抓取。
   - 页面数据快照：`page.data()` + 元素树；断言失败时附带 diff。
@@ -118,7 +118,7 @@ type ElementRef = {
 3. **自动化测试**：
    - 单元：针对 ElementRef 解析、配置解析编写 Jest/TS 测试。
    - 集成：使用示例小程序项目 + CI Runner（macOS/Windows）跑回归脚本。
-   - 参考 Playwright 的 `playwright test` 实践，构建 `tests/` 用例驱动 CLI。
+   - 借鉴成熟的端到端测试实践，构建 `tests/` 用例驱动 CLI。
 4. **CI/CD**：
    - 采用 GitHub Actions/Moore pipeline：
      1. 安装依赖与微信 IDE（或缓存）；
@@ -133,7 +133,7 @@ type ElementRef = {
 - 会话超时与 watchdog：长期未活动自动关闭 IDE。
 - 断言/操作前增加 `page.waitFor`/`wait_for_selector`，减少竞态失败。
 
-## 9. 与 Playwright MCP 的对齐点
+## 9. 行业对标与增值点
 - **工具 Schema 自动生成文档**：实现 `docs/update-readme.ts`，遍历工具注册，输出参数说明。
 - **能力分层**：使用 `capabilities` 控制高级功能开启，与 CLI `--caps` 对齐。
 - **上下文复用**：提供 `sharedMiniProgram` 模式，支持多个会话共享 IDE（类似 `SharedContextFactory`）。
@@ -149,7 +149,7 @@ type ElementRef = {
   2. 多端兼容（真机云测、远程调试接入）；
   3. 与团队测试平台集成（结果上报、用例管理）；
   4. 选择器智能推荐（结合页面结构快照与静态标记 `data-testid`）；
-  5. 结合 Playwright Vision 能力扩展到混合 H5 场景。
+  5. 扩展到混合 H5 场景时可引入视觉识别等高级能力。
 
 ---
-该方案汇总了需求文档的能力诉求、API 覆盖范围，以及 Playwright MCP 的工程实现方式，可作为后续开发与评审的基准文档。
+该方案汇总了需求文档的能力诉求、API 覆盖范围，以及业内成熟自动化平台的工程化经验，可作为后续开发与评审的基准文档。