@creatoria/miniapp-mcp 0.1.3 → 0.2.0

package/docs/charter.D3.align.yaml

@@ -1,206 +0,0 @@
-# Charter: [D3] Recording and Replay System
-
-task_id: D3
-task_name: 录制与回放系统实现
-stage: D
-phase: Align (Retrospective)
-created_at: "2025-10-02"
-status: COMPLETED
-estimated_hours: 3-4
-actual_hours: 3.5
-
-## Goal (目标)
-
-实现完整的工具调用序列录制与回放系统，支持保存测试场景、复现操作流程，为自动化测试和场景复用提供基础能力。
-
-**核心交付物**:
-- `src/tools/record.ts` - 录制/回放工具实现 (428 lines)
-- `tests/unit/record.test.ts` - 完整单元测试 (422 lines)
-- 6 个 MCP 工具：record_start, record_stop, record_list, record_get, record_delete, record_replay
-- ActionSequence 数据结构定义
-
-## Non-Goals (非目标)
-
-- ❌ 不实现视频录制（仅录制工具调用序列）
-- ❌ 不实现性能分析（仅记录 duration，不做分析）
-- ❌ 不实现自动断言生成（回放仅执行，不验证）
-- ❌ 不实现远程存储（仅本地文件系统）
-- ❌ 不实现编辑/修改已保存序列的能力
-
-## Scope (范围)
-
-### In Scope (包含)
-
-1. **录制管理**
-   - ✅ 启动录制（record_start）：设置名称和描述
-   - ✅ 停止录制（record_stop）：保存到 JSON 文件
-   - ✅ 自动生成 sequence ID（时间戳+随机数）
-   - ✅ 记录状态管理（SessionState.recording）
-
-2. **动作捕获**
-   - ✅ RecordedAction 数据结构：timestamp/toolName/args/duration/success/error
-   - ✅ recordAction() 内部函数：被工具包装器调用
-   - ✅ 过滤掉录制工具自身的调用
-   - ✅ 支持成功和失败操作的记录
-
-3. **序列管理**
-   - ✅ 列出所有序列（record_list）：返回摘要信息
-   - ✅ 获取序列详情（record_get）：返回完整 actions
-   - ✅ 删除序列（record_delete）：从文件系统移除
-   - ✅ 文件存储位置：`{outputDir}/sequences/{sequenceId}.json`
-
-4. **回放执行**
-   - ✅ 按序执行录制的工具调用（record_replay）
-   - ✅ 支持 continueOnError 模式
-   - ✅ 返回详细执行结果（success/failure 统计）
-   - ✅ 动态导入 tools 模块
-
-5. **数据结构**
-   - ✅ ActionSequence: id/name/description/createdAt/actions[]
-   - ✅ RecordedAction: timestamp/toolName/args/duration/success/error
-   - ✅ SessionState.recording: isRecording/startedAt/currentSequence
-
-### Out of Scope (不包含)
-
-- ❌ 序列编辑功能（无法修改已保存序列）
-- ❌ 条件逻辑（if/else/loop）
-- ❌ 变量和参数化
-- ❌ 回放速度控制
-- ❌ 断点调试
-- ❌ 远程共享序列
-
-## Constraints (约束)
-
-### Technical Constraints (技术约束)
-
-1. **存储格式**
-   - 必须使用 JSON 格式（便于人工阅读和编辑）
-   - 文件命名：`{sequenceId}.json`
-   - 目录：`{outputDir}/sequences/`
-
-2. **录制状态**
-   - 同一 Session 只能同时录制一个序列
-   - 录制状态存储在 SessionState.recording
-   - 停止录制后自动清空状态
-
-3. **工具集成**
-   - recordAction() 必须被所有工具包装器调用
-   - 录制工具自身不应被录制
-   - 回放时使用动态导入（避免循环依赖）
-
-4. **错误处理**
-   - 录制失败的操作也应被记录
-   - 回放可选择在错误时停止或继续
-   - 所有错误信息完整保留
-
-### Business Constraints (业务约束)
-
-1. **存储容量**: 单个序列 <10MB（典型测试场景 <100 个操作）
-2. **回放性能**: 操作间延迟 <10ms（不模拟真实延迟）
-3. **兼容性**: 序列格式向后兼容
-
-## Success Criteria (成功标准)
-
-### Functional Criteria (功能标准)
-
-- ✅ 启动录制并获得 sequenceId
-- ✅ 执行工具调用时自动记录到当前序列
-- ✅ 停止录制后生成 JSON 文件
-- ✅ list/get/delete 操作正常工作
-- ✅ 回放成功重现录制的操作序列
-- ✅ continueOnError=false 时遇到错误立即停止
-- ✅ continueOnError=true 时继续执行并统计失败数
-
-### Quality Criteria (质量标准)
-
-- ✅ TypeScript 编译 0 错误
-- ✅ 单元测试覆盖率 >90% (422 lines 测试代码)
-- ✅ 无 ESLint 错误
-- ✅ JSDoc 注释完整
-- ✅ JSON 格式美化输出（2 空格缩进）
-
-### Documentation Criteria (文档标准)
-
-- ✅ 函数签名有 JSDoc
-- ✅ 数据结构注释清晰
-- ⏳ charter.D3.align.yaml (本文档)
-- ⏳ tasks.D3.atomize.md (任务卡)
-
-## Definition of Done (完成标准)
-
-**代码**:
-- ✅ `src/tools/record.ts` 实现完成 (428 lines)
-- ✅ 6 个工具全部实现
-- ✅ 集成到 registerTools (tools/index.ts)
-- ✅ SessionState 扩展 recording 字段
-- ✅ TypeScript 编译通过
-
-**测试**:
-- ✅ `tests/unit/record.test.ts` (422 lines)
-- ✅ 所有核心函数有单元测试
-- ✅ 边界情况覆盖（已录制/未录制/文件不存在等）
-- ✅ 所有测试通过
-
-**文档**:
-- ⏳ charter.D3.align.yaml (追溯)
-- ⏳ tasks.D3.atomize.md (追溯)
-- ⏳ session_log (追溯)
-
-**Git**:
-- ✅ 已提交（feat: [D3] 录制回放能力实现）
-
-## Dependencies (依赖)
-
-**前置任务**:
-- ✅ B2: SessionStore 和 SessionState 定义
-- ✅ C1-C4: 核心工具实现（需要被录制）
-- ✅ C5: registerTools 机制
-
-**后续任务**:
-- D3 → E4: 示例项目（使用录制序列）
-- D3 → G1: 集成测试（使用回放验证）
-
-## Risks (风险)
-
-### Technical Risks (技术风险)
-
-1. **循环依赖** - 🟢 已缓解
-   - 风险：record.ts 导入 tools/index.ts 导致循环依赖
-   - 缓解：使用动态导入 `await import('./index.js')`
-
-2. **存储空间** - 🟢 低风险
-   - 风险：大量序列占用磁盘空间
-   - 缓解：用户手动管理，提供 delete 工具
-
-3. **格式兼容性** - 🟡 中风险
-   - 风险：未来工具 API 变更导致旧序列无法回放
-   - 缓解：保留 toolName 和 args 原始结构
-
-### Business Risks (业务风险)
-
-1. **回放失败** - 🟡 中风险
-   - 影响：序列依赖特定状态（如页面路径）
-   - 缓解：记录完整 args，包括 pagePath 等上下文
-
-2. **误用风险** - 🟢 低风险
-   - 影响：用户误以为回放会自动验证结果
-   - 缓解：文档明确说明回放不包含断言
-
-## Open Questions (未决问题)
-
-- ❓ 是否需要支持序列参数化（变量替换）？（当前不支持）
-- ❓ 是否需要支持序列合并/拆分？（当前不支持）
-- ❓ 是否需要记录页面截图作为视觉参考？（当前不支持）
-
-## References (参考资料)
-
-- `docs/完整实现方案.md` - 录制/回放架构设计
-- `docs/微信小程序自动化完整操作手册.md` - 自动化 API 参考
-- `src/types.ts` - ActionSequence/RecordedAction 定义
-- Playwright Inspector 录制功能 - 设计灵感
-
----
-
-**Approval**: ✅ RETROSPECTIVE APPROVED
-**Implementation**: ✅ COMPLETED
-**Documentation**: ⏳ IN PROGRESS

