Repository navigation
docs: refactor white-book into technical library (WebOS Architecture) - #176
Merged
Merged
Conversation
Contributor
Author
Documentation Update Report (Gap Analysis Completed)I have successfully performed a deep gap analysis and filled the missing documentation sections (reaching ~90% completeness). Newly Added Sections
The documentation now deeply reflects the actual codebase structure and logic. |
Contributor
Author
Documentation Update Report (Phase 2 - Deep Coverage)I have further expanded the documentation to reach ~95% coverage, specifically targeting the State Management, Platform Services, and UI component layers. Newly Added Books & Chapters
The White Book is now a comprehensive technical library, with every major subsystem documented and mapped to code. |
Contributor
Author
Documentation Update Report (Phase 3 - Service Layer Coverage)I have closed the remaining gaps in the directory by introducing a new Book: ****. Newly Added Book: Service ReferenceThis book documents the core business logic that doesn't fit into Drivers (Chain Adapters) or Wallet Core.
Coverage Status
The documentation is now fully aligned with the "WebOS" architectural vision. |
Contributor
Author
Documentation Update Report (Phase 4 - Link Integrity & Shell Coverage)I have completed the final refinements to the documentation structure. 1. Link Integrity
2. Shell & UI Coverage
3. Architecture Map
The PR is now ready for final review and merge. It represents a complete digital twin of the codebase. |
Gaubee
force-pushed
the
docs/refactor-whitebook-175
branch
4 times, most recently
from
January 8, 2026 05:08
5e34a44 to
01a3ddf
Compare
- Reorganize docs into 8 books (Manifesto, Kernel, Drivers, UI, Wallet, DApp, Shell, DevOps) - Implement 'Deep-Atomic Hierarchy' for better AI context retrieval - Map documentation structure to codebase architecture (WebOS paradigm)
- Added Book E3: Documentation Guide (Style, Structure) - Added deep technical content for Kernel Reference (Process State Machine, Window Model) - Added deep technical content for Driver Reference (ApiProvider Spec) - Added deep technical content for Wallet Guide (Secure Storage Model) - Reversed engineered details from source code (miniapp-runtime, chain-adapter, wallet-storage)
- Add 01-Wallet-Asset.md: wallet, asset, token components - Add 02-Transaction-Transfer.md: transaction history & transfer flow - Add 03-Onboarding-Security.md: onboarding, security, authorize, migration - Add 04-Ecosystem.md: miniapp ecosystem components - Add 05-Settings-Notification.md: settings, notification, contact - Update README.md with full component index
Major additions: - 00-Manifesto/00-Index.md: Master documentation index with source mapping - 03-UI-Ref: Complete Primitives (18) and Composites (25) indexes - 05-State-Ref: Full state management docs (10 stores, 10 queries) - 06-Service-Ref: Service layer index (35 services, 160 files) - Wallet Storage service with encryption details - Chain Adapter architecture and interfaces - EVM adapter implementation - API Providers (Etherscan, BlockCypher, TronGrid) - MiniApp Runtime lifecycle management - Ecosystem PostMessage bridge - Platform services overview - 12-Shell-Guide: Complete navigation documentation - 31 Activities with routes and params - 27 Sheets/Jobs with routes and params - Full navigation flow diagrams Coverage: 114 components, 160 services, 61 pages documented
Chain Adapters: - 03-Bitcoin.md: UTXO model, BIP84/SegWit, mempool.space API - 04-Tron.md: TRC-20, Energy/Bandwidth model, TronGrid API - 05-BioForest.md: Ed25519, AST tokens, fixed fee model Components: - 01-Wallet-Components.md: WalletCard 3D effects, 14 components - 02-Transaction-Components.md: TransactionList with date grouping State Management: - 02-ChainConfig-Store.md: Chain configuration management - 02-TransactionHistory-Query.md: Filtering and caching Platform Services: - 01-Biometric.md: WebAuthn, Face ID, fingerprint - 02-Camera.md: QR scanning, BarcodeDetector API
- Queries: Price, ExchangeRate, Staking (3 files) - Stores: Preferences, AddressBook, Notification, Ecosystem, SecurityPassword (5 files) - Platform Services: Haptics, Clipboard, Toast (3 files)
- Finance: CurrencyExchange, Staking, Transaction (3 files) - Platform: SecureStorage (1 file) - Migration: MpayMigration (1 file) - Authorize: PlaocAdapter (1 file) - BioForest: SDK, API Client (2 files)
Components (16 files): - Asset, Authorize, Common, Wallet, Transaction, Transfer - Security, Onboarding, Ecosystem, Layout, Token - Notification, Migration, UI-Primitives, Contact - Complete index with 238 components mapped Navigation (2 files): - All 29 Activities documented - All 28 Sheets documented
- useSend (7 files): transfer flow with BioForest/Web3/Mock support - useAssets, usePriceService, useExchangeRate - Security: useSecurityPassword, useMnemonicVerification - UI: useCardInteraction, useMonochromeMask, useWalletTheme - Navigation: useNavigation (Stackflow wrapper)
Queries (4 files): - AddressTransactions: multi-chain transaction history - AddressBalance: any address balance query - ChainConfig: local/remote config with ETag - SecurityPassword: BioForest secondPublicKey Types (4 files): - Amount: immutable precise calculations with Big.js - Asset: token info, fiat formatting - Staking: cross-chain mint/burn types - Index: type design principles
- Add design principles (trust-first, progressive complexity) - Add theme colors documentation with OKLCH color space - Add interaction specs (touch, gesture, animation, a11y) - Add product vision document - Add behavior constraints (MUST/SHOULD/MAY) to Wallet components - Update Foundation index and Manifesto README
Security Reference (08-Security-Ref/): - Key management: BIP39/BIP44, encryption, pattern lock - Authentication: wallet lock, biometric, auto-lock - DWEB authorization: Plaoc protocol, address/signature auth - Security audit: checklist, attack prevention, compliance Appendix (99-Appendix/): - Glossary: blockchain, tech stack, security terms - Chain networks: BFM, EVM, testnet configurations - State machines: transfer, wallet creation, DWEB auth, app lock - Edge cases: wallet, transfer, network, auth, display limits
i18n Reference (09-i18n-Ref/): - Language support: 6 languages including RTL Arabic - Detection rules and language family mapping - Translation resource naming conventions - RTL layout with CSS logical properties - Localization: number/date formatting, terminology Testing Strategy (90-DevOps/02-Testing/): - Three-layer testing: unit → component → E2E - Storybook + Vitest integration - Coverage targets (70%) - Priority levels (P0-P3) - Mock and selector conventions
New commands: - pnpm agent docs validate: Check broken links, missing entries, orphan docs - pnpm agent docs related -p <path>: Find related documentation for code/doc - pnpm agent docs graph: Output relationship graph (json/mermaid) - pnpm agent docs sync: Sync component/service lists from source code Features: - Builds bidirectional relationship graph (docs ↔ source code) - Detects orphan documents (no references) - Validates GitHub source links - Helps AI find relevant context when modifying code
Core modules: - common/mcp/base-mcp.ts - MCP server framework with defineTool() - common/workflow/base-workflow.ts - CLI workflow framework with defineWorkflow() - common/async-context.ts - AsyncLocalStorage-based context - common/preferences.ts - Hot-reloadable preferences management - meta/lib/scanner.ts - File scanner for MCPs/workflows Adapted for Node.js/Bun runtime (originally Deno)
New commands: - pnpm agent:flow - CLI workflow mode (replaces agent in future) - pnpm agent:mcp - MCP server mode (for AI assistants) Tools provided via both CLI and MCP: - whitebook_toc, whitebook_chapter, whitebook_search - practice_list, practice_add, practice_remove, practice_update - roadmap_list, roadmap_stats Architecture: Three-in-one (白皮书 + 源代码 + 测试), deprecated openspec
…create best-practices file
…ture Architecture: - mcps/*.mcp.ts - Each domain has its own MCP with defineTool() - meta/index.ts - Unified export, tool discovery - workflows/agent.workflow.ts - Compose MCP tools via tool.call() MCPs: - whitebook.mcp.ts - toc, chapter, search, knowledgeMap - practice.mcp.ts - list, add, remove, update - roadmap.mcp.ts - list, stats, current Workflow now calls MCP tools instead of raw functions, enabling consistent behavior between CLI and MCP modes.
- Remove fixed priority system - Use directory array order for merge (first wins) - Add createScanner() factory for flexible configuration - Support recursive directory scanning - Enable merging scripts/agent-flow + packages/flow
Meta MCP provides: - workflow(name, args): Execute any discovered workflow - reload(): Refresh workflow list - list(): List all available workflows agent.mcp now uses buildMetaMcp() to: 1. Auto-discover workflows from directories 2. Expose workflow execution to AI 3. Include direct MCP tools (whitebook, practice, roadmap)
- Remove mcps/agent.mcp.ts (redundant) - Add server.ts that uses buildMetaMcp() directly - Update package.json agent:mcp script
- Use official @modelcontextprotocol/sdk - Adapt Deno.args → process.argv.slice(2) - Adapt Deno.exit → process.exit - Fix zodToJsonSchema for Zod v3 shape() function
…ptation Key features preserved: - Dynamic import + run() execution - Console capture (captureConsole) - process.exit override (ExitError) - Auto-refresh every 30s - Dynamic tool description building
…aggregation
- Remove extraTools from server.ts
- Simplify meta/index.ts to only export tools for internal workflow use
- Add isMain check to agent.workflow.ts to prevent auto-run on import
- AI now uses workflow('agent', [...]) instead of direct tool calls
…s → Meta) ## Changes ### Layer 1: MCPs (原子工具集) - Refactor whitebook.mcp.ts: export pure functions + improve descriptions - Refactor practice.mcp.ts: export pure functions + improve descriptions - Refactor roadmap.mcp.ts: export pure functions + improve descriptions ### Layer 2: Workflows (面向角色) - Add onboarding.workflow.ts: 新上下文入口，替代 pnpm agent readme - Add task.workflow.ts: 任务管理（claim, worktree, pr） ### Layer 3: Meta MCP - Update server.ts: use buildMetaMcp to auto-discover workflows - workflow description now serves as AI entry documentation ### Removed - agent.workflow.ts: functionality split into onboarding + task - meta/index.ts: no longer needed, paths defined in server.ts
- Simplify workflow/mcp descriptions to be concise - Use examples array in workflows for automatic formatting - Dynamic examples generation in meta.mcp.ts - Remove verbose 'how to call' documentation from descriptions
- Restore 07-Best-Practices.md with complete content (26 practices) - Update practice.mcp.ts to support '- xxx' format (original format) - Keep file header with maintenance note
Merged original content from 00-必读/index.md: - 序言：纠正 AI 直觉 - 核心章节速查 - 外部文档链接 - 开发检查清单 - 快速参考代码示例 - 常见问题 Q&A
- Add 06-Service-Ref/01-Service-Definition-System.md (821 lines) Schema-first service definition pattern, middleware system, MockDevTools integration - Add 00-Manifesto/08-User-Stories.md (456 lines) 10 Epics with detailed stories and acceptance criteria
…rst) - start: Create Issue + Branch + Worktree + Draft PR - sync: Sync local plan to Issue Body - submit: Push changes + Mark PR as Ready
…ecycle) 1. Core: - task: Support domain types (ui/service/page) and context injection - investigate: New workflow for requirement analysis and RFC generation - review: New workflow for QA checklist and verification - document: New workflow for whitebook synchronization 2. Infrastructure (MCPs): - git-workflow.mcp: Atomic GitHub/Git operations - whitebook.mcp: Enhanced with 'getRelatedChapters'
- Guide AI to use 'investigate', 'task', 'review' workflows - Emphasize Schema-first and Issue-Driven principles - Remove legacy pnpm agent commands
- Migrate agent entry point to Deno (meta.mcp.ts) - Fix all workflow imports and shebangs - Update packages/flow imports for Deno compatibility - Update package.json scripts
- Migrate agent entry point to Deno (scripts/agent-flow/meta/entry.ts) - Fix all workflow imports and shebangs - Update packages/flow imports for Deno compatibility - Update package.json scripts to use deno run - Verify CLI dispatcher works for all workflows
Gaubee
force-pushed
the
docs/refactor-whitebook-175
branch
from
January 8, 2026 05:14
01a3ddf to
75c4aa2
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
重构背景
现有的白皮书结构松散，无法准确反映 KeyApp 复杂的 WebOS 架构 (Kernel + Shell + Drivers)。为了更好地支持 AI 开发和新成员入职，我们需要构建一个矩阵式的技术丛书。
重构内容 (V11)
将白皮书拆分为 8 本独立专著：
纵向：技术参考 (Technical Reference)
miniapp-runtime，包含进程状态机、窗口管理、沙箱隔离。横向：功能指南 (Feature Guide)
通用：工程与规范
关键改进
src/目录强关联，便于 AI 索引。