@creatoria/miniapp-mcp 0.1.0

package/docs/charter.D3.align.yaml

@@ -0,0 +1,206 @@
+# 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

@@ -0,0 +1,294 @@
+# 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

@@ -0,0 +1,193 @@
+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"