package/docs/charter.E-Docs.align.yaml

@@ -1,294 +0,0 @@
-# E1: Documentation Enhancement - Project Charter
-
-## Metadata
-task_id: E1
-stage: E - Documentation & Examples
-status: PLANNED
-created: 2025-10-02
-author: Claude Code
-approver: TBD
-
-## 1. Goals (目标)
-
-### Primary Goal (主要目标)
-Complete and polish the project documentation system to ensure developers can quickly understand, configure, and use the MCP server for WeChat Mini Program automation.
-
-完善 creatoria-miniapp-mcp 项目文档，提供清晰的使用指南、API 参考和实际示例，降低新用户上手门槛，提升项目可维护性。
-
-### Success Criteria (成功标准)
-- [ ] README.md provides 5-minute quickstart path
-- [ ] All 59 tools have complete API documentation with examples
-- [ ] At least 5 realistic usage examples covering major scenarios
-- [ ] Troubleshooting guide covers common errors and debugging workflows
-- [ ] Setup guide enables zero-to-running in <15 minutes
-- [ ] Documentation is consistent, searchable, and cross-referenced
-
-### Key Metrics (关键指标)
-- Documentation coverage: 100% of tools (59/59)
-- Example coverage: 5+ realistic scenarios
-- Quickstart completion time: <5 minutes (first run)
-- Setup completion time: <15 minutes (environment + config)
-
-## 2. Non-Goals (非目标)
-
-- ❌ Multi-language documentation (English/Chinese only, not other languages)
-- ❌ Interactive documentation website (Markdown files only for E1)
-- ❌ Video tutorials or screencasts (defer to Stage F)
-- ❌ Auto-generated API docs from TypeScript types (manual curation for now)
-- ❌ Migration guides from other automation frameworks
-- ❌ Performance benchmarking documentation
-- ❌ Advanced architecture deep-dives (keep in ADRs)
-
-## 3. Scope (范围)
-
-### In Scope
-
-#### 3.1 README.md Enhancement
-- **Current State**: Basic structure exists with installation and configuration sections
-- **Target State**:
-  - Hero section with value proposition
-  - Quickstart (<5 minutes to first successful command)
-  - Core features overview (59 tools categorized into 7 groups)
-  - 3 inline code examples (navigation, interaction, assertion)
-  - Clear navigation to detailed docs
-  - Badges (CI status, license, version)
-
-#### 3.2 API Documentation (docs/api/)
-- **Current State**: Framework exists with README + category files (placeholders)
-- **Target State**:
-  - `docs/api/README.md`: Tool catalog + basic workflows
-  - `docs/api/automator.md`: 4 tools (launch, connect, disconnect, close)
-  - `docs/api/miniprogram.md`: 6 tools (navigate, evaluate, screenshot, etc.)
-  - `docs/api/page.md`: 8 tools (query, data, wait, scroll, etc.)
-  - `docs/api/element.md`: 23 tools (attributes, interactions, component methods)
-  - `docs/api/assert.md`: 9 tools (exists, text, attribute, data, etc.)
-  - `docs/api/snapshot.md`: 3 tools (capture, restore, compare)
-  - `docs/api/record.md`: 6 tools (start, stop, save, replay, etc.)
-
-  **Format per tool**: Function description, parameters (with types), return value, code example, usage notes, common errors
-
-#### 3.3 Usage Examples (examples/)
-- **Current State**: `01-basic-navigation.md` exists (created previously)
-- **Target State**: 5+ examples covering:
-  1. ✅ `01-basic-navigation.md` (existing - review/enhance)
-  2. `02-element-interaction.md` (tap, input, swiper, scroll, picker)
-  3. `03-assertion-testing.md` (automated test workflow with asserts)
-  4. `04-snapshot-debugging.md` (capture/restore state for debugging)
-  5. `05-record-replay.md` (record user flow, replay for regression testing)
-  6. (Optional) `06-e2e-shopping.md` (complete shopping cart flow)
-
-  **Format**: Scenario description, prerequisites, step-by-step code with explanations, expected output, troubleshooting tips
-
-#### 3.4 Troubleshooting Guide (docs/troubleshooting.md)
-- **Current State**: File exists with basic structure
-- **Target State**:
-  - **FAQ Section**: Top 10-15 common questions
-  - **Error Reference**: Categorized by source (Automator, MCP, Network, Configuration)
-  - **Debugging Workflows**: Step-by-step diagnostic procedures
-  - **Best Practices**: Performance, reliability, maintainability tips
-  - **Common Pitfalls**: Element resolution, page state, timing issues
-
-#### 3.5 Setup Guide (docs/setup-guide.md)
-- **Current State**: File exists with basic installation steps
-- **Target State**:
-  - **Environment Requirements**: Detailed version requirements (Node, WeChat DevTools, OS)
-  - **WeChat DevTools Setup**: Automation port configuration, security settings
-  - **MCP Client Configuration**: Claude Desktop, Cline, custom clients
-  - **Verification Steps**: How to confirm everything is working
-  - **Configuration Options**: All .mcp.json options explained
-  - **Common Setup Issues**: Permission errors, port conflicts, path issues
-
-#### 3.6 Contributing Guide (CONTRIBUTING.md)
-- **Current State**: File exists
-- **Target State**:
-  - **6A Workflow**: Detailed explanation of Align/Architect/Atomize/Approve/Automate/Assess
-  - **Development Environment**: Setup, tools, commands
-  - **Code Standards**: TypeScript, testing, documentation conventions
-  - **Tool Development**: How to add new tools, register, test, document
-  - **PR Process**: Branch strategy, commit conventions, review checklist
-
-### Out of Scope (for E1)
-- Translation to languages other than English/Chinese
-- Interactive API playground
-- Auto-generated docs from code (revisit in Stage F)
-- Migration guides from Playwright/Cypress
-- Video/screencast tutorials (defer to Stage F)
-
-## 4. Context & Background (背景)
-
-### Current Documentation State
-```
-✅ Exists with content:
-  - README.md (basic structure)
-  - docs/api/README.md (framework)
-  - docs/api/*.md (category files with placeholders)
-  - examples/01-basic-navigation.md
-  - docs/troubleshooting.md (basic structure)
-  - docs/setup-guide.md (basic steps)
-  - CONTRIBUTING.md (exists)
-
-❌ Needs enhancement:
-  - All API docs need complete tool documentation (59 tools)
-  - Need 4+ additional examples
-  - Troubleshooting needs FAQ and error reference
-  - Setup guide needs detailed configuration explanations
-  - README needs quickstart and inline examples
-  - CONTRIBUTING needs 6A workflow documentation
-```
-
-### Implementation Context
-- Stage D2 (Snapshot capabilities) completed
-- All 59 tools are implemented and tested (290+ tests passing)
-- ElementRef protocol is stable
-- SessionStore and OutputManager are production-ready
-- MCP server is functional end-to-end
-- Record tools implemented in Stage D2
-
-### User Personas
-1. **New Users**: Need quickstart and simple examples
-2. **Integration Developers**: Need complete API reference
-3. **Test Engineers**: Need assertion and recording examples
-4. **Troubleshooters**: Need error reference and debugging guides
-5. **Contributors**: Need development workflow documentation
-
-## 5. Constraints & Assumptions (约束与假设)
-
-### Constraints
-- Documentation must be Markdown-based (portable, version-controlled)
-- Examples must be runnable or clearly fictional with explanations
-- API docs must stay synchronized with code (manual update protocol in CONTRIBUTING.md)
-- All code examples must use TypeScript/JavaScript (no other languages)
-- Documentation size: Keep individual files <2000 lines for readability
-- Bilingual support: English and Chinese (mixed is acceptable)
-
-### Assumptions
-- Readers have basic WeChat Mini Program knowledge
-- Readers understand MCP protocol basics (or can reference MCP docs)
-- Example code doesn't need to be copy-pastable (conceptual clarity prioritized)
-- Manual documentation maintenance is acceptable for now (no auto-generation)
-- Most users will access docs via GitHub (Markdown rendering)
-
-### Dependencies
-- Stage D completion (all 59 tools implemented)
-- Access to tool schemas and type definitions (src/tools/)
-- Understanding of ElementRef protocol (src/core/element-ref.ts)
-- Knowledge of SessionStore lifecycle (src/core/session-store.ts)
-- Test files as source of usage examples (tests/unit/)
-
-## 6. Risks & Mitigation (风险与缓解)
-
-### Risks
-
-| Risk | Impact | Probability | Mitigation |
-|------|--------|-------------|------------|
-| Documentation becomes outdated as code evolves | High | Medium | Establish update protocol in CONTRIBUTING.md, add checklist to PR template |
-| Examples don't match user scenarios | Medium | Medium | Base on test files, collect feedback, iterate |
-| API docs too technical for beginners | Medium | Low | Add beginner-friendly intro sections, progressive disclosure |
-| Inconsistent formatting across docs | Low | Medium | Create documentation template, review all docs for consistency |
-| Missing error codes in troubleshooting | Medium | Low | Cross-reference miniprogram-automator errors, add placeholders |
-| Work underestimated | Medium | Medium | Focus on core content, avoid over-polishing |
-
-### Open Questions
-1. **API Documentation Generation**: Should we invest in auto-generation from Zod schemas, or maintain manually?
-   - **Current Decision**: Manual for E1 (faster), revisit automation in Stage F
-
-2. **Example Code Verification**: Do we need a test suite that validates example code?
-   - **Decision Needed**: Defer to E2 or Stage G
-
-3. **Documentation Site**: Should we use VitePress/Docusaurus for better UX?
-   - **Current Decision**: Markdown files only for E1 (simplicity), revisit in Stage G
-
-4. **Localization Strategy**: Should we maintain separate EN/CN files or mixed?
-   - **Current Decision**: Mixed bilingual (headers in both languages) for critical docs
-
-5. **Example Mini Program**: Do we need a dedicated demo project?
-   - **Decision Needed**: Check if existing test project can serve this purpose
-
-## 7. Success Definition (完成标准)
-
-### Definition of Done (DoD)
-- [ ] README.md updated with quickstart, examples, and navigation
-- [ ] All 59 tools documented in docs/api/ with required format (function, params, return, example, notes, errors)
-- [ ] 5+ usage examples created in examples/ directory
-- [ ] docs/troubleshooting.md includes FAQ (10+ items), error reference (20+ codes), debugging workflows (3+ scenarios)
-- [ ] docs/setup-guide.md covers environment requirements, DevTools config, MCP client setup, verification steps
-- [ ] docs/architecture.md created with system overview, design decisions
-- [ ] CONTRIBUTING.md enhanced with 6A workflow, tool development guide
-- [ ] All documentation cross-referenced (internal links working)
-- [ ] Documentation reviewed for consistency, clarity, and completeness
-- [ ] All new/updated files committed to git with proper commit message
-
-### Acceptance Tests
-1. **Quickstart Test**: New user can run first automation command in <5 minutes following README
-2. **API Lookup Test**: Developer can find tool documentation and example for any of 59 tools in <2 minutes
-3. **Example Test**: User can understand and adapt example code for their scenario in <10 minutes
-4. **Troubleshooting Test**: User encountering error can find solution in troubleshooting.md in <5 minutes
-5. **Setup Test**: New user can configure environment end-to-end in <15 minutes following setup-guide.md
-
-### Evidence Collection
-- Screenshots of rendered Markdown in GitHub
-- Feedback from 2+ external reviewers (if available)
-- Checklist completion for all DoD items
-- Git commit log showing all documentation updates
-- Session log documenting work performed
-
-## 8. Timeline & Effort (时间与工作量)
-
-### Estimated Effort
-- README enhancement: 30 minutes
-- API documentation (59 tools): 2-3 hours (3-4 minutes per tool)
-- Usage examples (4 new + 1 enhancement): 2 hours (30 minutes each)
-- Troubleshooting enhancement: 1 hour
-- Setup guide enhancement: 30 minutes
-- Architecture document: 45 minutes
-- CONTRIBUTING enhancement: 30 minutes
-- Cross-referencing and review: 1 hour
-- **Total**: 7-9 hours
-
-### Phasing (分阶段执行)
-- **Phase 1** (2 hours): README + Setup Guide + Architecture (unblock new users)
-- **Phase 2** (3 hours): API Documentation (reference completion)
-- **Phase 3** (2 hours): Examples (learning materials)
-- **Phase 4** (1.5 hours): Troubleshooting + CONTRIBUTING + Review
-
-### Blockers
-- None identified (all dependencies complete)
-
-## 9. Stakeholders & Communication (相关方与沟通)
-
-### Stakeholders
-- **Primary**: Project maintainers (documentation owners)
-- **Secondary**: Future contributors (need clear docs to contribute)
-- **Tertiary**: End users (developers using the MCP server)
-
-### Communication Plan
-- Commit messages reference E1 task
-- Update .llm/state.json with progress
-- Create .llm/qa/E1-acceptance.md with evidence
-- Session log in .llm/session_log/ if work spans multiple sessions
-
-## 10. References (参考文档)
-
-### Related Documents
-- `docs/完整实现方案.md`: Original architecture
-- `docs/微信小程序自动化完整操作手册.md`: Source of truth for tool capabilities
-- `.llm/prompts/task.cards.md`: E1 task definition
-- `CONTRIBUTING.md`: Documentation contribution guidelines (to be enhanced)
-- `docs/charter.e1.align.yaml`: Original Chinese charter (superseded by this)
-- `docs/architecture.e1.md`: Original Chinese architecture (superseded by architecture.E1.md)
-
-### External References
-- MCP Protocol Documentation: https://modelcontextprotocol.io/
-- WeChat Mini Program Docs: https://developers.weixin.qq.com/miniprogram/dev/framework/
-- Markdown Style Guide: https://www.markdownguide.org/
-- GitHub Flavored Markdown: https://github.github.com/gfm/
-
----
-
-**Approval Required**: YES (Align stage requires explicit approval before Atomize)
-
-**Next Steps After Approval**:
-1. Create `docs/tasks.E1.atomize.md` (break into implementation tasks)
-2. Proceed to Atomize stage (detailed task breakdown)
-3. Update `.llm/state.json` with E1 APPROVED status
-4. Begin implementation with Phase 1 (README + Setup Guide + Architecture)

package/docs/charter.F1.align.yaml

@@ -1,193 +0,0 @@
-task: F1
-name: "结构化日志增强 (Structured Logging Enhancement)"
-parent_stage: "F - Observability & Artifacts"
-version: "1.0"
-date: "2025-10-03"
-status: "Align"
-
-# ==============================================================================
-# 1. MISSION & SCOPE
-# ==============================================================================
-
-mission: |
-  增强现有日志系统，为每个 MCP 工具调用自动记录结构化信息（工具名、参数、
-  开始/结束时间、耗时、状态、错误），支持控制台输出格式化和可选的文件持久化，
-  提供完整的操作审计和调试能力。
-
-goals:
-  - id: G1
-    description: "自动记录工具调用生命周期"
-    rationale: "每个工具调用应自动记录 START/END 事件，无需手动编写日志代码"
-    acceptance_criteria:
-      - "工具调用前自动记录 START 日志（工具名、参数）"
-      - "工具调用后自动记录 END 日志（工具名、结果、耗时）"
-      - "工具调用失败时记录 ERROR 日志（错误信息、堆栈）"
-      - "日志中包含 sessionId 和 timestamp"
-
-  - id: G2
-    description: "结构化日志格式"
-    rationale: "日志应易于机器解析（JSON）和人类阅读（格式化文本）"
-    acceptance_criteria:
-      - "每条日志为 JSON 对象（timestamp, level, sessionId, toolName, message, context, duration）"
-      - "控制台输出格式化为易读文本"
-      - "支持日志级别过滤（DEBUG, INFO, WARN, ERROR）"
-
-  - id: G3
-    description: "可选的文件持久化"
-    rationale: "长时间测试或 CI 环境需要保存日志到文件"
-    acceptance_criteria:
-      - "通过配置启用文件日志（默认禁用）"
-      - "日志文件按会话分离（outputDir/logs/session-{sessionId}.log）"
-      - "文件日志为 JSON Lines 格式（每行一个 JSON 对象）"
-
-non_goals:
-  - "日志轮转（依赖外部工具如 logrotate）"
-  - "日志查询 API（用户使用 jq/grep 等工具）"
-  - "实时日志流传输"
-  - "日志加密"
-
-# ==============================================================================
-# 2. CONTEXT & CONSTRAINTS
-# ==============================================================================
-
-context:
-  current_state: |
-    - ConsoleLogger 已实现基础功能（info/warn/error/debug）
-    - 当前日志输出到 stderr，格式为：timestamp LEVEL [sessionId] [toolName]: message {context}
-    - 工具调用需要手动添加日志语句
-    - 无耗时统计
-    - 无文件持久化
-
-  dependencies:
-    - "B4: Logger 接口定义（src/types.ts:Logger）"
-    - "E1-E4: 配置系统（可配置 logLevel, enableFileLog, outputDir）"
-    - "C5: 工具注册器（src/tools/index.ts - 需集成自动日志）"
-
-constraints:
-  technical:
-    - "日志不能阻塞工具执行（异步写入）"
-    - "保持 Logger 接口向后兼容"
-    - "文件写入错误不应中断工具执行"
-
-  business:
-    - "文件日志默认禁用（避免未预期的磁盘写入）"
-    - "不破坏现有 395 个单元测试"
-
-  timeline:
-    - "预计完成时间：1-1.5 小时"
-
-# ==============================================================================
-# 3. SUCCESS CRITERIA
-# ==============================================================================
-
-success_criteria:
-  functional:
-    - id: SC1
-      description: "自动日志注入"
-      verification: "调用任意工具，验证 START/END 日志自动出现"
-
-    - id: SC2
-      description: "结构化信息完整"
-      verification: "检查日志包含所有必需字段（timestamp, level, sessionId, toolName, duration）"
-
-    - id: SC3
-      description: "文件持久化可选"
-      verification: "启用 enableFileLog，验证日志写入文件；禁用时不写入"
-
-  non_functional:
-    - id: NFR1
-      description: "性能开销 <5%"
-      verification: "对比启用/禁用增强日志的工具执行时间"
-
-    - id: NFR2
-      description: "向后兼容"
-      verification: "所有现有测试通过"
-
-# ==============================================================================
-# 4. RISKS & MITIGATION
-# ==============================================================================
-
-risks:
-  - id: R1
-    description: "文件写入失败（磁盘满、权限问题）"
-    probability: "Low"
-    impact: "Low"
-    mitigation: "捕获文件写入异常，仅记录 stderr 警告，不中断工具执行"
-
-  - id: R2
-    description: "日志输出影响性能"
-    probability: "Medium"
-    impact: "Medium"
-    mitigation: "异步文件写入，批量缓冲（每 100 条或 5 秒刷新）"
-
-# ==============================================================================
-# 5. DELIVERABLES
-# ==============================================================================
-
-deliverables:
-  code:
-    - path: "src/core/logger.ts"
-      description: "增强 ConsoleLogger：添加文件写入、批量缓冲"
-      type: "enhancement"
-
-    - path: "src/core/tool-logger.ts"
-      description: "工具调用日志包装器（auto-log wrapper）"
-      type: "new"
-
-    - path: "src/tools/index.ts"
-      description: "集成 tool-logger 到工具调用流程"
-      type: "integration"
-
-    - path: "src/types.ts"
-      description: "新增 ToolLogEntry, LoggerConfig 类型"
-      type: "enhancement"
-
-  tests:
-    - path: "tests/unit/logger-enhanced.test.ts"
-      description: "增强日志功能测试（文件写入、缓冲、耗时）"
-      estimated_tests: 15
-
-    - path: "tests/unit/tool-logger.test.ts"
-      description: "工具调用日志包装器测试"
-      estimated_tests: 10
-
-  docs:
-    - path: "docs/observability.md"
-      description: "F1 部分：结构化日志配置和使用"
-
-# ==============================================================================
-# 6. OPEN QUESTIONS
-# ==============================================================================
-
-open_questions:
-  - question: "日志缓冲策略？"
-    proposed_answer: "100 条或 5 秒，先达到为准"
-    status: "proposed"
-
-  - question: "日志文件最大大小？"
-    proposed_answer: "单文件 10MB，超过则警告（不自动轮转）"
-    status: "proposed"
-
-# ==============================================================================
-# 7. APPROVAL CHECKLIST
-# ==============================================================================
-
-approval_checklist:
-  - [ ] Goals 清晰且可衡量
-  - [ ] Success criteria 可验证
-  - [ ] Risks 已识别
-  - [ ] Deliverables 完整
-  - [ ] Open questions 已解决
-
-# ==============================================================================
-# METADATA
-# ==============================================================================
-
-metadata:
-  created_by: "ClaudeCode"
-  created_at: "2025-10-03T02:30:00Z"
-  task: "F1 - Structured Logging"
-  parent_stage: "F - Observability & Artifacts"
-  estimated_effort: "1-1.5 hours"
-  priority: "HIGH"
-  status: "Ready for Architect"