{"id":"dfcf2aba-873b-4600-9b59-40a4071e5dd5","entityType":"agent","slug":"clawhub-fyniujin-kingdoc","name":"kingdoc","canonicalUrl":"https://www.xpersona.co/agent/clawhub-fyniujin-kingdoc","canonicalPath":"/agent/clawhub-fyniujin-kingdoc","generatedAt":"2026-10-10T10:43:54.421Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T05:49:54.203Z","emptyReason":null},"description":"金山文档 AI 协作助手 — 9 品类在线文档全生命周期管理 （文档/智能画布/电子表格/演示文稿/多维表格/收集表/可视化/历史管理/全文搜索/附件）， 深度直连金山文档（WPS）开放平台原生 API，覆盖腾讯文档全部能力 + 金山独有 18 项增强 （回收站、版本历史、格式转换（全格式覆盖 jpg/png/t... Skill: kingdoc Owner: fyniujin Summary: 金山文档 AI 协作助手 — 9 品类在线文档全生命周期管理 （文档/智能画布/电子表格/演示文稿/多维表格/收集表/可视化/历史管理/全文搜索/附件）， 深度直连金山文档（WPS）开放平台原生 API，覆盖腾讯文档全部能力 + 金山独有 18 项增强 （回收站、版本历史、格式转换（全格式覆盖 jpg/png/t... Tags: latest:4.2.0 Version history: v4.2.0 | 2026-09-19T02:32:24.592Z | auto Kingdoc 4.2.0 introduces major enhancements and internal refactoring. - Added 10 new modules, including airscript, knowledge_hub, webhook_cent","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.6K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s177r8w7p1d7cpbys9bn33kwhs89d0xw:kingdoc","sourceUrl":"https://clawhub.ai/fyniujin/kingdoc","homepage":"https://clawhub.ai/fyniujin/skills/kingdoc","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/fyniujin/kingdoc","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/fyniujin/skills/kingdoc","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":64,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"金山文档 AI 协作助手 — 9 品类在线文档全生命周期管理 （文档/智能画布/电子表格/演示文稿/多维表格/收集表/可视化/历史管理/全文搜索/附件）， 深度直连金山文档（WPS）开放平台原生 API，覆盖腾讯文档全部能力 + 金山独有 18 项增强 （回收站、版本历史、格式转换（全格式覆盖 jpg/png/t..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T05:49:54.203Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T05:49:54.203Z","emptyReason":null},"stars":null,"forks":null,"downloads":1641,"packageName":null,"latestVersion":"4.2.0","tractionLabel":"1.6K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T05:49:54.202Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T05:49:54.203Z","lastCrawledAt":"2026-10-10T05:49:54.202Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T05:49:54.202Z","lastVerifiedAt":null,"highlights":[{"version":"4.2.0","createdAt":"2026-09-19T02:32:24.592Z","changelog":"Kingdoc 4.2.0 introduces major enhancements and internal refactoring. - Added 10 new modules, including airscript, knowledge_hub, webhook_center, CRDT table, and compliance_center for expanded functionality. - Significant code cleanup: removed 40 files and restructured OCR, local, and server components. - Improved OCR and document processing flows with updates to multiple engine files. - Updated documentation in README and SKILL.md to reflect new capabilities and usage patterns. - Foundation for future features with modular expansion and webhook/event processing support.","fileCount":85,"zipByteSize":223203},{"version":"4.0.0","createdAt":"2026-09-01T09:31:40.366Z","changelog":"KingDoc 4.0.0 introduces major internal enhancements and expanded engine capabilities. - Added 41 new Python engine module files, expanding support for blocks, categories, local/remote bridges, OCR, quota management, history, and more. - Implemented new support for form analytics, page swapping, and advanced content search. - Multiple engine API components updated, including mcp_server. - Removed legacy documentation file (skill-card.md). - README and SKILL documentation revised for updated feature set.","fileCount":114,"zipByteSize":353333},{"version":"3.9.0","createdAt":"2026-08-24T07:57:56.827Z","changelog":"KingDoc v3.9.0 introduces核心能力增强与编辑体验升级： - 新增块级编辑、本地配额管理、演示页替换，提升结构化编辑和资源管控能力 - 增加“全格式覆盖格式转换”（支持 jpg/png/txt 等），丰富文档处理场景 - 新增引擎模块：blocks.py（块级编辑）、format_converter.py（格式转换）、page_swap.py（演示页处理）、quota_manager.py（配额管理） - 支持段落级文档编辑，实现更细粒度的内容调整替代整文件替换 - 文档描述及功能矩阵同步补充体现新能力 - 清理遗留文档，移除 skill-card.md","fileCount":73,"zipByteSize":156349},{"version":"3.8.0","createdAt":"2026-08-22T12:39:07.590Z","changelog":"KingDoc v3.8.0 introduces major upgrades including a new document type, enhanced editing, and full-text search. - 新增“智能画布”文档品类，支持元素级编辑（CRUD）与 Markdown 增量追加 - 引入“全文搜索”能力，支持本地及云端文档内容检索 - 增强功能矩阵，“9 类文档”全面覆盖，描述项与表格同步更新 - 支持“智能画布元素级编辑”“全文搜索”等 16 项独有增强 - 新增相关模块文件（content_search、element_engine、space_tree 等），移除 skill-card.md - 优化多处文档描述、能力说明与用户操作指南","fileCount":69,"zipByteSize":135189},{"version":"3.7.0","createdAt":"2026-08-20T01:10:51.199Z","changelog":"Major refactor and capability expansion in v3.7.0. - Refactored codebase: consolidated modules under new engine structure, removed legacy files and directories. - Added history management (recycle bin, versions, trash) and multiple new OCR tools (education/formula recognition). - Introduced enhanced document views: base, calendar, Gantt, and Kanban. - Enforced local-first Tesseract OCR (data never leaves device). - Updated documentation (SKILL.md/README.md) to clarify full-lifecycle coverage and highlight new unique features.","fileCount":60,"zipByteSize":107307},{"version":"3.6.0","createdAt":"2026-08-16T10:49:04.031Z","changelog":"KingDoc v3.6.0 adds a fully modular engine directory, enabling local deployments and future cloud sync without code duplication. - New: Added 46+ new engine and kingdoc files for a modular architecture (including APIs, authentication, collaboration, template marketplace, security, rate limiting, update checks, hardware, OCR, and more). - Change: Core engine logic and AI adapters refactored for modularity and better maintainability. - Change: Updated key files (README.md, SKILL.md, main APIs) to reflect the new architecture and usage. - Remove: Deprecated legacy file `skill-card.md`. - All features remain 1:1 compatible, now with improved extendability and local/cloud separation.","fileCount":92,"zipByteSize":211340},{"version":"3.5.0","createdAt":"2026-08-08T14:14:42.362Z","changelog":"KingDoc 3.5.0 introduces major structural enhancements for collaboration and document intelligence. - Added new modules: document categorization, document comparison, and real-time collaboration. - Improved backend processing in mcp_server.py to support new collaboration features. - Updated documentation to reflect latest features; obsolete skill-card.md removed. - Lays groundwork for smarter document handling and enhanced team editing workflows.","fileCount":46,"zipByteSize":98907},{"version":"3.4.0","createdAt":"2026-07-30T03:36:18.790Z","changelog":"Kingdoc 3.4.0 - 新增合规检查（compliance_check.py）及用户敏感词、黑名单、白名单机制，提升安全与内容管理能力 - 增加规范文档（references/format_spec.md）和敏感内容参考文件 - mcp_server.py 及核心文档更新以支持合规与用户校验流程 - skill-card.md 移除，说明转移至其它说明文件 - 文档及说明文档完善，适配新安全与合规功能","fileCount":43,"zipByteSize":87805}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s177r8w7p1d7cpbys9bn33kwhs89d0xw:kingdoc","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-kingdoc/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-kingdoc/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-kingdoc/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-kingdoc/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-kingdoc/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-kingdoc/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T10:43:54.417Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-kingdoc/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-kingdoc/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-kingdoc/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-kingdoc/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T05:49:54.203Z","emptyReason":null},"readme":"Skill: kingdoc\n\nOwner: fyniujin\n\nSummary: 金山文档 AI 协作助手 — 9 品类在线文档全生命周期管理 （文档/智能画布/电子表格/演示文稿/多维表格/收集表/可视化/历史管理/全文搜索/附件）， 深度直连金山文档（WPS）开放平台原生 API，覆盖腾讯文档全部能力 + 金山独有 18 项增强 （回收站、版本历史、格式转换（全格式覆盖 jpg/png/t...\n\nTags: latest:4.2.0\n\nVersion history:\n\nv4.2.0 | 2026-09-19T02:32:24.592Z | auto\n\nKingdoc 4.2.0 introduces major enhancements and internal refactoring.\n\n- Added 10 new modules, including airscript, knowledge_hub, webhook_center, CRDT table, and compliance_center for expanded functionality.\n- Significant code cleanup: removed 40 files and restructured OCR, local, and server components.\n- Improved OCR and document processing flows with updates to multiple engine files.\n- Updated documentation in README and SKILL.md to reflect new capabilities and usage patterns.\n- Foundation for future features with modular expansion and webhook/event processing support.\n\nv4.0.0 | 2026-09-01T09:31:40.366Z | auto\n\nKingDoc 4.0.0 introduces major internal enhancements and expanded engine capabilities.\n\n- Added 41 new Python engine module files, expanding support for blocks, categories, local/remote bridges, OCR, quota management, history, and more.\n- Implemented new support for form analytics, page swapping, and advanced content search.\n- Multiple engine API components updated, including mcp_server.\n- Removed legacy documentation file (skill-card.md).\n- README and SKILL documentation revised for updated feature set.\n\nv3.9.0 | 2026-08-24T07:57:56.827Z | auto\n\nKingDoc v3.9.0 introduces核心能力增强与编辑体验升级：\n\n- 新增块级编辑、本地配额管理、演示页替换，提升结构化编辑和资源管控能力\n- 增加“全格式覆盖格式转换”（支持 jpg/png/txt 等），丰富文档处理场景\n- 新增引擎模块：blocks.py（块级编辑）、format_converter.py（格式转换）、page_swap.py（演示页处理）、quota_manager.py（配额管理）\n- 支持段落级文档编辑，实现更细粒度的内容调整替代整文件替换\n- 文档描述及功能矩阵同步补充体现新能力\n- 清理遗留文档，移除 skill-card.md\n\nv3.8.0 | 2026-08-22T12:39:07.590Z | auto\n\nKingDoc v3.8.0 introduces major upgrades including a new document type, enhanced editing, and full-text search.\n\n- 新增“智能画布”文档品类，支持元素级编辑（CRUD）与 Markdown 增量追加\n- 引入“全文搜索”能力，支持本地及云端文档内容检索\n- 增强功能矩阵，“9 类文档”全面覆盖，描述项与表格同步更新\n- 支持“智能画布元素级编辑”“全文搜索”等 16 项独有增强\n- 新增相关模块文件（content_search、element_engine、space_tree 等），移除 skill-card.md\n- 优化多处文档描述、能力说明与用户操作指南\n\nv3.7.0 | 2026-08-20T01:10:51.199Z | auto\n\nMajor refactor and capability expansion in v3.7.0.\n\n- Refactored codebase: consolidated modules under new engine structure, removed legacy files and directories.\n- Added history management (recycle bin, versions, trash) and multiple new OCR tools (education/formula recognition).\n- Introduced enhanced document views: base, calendar, Gantt, and Kanban.\n- Enforced local-first Tesseract OCR (data never leaves device).\n- Updated documentation (SKILL.md/README.md) to clarify full-lifecycle coverage and highlight new unique features.\n\nv3.6.0 | 2026-08-16T10:49:04.031Z | auto\n\nKingDoc v3.6.0 adds a fully modular engine directory, enabling local deployments and future cloud sync without code duplication.\n\n- New: Added 46+ new engine and kingdoc files for a modular architecture (including APIs, authentication, collaboration, template marketplace, security, rate limiting, update checks, hardware, OCR, and more).\n- Change: Core engine logic and AI adapters refactored for modularity and better maintainability.\n- Change: Updated key files (README.md, SKILL.md, main APIs) to reflect the new architecture and usage.\n- Remove: Deprecated legacy file `skill-card.md`.\n- All features remain 1:1 compatible, now with improved extendability and local/cloud separation.\n\nv3.5.0 | 2026-08-08T14:14:42.362Z | auto\n\nKingDoc 3.5.0 introduces major structural enhancements for collaboration and document intelligence.\n\n- Added new modules: document categorization, document comparison, and real-time collaboration.\n- Improved backend processing in mcp_server.py to support new collaboration features.\n- Updated documentation to reflect latest features; obsolete skill-card.md removed.\n- Lays groundwork for smarter document handling and enhanced team editing workflows.\n\nv3.4.0 | 2026-07-30T03:36:18.790Z | auto\n\nKingdoc 3.4.0\n\n- 新增合规检查（compliance_check.py）及用户敏感词、黑名单、白名单机制，提升安全与内容管理能力\n- 增加规范文档（references/format_spec.md）和敏感内容参考文件\n- mcp_server.py 及核心文档更新以支持合规与用户校验流程\n- skill-card.md 移除，说明转移至其它说明文件\n- 文档及说明文档完善，适配新安全与合规功能\n\nv3.3.0 | 2026-07-21T04:44:40.540Z | auto\n\nKingdoc v3.3.0 introduces collaborative conflict resolution features.\n\n- 新增「协同编辑冲突解决」模块，基于自研 difflib 实现，支持冲突检测、智能合并及可视化 diff，无需外部依赖。\n- engine/conflict_resolver.py 文件加入，实现冲突检测与合并逻辑。\n- 优化和调整 engine/api/mcp_server.py 以对接新冲突解决功能。\n- 文档：README.md、SKILL.md 详细补充了协同编辑冲突相关用法与说明。\n- 移除 skill-card.md 文件。\n\nv3.2.0 | 2026-07-17T08:36:35.551Z | auto\n\nKingDoc v3.2.0 brings local WPS AI abilities with fallback. \n- Added WPS AI toolset (write, analyze, ppt, read, detect_intent) via new `engine/wps_ai/` modules.\n- WPS AI runs locally by default; designed for future backend extensibility without API keys.\n- Updated documentation to describe local-first WPS AI workflow and supported actions.\n- Small internal changes to `engine/api/mcp_server.py`; obsolete file `skill-card.md` removed.\n\nv3.0.0 | 2026-07-12T07:59:46.600Z | auto\n\nKingDoc v3.0.0 — Major Upgrade\n\n- Introduced deep integration with native online document APIs for enhanced real-time editing and collaboration.\n- Added strict \"dangerous operation confirmation\" with explicit prompts before deletes, overwrites, batch actions, and permission changes.\n- Launched local, keyless features: generate DOCX/PPTX, OCR extraction, hardware profiling—all available out-of-the-box, cloud key required only for online actions.\n- Hardware auto-detection now recommends and auto-sets concurrency for optimal performance and stability.\n- Added automatic fallback to cloud OCR or user guidance if Tesseract is missing (no manual setup required).\n- Expanded documentation: added clear natural language usage samples, frequently asked questions, edge-case boundaries, and full workflow cases.\n- Improved file type blocking, enhanced audit trails, and enforced security best practices across potentially risky actions.\n\nv2.3.0 | 2026-07-05T04:28:42.201Z | auto\n\nKingDoc v2.3.0 introduces enhanced document support and upgrades:\n\n- 增加“思维导图(mindmap)”及“流程图(flowchart)”支持，品类从6大类扩充至9大类。\n- 支持本地 Tesseract OCR，实现“图片文字识别”，无需第三方API Key。\n- 丰富工作流范例，加入流程图、思维导图及 HTML/网页剪藏等工作流。\n- 详细标注每一文档品类的“对标腾讯”能力对照及实现方式。\n- 文档结构和说明全面升级，突出 KingDoc 独有能力与腾讯文档差异化。\n- 新增“安装 Tesseract OCR”引导及更多本地化功能说明。\n\nv2.1.0 | 2026-07-02T08:40:29.614Z | user\n\nv2.1.0 — 金山文档 AI 协作助手更新\n\nv2.0.0 | 2026-07-02T05:23:15.557Z | user\n\nv2.0.0 — 金山文档 AI 协作助手：6品类全生命周期管理\n\nArchive index:\n\nArchive v4.2.0: 85 files, 223203 bytes\n\nFiles: engine/__init__.py (57b), engine/airscript.py (16862b), engine/api/__init__.py (26b), engine/api/mcp_server.py (97294b), engine/api/tools.py (11767b), engine/auth.py (2767b), engine/bidata_io.py (19379b), engine/blocks.py (14798b), engine/categories.py (9428b), engine/client.py (2956b), engine/compliance_center.py (10204b), engine/compliance_check.py (20605b), engine/conflict_resolver.py (14007b), engine/content_search/__init__.py (186b), engine/content_search/searcher.py (3879b), engine/crdt_table.py (14335b), engine/cross_compare.py (7683b), engine/dbf_auto.py (13490b), engine/doc_comparator.py (9904b), engine/element_engine/__init__.py (489b), engine/element_engine/editor.py (8867b), engine/exceptions.py (2469b), engine/form_analytics.py (20045b), engine/format_converter.py (29772b), engine/hardware.py (9144b), engine/history/__init__.py (258b), engine/history/manager.py (4177b), engine/history/trash.py (1889b), engine/history/version.py (1946b), engine/knowledge_hub.py (12046b), engine/local_bridge.py (25079b), engine/local/__init__.py (58b), engine/local/generators.py (7739b), engine/local/ocr.py (8881b), engine/memory_bridge.py (17042b), engine/ocr/__init__.py (559b), engine/ocr/education.py (3107b), engine/ocr/formula_recognizer.py (4425b), engine/page_swap.py (14585b), engine/quota_manager.py (18021b), engine/rate_limiter.py (1137b), engine/realtime_collab.py (12651b), engine/security.py (5383b), engine/space_tree/__init__.py (181b), engine/space_tree/manager.py (4291b), engine/template_marketplace.py (9203b), engine/topic_generator.py (7583b), engine/update_check.py (6083b), engine/view_render.py (13218b), engine/views/__init__.py (999b), engine/views/base.py (1224b), engine/views/calendar.py (5336b), engine/views/gantt.py (4831b), engine/views/kanban.py (3237b), engine/webhook_center.py (18682b), engine/wps_ai/__init__.py (75b), engine/wps_ai/adapter.py (3672b), engine/wps_ai/backends/__init__.py (49b), engine/wps_ai/backends/base.py (1601b), engine/wps_ai/backends/local_fallback.py (13830b), engine/wps_ai/capabilities.py (2293b), engine/wps_ai/research_notes.md (1830b), output/test_doc_r3.md (34b), output/test_doc.md (40b), output/test_doc2.md (22b), README.md (8976b), references/auth.md (6713b), references/dbt_references.md (2265b), references/error_codes.md (1247b), references/et_references.md (1646b), references/format_spec.md (627b), references/office_references.md (1335b), references/rate_limit.md (1693b), references/security.md (9332b), references/sensitive_words.txt (806b), references/user_blacklist.txt (123b), references/user_whitelist.txt (123b), references/workflows.md (7668b), scripts/env_check.sh (1542b), scripts/tests/test_file.py (2632b)\n\nFile v4.2.0:SKILL.md\n\n---\nname: kingdoc\nversion: 4.2.0\ndescription: >\n---\n\n\n# KingDoc — 金山文档 AI 协作助手 v3.0.0\n\n> 对标腾讯文档 TENCENT DOCS，功能 1:1 覆盖 + 差异化增强。\n> **v3.0.0 重点：深度直连在线文档原生 API、危险操作强制确认、硬件自适应性能、免密钥本地能力。**\n\n---\n\n## 📣 评测反馈与本轮（v3.0.0）优化说明\n\n本版本针对第三方评测（综合 4.5/5「优秀」）的降分项做了**逐项闭环**：\n\n| 评测降分点 | v3.0.0 优化 |\n|-----------|------------|\n| 某些危险操作缺强制确认，可能误操作 | 新增「危险操作强制确认」铁律与确认清单（见第 6、12 节） |\n| 高级功能需额外装 Tesseract | 本地 OCR **免密钥**优先；未装 Tesseract 时降级云端，都无则给安装指引 |\n| 首次配置需 App Key，对新手复杂 | 明确「本地生成/OCR/硬件画像零配置可用」；云端仅上传/协作需 Key |\n| 能力边界说明少（大文件/失败场景） | 新增「能力边界与失败场景」专章（第 13 节） |\n| 触发方式不清晰（高级功能怎么说） | 新增「自然语言触发示例」专章（第 5 节） |\n| FAQ 不丰富、找不到答案 | 新增 FAQ 专章（第 25 节），安全/错误集中可查 |\n| 缺完整场景案例 | 新增「完整场景案例」专章（第 11 节） |\n| 创造性/增值不足 | 新增硬件自适应性能调度、网页剪藏、批量任务、Webhook 等增值能力 |\n| 性能可能拖累电脑 | 新增硬件自动采集 + 自动分配并发子进程数（第 17 节） |\n\n---\n\n## ⚠️ 首次使用必读\n\n### 1. 申请金山开放平台 App（免费，仅云端协作需要）\n\n**只影响「上传到云端 / 多人协作 / 回收站 / 版本」等联网能力。**\n本地生成文档、本地 OCR、硬件画像**完全不需要 Key，开箱即用**。\n\n申请步骤：\n1. 访问 [金山开放平台](https://developer.kdocs.cn) 并登录金山文档账号\n2. 进入「应用管理」→「创建应用」，获取 **`App ID`** 和 **`App Secret`**\n3. 勾选权限（OAuth Scope）：\n - 必须：`user:file:write`、`user:file:read`、`team:file:write`、`team:file:read`\n - 建议：`user:team:read`、`user:notification:write`\n4. 测试阶段限速 500 次/天，正式版 10 万次/天\n\n### 2. （可选）安装本地 Tesseract OCR\n\n仅「图片文字提取」需要；未装则自动降级云端 OCR 或给指引，**不影响其他功能**。\n\n```bash\n# Windows\nwinget install UB-Mannheim.TesseractOCR\n# macOS\nbrew install tesseract tesseract-lang\n# Linux\nsudo apt-get install tesseract-ocr tesseract-ocr-chi-sim\n```\n\n### 3. 配置并加载\n\n```bash\n# Linux/macOS\nbash setup.sh\n# Windows (PowerShell)\npowershell -ExecutionPolicy Bypass -File setup.ps1\n```\n脚本引导输入 App ID/Secret，自动生成 `config.json`、`mcp-config.json`、模板与图标，并采集本机硬件画像。\n\n---\n\n## 快速开始\n\n| 你想做什么 | 直接对 AI 说 |\n|-----------|-------------|\n| 新建会议纪要 | `\"帮我写一份会议纪要\"` |\n| 创建数据表 | `\"建一个销售数据表格，含产品/销量/金额\"` |\n| 生成 PPT | `\"帮我做一份产品发布 PPT\"` |\n| 生成思维导图 | `\"画一个项目计划的思维导图\"` |\n| 生成流程图 | `\"画一个用户下单流程图\"` |\n| 看文档内容 | `\"看看这个文档说了什么\"` |\n| 搜文件 | `\"搜一下上个月的合同\"` |\n| 上传本地文件 | `\"把这个 PDF 上传到云端\"` |\n| 识别图片文字 | `\"把这张发票的文字提取出来\"` |\n| 恢复误删 | `\"回收站里有没有昨天删的 Word？\"` |\n| 回滚版本 | `\"这份文档改坏了，回退到上周版本\"` |\n| 分享权限 | `\"给张三发个可编辑的链接\"` |\n| 归档文件夹 | `\"把文件移到 2026 项目文件夹\"` |\n| 格式转换 | `\"把这份文档转成 PDF\"` |\n\n---\n\n## 5. 自然语言触发示例（高级功能怎么表达）\n\n为避免「不知道怎么开口」，以下给可直接说的话：\n\n- **批量建表**：`\"新建客户管理多维表格，字段：客户名(文本)、签约金额(数字)、状态(单选)，并一次写入 20 条记录\"`\n- **格式转换**：`\"把《Q2 报告》导出成 PDF\"` / `\"转成 Word 发我\"`\n- **OCR 转文档**：`\"识别这张发票图片，生成一份 Word 报销单\"` / `\"把这张表格图片转成在线电子表格\"`\n- **网页剪藏**：`\"把这个网页 https://... 收藏成金山文档\"` \n- **通知推送**：`\"导入完成后用企微机器人通知我\"` \n- **版本回滚**：`\"列出这份文档的历史版本，回退到 7 月 1 日那版\"` \n- **权限管理**：`\"给团队文件夹『2026 项目』里的文档设置只读\"` \n- **本地免密钥生成**：`\"本地生成一份周报 DOCX，不用上传\"`（无需 App Key）\n\n---\n\n## 安全声明\n\n| 保护项 | 方式 |\n|--------|------|\n| 🔒 删除确认 | 删除走回收站 API，不物理删除 |\n| 🗑️ 软删除+恢复 | `trash.list → trash.recover` |\n| 📝 版本冲突检测 | 写入前获取最新版本号，冲突时提示用户合并 |\n| 🔐 权限前置校验 | 所有写入操作前自动检查权限，无权限拒绝 |\n| ⚡ 限流保护 | 429 自动指数退避重试（最多 5 次） |\n| 🛡️ 文件类型拦截 | 默认禁止上传 .exe/.bat/.ps1/.zip 等（见第 18 节） |\n| 🔑 Token 安全 | Token 仅存在于内存，不落盘 |\n| 📋 审计日志 | 所有写操作记录到本地日志 |\n| 🔀 批量合并 | 50ms 窗口内连续写入自动合并为一次请求 |\n| 🧠 硬件自适应 | 自动按本机 CPU/内存分配并发，不拖累电脑（第 17 节） |\n\n---\n\n## 6. 🚨 危险操作强制确认（v3.0.0 新增铁律）\n\n> 评测指出「部分危险操作缺少强制确认」。以下操作**执行前必须向用户显式确认**，\n> 列出具体影响，待用户明确同意后方可进行；**绝不**静默执行。\n\n| 危险操作 | 确认内容（必须展示给用户） |\n|---------|--------------------------|\n| 删除文件 `kdoc.file.delete` | 文件名 + 大小 + 「将进入回收站，可恢复」 |\n| **彻底删除** `kdoc.trash.destroy` | 文件名 + 「**不可逆**，将永久丢失」⚠️ 二次确认 |\n| 覆盖文件 `kdoc.file.upload` | 原文件版本 + 「覆盖后旧内容进入版本历史」 |\n| 批量操作 `kdoc.batch.*` | 操作类型 + 文件数量 + 文件清单预览 |\n| 权限变更 `kdoc.file.permission` | 目标成员 + 授予/收回的权限 |\n| 清空回收站 | 数量 + 「**不可恢复**」⚠️ |\n| 回滚版本 `kdoc.version.restore` | 目标版本 + 「当前内容将被历史版本替换」 |\n| Webhook 设置 | 回调 URL + 监听事件清单 |\n\n**确认模式**（config.json 可配）：\n```json\n{ \"safety\": { \"confirm_mode\": \"dangerous\", \"dry_run\": false, \"audit_enabled\": true } }\n```\n- `dangerous`（默认）：仅上表危险操作需确认\n- `always`：所有写操作均确认\n- `dry_run: true`：只展示将要执行的操作，不真正调用\n\n---\n\n## 支持的文档类型（9 品类）\n\n| 类型 | doc_type | 推荐度 | 创建 | 编辑 | 对标腾讯 | 实现方式 |\n|------|----------|--------|------|------|---------|---------|\n| 智能文档 | smart_note | ⭐⭐⭐ | ✅ 自动 | ✅ 本地生成+上传 | smartcanvas | Markdown→DOCX→上传覆盖 |\n| 文字文档 | doc | ⭐⭐⭐ | ✅ 自动 | ✅ 本地生成+上传 | doc | python-docx→上传覆盖 |\n| 智能画布 | smart_canvas | ⭐⭐⭐ | ✅ 自动 | ✅ 元素级 CRUD+增量追加 | 智能画布 | element_api + Markdown 追加 |\n| 电子表格 | sheet | ⭐⭐⭐ | ✅ 自动 | ✅ API 精细编辑 | sheet | 金山 et API（单元格/公式） |\n| 演示文稿 | ppt | ⭐⭐⭐ | ✅ 自动 | ✅ 本地生成+上传 | slide | python-pptx→上传覆盖 |\n| 多维表格 | smartsheet | ⭐⭐⭐ | ✅ 自动 | ✅ API 精细编辑 | smartsheet | 金山 dbt API（记录/字段/视图） |\n| 收集表 | form | ⭐⭐⭐ | ✅ 自动 | ✅ API 配置 | form | 金山 form API |\n| 可视化 | visualization | ⭐⭐⭐ | ✅ 自动 | ✅ 本地渲染+上传 | — | mermaid→SVG→上传 |\n| 历史管理 | history_mgmt | ⭐⭐⭐ | — | ✅ 统一管理 | — | 回收站+版本历史统一入口 |\n| 全文搜索 | content_search | ⭐⭐⭐ | — | ✅ 全文搜索 | — | 内容搜索 API（超越腾讯） |\n| 附件 | attachment | ⭐⭐⭐ | ✅ 自动 | — | — | 本地文件直接上传 |\n\n---\n\n## 核心能力矩阵\n\n### 1️⃣ 文档创建（9 品类全覆盖）\n\n| 用户意图 | 品类 | 创建方法 | 编辑方法 |\n|---------|------|---------|---------|\n| 报告/笔记/文章/纪要/markdown | smart_note / doc | `kdoc.file.create` | `kdoc.local.docx.generate` → 上传覆盖 |\n| PPT/幻灯片 | ppt | `kdoc.file.create` | `kdoc.local.pptx.generate` → 上传覆盖 |\n| 数据表格/Excel | sheet | `kdoc.et.create` | `kdoc.et.*` 精细编辑 |\n| 多维表格 | smartsheet | `kdoc.dbt.create` | `kdoc.dbt.*` 精细编辑 |\n| 表单/问卷 | form | `kdoc.form.create` | `kdoc.form.*` 配置 |\n| 思维导图 | mindmap | `kdoc.local.mindmap.generate` → 上传 | 生成 SVG→上传覆盖 |\n| 流程图 | flowchart | `kdoc.local.flowchart.generate` → 上传 | 生成 SVG→上传覆盖 |\n| 上传文件/图片/pdf | attachment | `kdoc.file.upload` | — |\n\n### 2️⃣ 文档编辑（改内容）\n\n先 `kdoc.file.info` 确定品类，再路由对应工具集。**严禁跨品类操作。**\n\n| 原始文档类型 | 编辑工具集 | 编辑粒度 |\n|------------|-----------|---------|\n| 智能文档/文字 | `kdoc.local.docx.generate` → 上传覆盖 | 整文件替换（自动重排） |\n| 演示文稿 | `kdoc.local.pptx.generate` → 上传覆盖 | 整文件替换 |\n| 电子表格 | `kdoc.et.cell.write` / `kdoc.et.range.write` | **单元格级** ✅ |\n| 多维表格 | `kdoc.dbt.record.*` / `kdoc.dbt.field.*` | **记录级** ✅ |\n| 收集表 | `kdoc.form.*` 配置 | 表单配置级 |\n| 思维导图/流程图 | `kdoc.local.mmd.generate` → 上传覆盖 | 整文件替换 |\n\n### 3️⃣ 文件管理\n\n| 动作 | 工具 |\n|------|------|\n| 重命名/移动/删除/复制 | `kdoc.file.*` |\n| 导入（本地→云端） | `kdoc.file.upload` |\n| 导出（云端→本地） | `kdoc.file.download` |\n| 权限/分享链接 | `kdoc.file.permission` / `kdoc.share.*` |\n| 回收站查询/恢复 | `kdoc.trash.list` / `kdoc.trash.recover` |\n| 版本历史/回滚 | `kdoc.version.list` / `kdoc.version.restore` |\n| 批量操作 | `kdoc.batch.create` → `kdoc.batch.query` |\n| 空间管理 | `kdoc.space.*` / `kdoc.folder.*` |\n\n### 4️⃣ 格式转换与 OCR\n\n| 场景 | 工具 | 实现方式 |\n|------|------|---------|\n| 文档→PDF/Word/Excel/PPT | `kdoc.office.convert` | 金山 API |\n| 纯文本提取 | `kdoc.office.extract` | 金山 API |\n| 图片 OCR 文字提取 | `kdoc.local.ocr.extract` | **本地 Tesseract（免密钥）/ 云端降级** |\n| 图片→Word | `kdoc.local.docx.generate(image_ocr=true)` | OCR→生成 DOCX→上传 |\n| 图片→Excel | `kdoc.et.create(data=ocr_table)` | OCR→解析表格→写入 |\n| 网页剪藏 | `kdoc.scrape.url` → `kdoc.file.create` | 抓取→创建文档 |\n| HTML 一键上云 | `kdoc.scrape.html` → `kdoc.file.upload` | 读取本地 HTML→上传 |\n\n### 5️⃣ 扩展能力（金山独有）\n\n| 能力 | 工具 | 说明 |\n|------|------|------|\n| 通知推送 | `kdoc.notification.send` | 企微/钉钉/金山协作机器人 |\n| 多维表格 Webhook | `kdoc.dbt.webhook.set` | 事件驱动监听表格变更 |\n| 空间额度用量 | `kdoc.space.quota` | 企业级管理视角 |\n| 用户信息 | `kdoc.user.info` | 获取用户/团队信息 |\n\n### 6️⃣ 本地免密钥工具（无需 App Key）\n\n| 工具 | 说明 |\n|------|------|\n| `kdoc.local.docx.generate` | 本地生成 DOCX（会议纪要/周报/合同） |\n| `kdoc.local.pptx.generate` | 本地生成 PPTX |\n| `kdoc.local.mindmap.generate` | 本地渲染思维导图 SVG |\n| `kdoc.local.flowchart.generate` | 本地渲染流程图 SVG |\n| `kdoc.local.ocr.extract` | 本地 OCR 提取图片文字 |\n| `kdoc.local.hardware.profile` | 采集本机硬件 + 推荐并发数 |\n\n### 7️⃣ WPS AI 能力（v3.2.0 新增，本地降级优先）\n\n> WPS AI 目前无公开开发者 API，本模块采用**本地降级 + 自研逻辑**实现，零密钥可用。\n> 未来如 WPS AI 开放 API，只需新增后端即可升级，无需改动上层。\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.wps_ai.write` | AI 写作辅助 | polish(润色) / expand(扩写) / shorten(缩写) / continue_write(续写) / rewrite(改写) |\n| `kdoc.wps_ai.analyze` | AI 数据分析 | 自然语言提问 → 基础统计 + 公式建议 |\n| `kdoc.wps_ai.ppt` | AI PPT 生成 | Markdown 大纲 → 自动生成 PPT |\n| `kdoc.wps_ai.read` | AI 阅读助手 | summarize(总结) / qa(问答) / mindmap(思维导图) |\n| `kdoc.wps_ai.detect_intent` | 意图检测 | 识别用户输入匹配的 WPS AI 能力 |\n\n**后端策略**：本地降级优先 → 未来可扩展 WPS Open API / COM 自动化 / Web API\n\n---\n\n## 10. 协同编辑冲突解决（v3.3.0 新增，自研 difflib 实现）\n\n> 多人同时编辑同一文档时经常出现冲突（A 修改了第 3 段，B 也修改了第 3 段）。\n> 本模块提供**冲突检测 + 智能合并 + 可视化 diff + 解决模板**，零外部依赖。\n\n### 10.1 冲突检测\n\n| 用户意图 | 直接对 AI 说 |\n|---------|-------------|\n| 检测冲突 | `「检测这两人修改的冲突」` |\n| 查看差异 | `「对比这两个版本的差异」` |\n| 自动合并 | `「帮我合并这两个版本」` |\n| 保留某版本 | `「保留 A 的版本」` / `「保留 B 的版本」` |\n\n### 10.2 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.conflict.detect` | 冲突检测 | 输入基准版+A版+B版 → 返回冲突块列表+统计 |\n| `kdoc.conflict.merge` | 智能合并 | 无冲突段自动合并，冲突段标注 `<<<<<<< VERSION_A` |\n| `kdoc.conflict.diff` | 冲突可视化 | 生成 Git diff 风格结构化数据 + 可选 HTML |\n| `kdoc.conflict.resolve` | 冲突解决 | keep_a / keep_b / manual / auto_merge |\n\n### 10.3 工作流程\n\n```\n① 检测：kdoc.version.list → 取最近 2-3 个版本 → conflict.detect() → 冲突块列表\n② 合并：conflict.merge() → 自动合并无冲突段 + 标注冲突段 → 合并建议\n③ 可视化：conflict.diff() → Git 风格并排 diff（可导出 HTML）\n④ 解决：用户选模板 → conflict.resolve() → ⚠️ 强制确认 → kdoc.file.upload 覆盖回云端\n```\n\n### 10.4 解决模板\n\n| 策略 | 说明 |\n|------|------|\n| `keep_a` | 保留用户 A 的版本 |\n| `keep_b` | 保留用户 B 的版本 |\n| `manual` | 手动编辑合并版本（需传 `manual_text`） |\n| `auto_merge` | 自动合并（仅无冲突段，冲突段保留标记） |\n\n### 10.5 安全约束\n\n- 合并结果覆盖回云端属于「覆盖文件」危险操作，**必须走强制确认铁律**（见第 6 节）\n- 冲突段**绝不自动覆盖**，必须用户明确选择\n- 大文档 diff 自动分块处理，不拖累电脑（硬件自适应）\n\n---\n\n## 11. 文档内容合规检查（v3.4.0 新增，自研正则+规则引擎）\n\n> 政企客户对文档内容有严格合规要求，手动检查耗时易遗漏。\n> 本模块提供**敏感词扫描 + 数据泄露检测 + 格式规范检查 + 密级标注**，零外部依赖。\n\n### 11.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.compliance.sensitive` | 敏感词扫描 | 输入全文 → 返回命中词+位置+上下文+风险等级 |\n| `kdoc.compliance.leak` | 数据泄露检测 | 扫描手机号/身份证号/银行卡号/邮箱 → 风险等级+脱敏显示 |\n| `kdoc.compliance.format` | 格式规范检查 | 输入文件路径 → 返回不合规清单（支持 DOCX/PPTX/TXT/MD） |\n| `kdoc.compliance.classify` | 密级自动标注 | 输入全文 → 建议密级（公开/内部/秘密/机密） |\n\n### 11.2 工作流程\n\n```\n① 敏感词扫描：kdoc.file.content → 取全文 → compliance.sensitive() → 命中列表+位置\n② 泄露检测：compliance.leak() → 正则匹配手机/身份证/银行卡/邮箱 → 风险等级\n③ 格式检查：kdoc.local.docx 解析 → compliance.format() → 不合规清单\n④ 密级标注：compliance.classify() → 关键词+规则 → 建议密级\n```\n\n### 11.3 敏感词库管理\n\n- **内置词库**：`references/sensitive_words.txt`（适配中国监管要求）\n- **用户黑名单**：`references/user_blacklist.txt`（追加自定义敏感词）\n- **用户白名单**：`references/user_whitelist.txt`（跳过误判词）\n- **定期更新**：替换 `sensitive_words.txt` 即可，无需改代码\n\n### 11.4 数据泄露检测能力\n\n| 类型 | 正则匹配 | 额外校验 | 风险等级 |\n|------|---------|---------|---------|\n| 手机号 | 1[3-9]\\d{9} | — | high |\n| 身份证号 | 18位 | 校验码验证 | critical |\n| 银行卡号 | 16-19位 | Luhn 算法 | critical |\n| 邮箱地址 | 标准邮箱正则 | — | medium |\n| IP地址 | IPv4 | — | low |\n\n### 11.5 格式规范检查\n\n| 检查项 | 规范 | 严重度 |\n|--------|------|--------|\n| 字体 | 宋体 | warning |\n| 字号 | 10-14pt | warning |\n| 行距 | 1.5倍行距 | info |\n| 页边距 | 2.54cm/3.17cm | info |\n| 行长度 | ≤80字符 | info |\n| 标题层级 | 长文档必须有 H1 | warning |\n\n### 11.6 密级标注规则\n\n| 密级 | 关键词示例 |\n|------|-----------|\n| 机密 | 绝密、核心机密、国家安全、军事机密、情报来源 |\n| 秘密 | 商业机密、技术机密、客户名单、未公开财报 |\n| 内部 | 内部资料、内部通知、仅限内部、不得外传 |\n| 公开 | 无匹配关键词 |\n\n---\n\n## 12. 实时协同编辑（v3.5.0 新增，序列 CRDT 自研实现）\n\n> 多人同时编辑同一文档时经常出现冲突（A 修改了第 3 段，B 也修改了第 3 段）。\n> v3.3 冲突解决是事后 difflib 合并，本模块升级为**实时 CRDT 协同**，多人同时编辑无冲突。\n\n### 12.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.realtime.create` | 创建协同文档 | 输入 client_id → 返回文档状态 |\n| `kdoc.realtime.insert` | 插入文本 | 输入位置+文本 → 返回操作列表 |\n| `kdoc.realtime.delete` | 删除文本 | 输入位置+长度 → 返回操作列表 |\n| `kdoc.realtime.get_text` | 获取当前文本 | 输入 client_id → 返回可见文本 |\n| `kdoc.realtime.stats` | 获取统计信息 | 输入 client_id → 返回字符数/操作数 |\n\n### 12.2 核心算法：序列 CRDT\n\n- 每个字符带唯一因果 ID（lamport timestamp + client_id + 序列号）\n- 插入/删除操作满足交换律，顺序无关\n- 删除标记 tombstone（保留因果关系，不真正移除）\n- 最终一致性：所有客户端收敛到相同状态\n- 无需中央服务器协调（P2P 友好）\n\n### 12.3 工作流程\n\n```\n1) kdoc.realtime.create(client_id) → 创建协同文档\n2) 用户 A 插入：kdoc.realtime.insert(\"alice\", 0, \"Hello\")\n3) 用户 B 同时插入：kdoc.realtime.insert(\"bob\", 5, \" World\")\n4) 操作自动广播给所有客户端\n5) kdoc.realtime.get_text(client_id) → 获取一致文本\n```\n\n---\n\n## 13. 文档对比（v3.5.0 新增，复用 difflib 引擎）\n\n> 对应 TOP50「文档对比检测器」，两版文档差异高亮。\n> 复用 conflict_resolver.py 的 difflib 引擎，提供面向用户的对比能力。\n\n### 13.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.compare.diff` | 差异高亮 | 输入两版文本 → 返回差异行+统计+相似度 |\n| `kdoc.compare.summary` | 变更摘要 | 输入两版文本 → 返回增删改统计+关键变化 |\n| `kdoc.compare.export` | 导出报告 | 输入两版文本 → 返回 Markdown/HTML 报告 |\n\n### 13.2 工作流程\n\n```\n1) kdoc.file.content(file_id) → 获取当前版本\n2) kdoc.version.list(file_id) → 获取历史版本\n3) kdoc.compare.diff(current, history) → 差异高亮\n4) kdoc.compare.summary(current, history) → 变更摘要\n5) kdoc.compare.export(current, history, format=\"html\") → 导出报告\n```\n\n---\n\n## 14. 可视化品类合并（v3.5.0 精简 9→8 品类，v3.6.0 进一步精简为 7 品类）\n\n> 为降低认知门槛、统一渲染管线，v3.6.0 将思维导图和流程图合并为「可视化」品类。\n\n### 14.1 合并前后对比\n\n| 合并前（v3.5.0 8 品类） | 合并后（v3.6.0 7 品类） |\n|-------------------------|-------------------------|\n| 文档 / 电子表格 / 演示文稿 / 多维表格 / 收集表 / **思维导图** / **流程图** / 附件 | 文档 / 电子表格 / 演示文稿 / 多维表格 / 收集表 / **可视化** / 附件 |\n\n### 14.2 子命令路由\n\n合并后用户仍可用原有表达方式，引擎自动识别子命令：\n\n| 用户表达 | 品类 | 子命令 |\n|---------|------|--------|\n| \"画一个思维导图\" | visualization | mindmap |\n| \"画一个流程图\" | visualization | flowchart |\n| \"画个脑图\" | visualization | mindmap |\n\n### 14.3 共享渲染管线\n\n```\n用户意图 → 品类路由 → visualization\n ↓\n 子命令识别：mindmap 或 flowchart\n ↓\n 共享 mermaid→SVG 渲染管线\n ↓\n 上传为在线文档\n```\n\n### 14.4 引擎逻辑不变\n\n- 底层仍调用 `engine/local/generators.py` 的 `MindmapGenerator` / `FlowchartGenerator`\n- 渲染方式仍为 mermaid→SVG→上传覆盖\n- 仅改品类元数据（`engine/categories.py`）+ 路由表\n\n---\n\n## 15. WPS AI 深度集成（v3.2 本地降级 → v3.6 段落级 AI 操作）\n\n> v3.2 已实现全文级 AI 写作辅助（polish/expand/shorten），v3.6 升级为**段落级 AI 深度集成**。\n\n### 15.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.wps_ai.rewrite` | AI 段落改写 | formal/casual/concise/elaborate |\n| `kdoc.wps_ai.summarize` | AI 段落总结 | 提取核心要点 |\n| `kdoc.wps_ai.continue` | AI 段落续写 | 根据方向继续写作 |\n\n### 15.2 工作流程\n\n```\n1) 用户在编辑器中选中段落\n2) 触发 AI 操作（改写/总结/续写）\n3) 适配器路由到本地降级后端\n4) 返回处理结果 → 用户确认 → 替换原段落\n5) 未来 WPS AI API 开放后，切换为原生后端，无需改上层代码\n```\n\n### 15.3 后端策略\n\n```\n当前（v3.6）：本地降级占位（返回原文+提示）\n未来：WPS AI 开放 API → 升级为原生后端（实现 WpsAiDeepBackend 接口即可）\n```\n\n---\n\n## 16. 文档模板市场（v3.6.0 新增，行业模板库一键复用）\n\n> 降低文档创建门槛，提供行业模板库 + 变量替换 + 一键生成。\n\n### 16.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.template.list` | 列出所有可用模板 | 可按类别筛选 |\n| `kdoc.template.search` | 搜索模板 | 按关键词搜索 |\n| `kdoc.template.use` | 使用模板 | 变量替换生成文档 |\n| `kdoc.template.refresh` | 刷新模板仓库 | git pull |\n\n### 16.2 模板仓库结构\n\n```\ntemplates/\n├── meeting.md # 会议纪要模板\n├── weekly-report.md # 周报模板\n├── project-plan.md # 项目计划模板\n├── contract.md # 合同模板\n├── pitch-deck.md # 融资路演模板\n└── ...\n```\n\n### 16.3 变量替换\n\n模板使用 `{{变量名}}` 语法，使用时传入变量字典：\n\n```yaml\n---\nname: weekly-report\n分类: 工作汇报\ndescription: 标准周报模板\n---\n\n# {{title}}\n> 作者：{{author}} | 日期：{{date}}\n\n## 本周完成\n{{completed}}\n\n## 下周计划\n{{plan}}\n\n## 风险与风险\n{{risks}}\n```\n\n调用：`kdoc.template.use(\"weekly-report\", {\"title\": \"周报\", \"author\": \"张三\", ...})`\n\n### 16.4 工作流程\n\n```\n1) kdoc.template.list() → 列出可用模板\n2) 用户选择模板 → kdoc.template.use(name, variables)\n3) 引擎替换变量 → 生成 Markdown → 保存到 output/\n4) 返回生成内容 + 文件路径\n5) 可选：上传为在线文档\n```\n\n---\n\n## 17. 多维表格视图增强（v3.7.0 新增，对标 Airtable）\n\n> 对标 Airtable 的多维表格视图能力，支持看板/日历/甘特图三种视图。\n> 零第三方依赖，本地渲染引擎。\n\n### 17.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.view.render` | 视图渲染 | kanban / calendar / gantt |\n| `kdoc.view.list` | 列出可用视图 | 返回视图类型清单 |\n\n### 17.2 视图类型\n\n| 视图 | 说明 | 适用场景 |\n|------|------|---------|\n| 看板 | 按状态字段分组卡片 | 任务管理/项目跟踪 |\n| 日历 | 按日期字段月/周布局 | 日程/活动排期 |\n| 甘特图 | 时间轴+任务依赖 | 项目进度管理 |\n\n### 17.3 工作流程\n\n```\n1) kdoc.dbt.record.query → 获取多维表格记录\n2) kdoc.view.render(view_type=\"kanban\", data={records, fields})\n3) 本地引擎渲染 → 返回结构化 JSON\n4) 前端可视化展示（不依赖外部 API）\n```\n\n### 17.4 硬件自适应\n\n- 视图渲染使用 `hardware.py` 的 `workers` 限制并发\n- 大数据集（>1000 行）自动分页\n\n---\n\n## 18. 手写/公式识别 OCR（v3.7.0 新增，教育场景）\n\n> 覆盖教育手写公式场景，强制本地 Tesseract，数据不出域。\n\n### 18.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.ocr.formula` | 数学公式识别 | 图片 → LaTeX/MathML |\n| `kdoc.ocr.education` | 教育场景统一入口 | 自动判断手写/公式/混合 |\n| `kdoc.local.ocr.extract` | 基础 OCR（v3.7.0 升级） | 强制本地，数据不出域 |\n\n### 18.2 降级策略\n\n```\n优先级：本地 Tesseract → 提示安装（❌ 禁止调用外部 OCR API）\n```\n\n### 18.3 工作流程\n\n```\n1) kdoc.ocr.education(image_path, scene=\"auto\")\n2) 自动判断场景：handwriting / formula / mixed\n3) 返回文本 + LaTeX（如有公式）\n4) 可选：生成 DOCX/PPTX 文档\n```\n\n---\n\n## 19. 历史管理（v3.7.0 新增，合并回收站+版本历史）\n\n> 统一入口管理回收站和版本历史，降低认知门槛。\n\n### 19.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.history.list` | 列出历史记录 | trash / version |\n| `kdoc.history.restore` | 恢复文件 | 还原/回滚 |\n| `kdoc.history.destroy` | ⚠️ 彻底删除 | 仅回收站 |\n\n### 19.2 统一 CLI 接口\n\n```bash\nkdoc history list --from trash|version [--limit 20]\nkdoc history restore --from trash|version [--version ]\nkdoc history destroy # ⚠️ 需二次确认\n```\n\n### 19.3 工作流程\n\n```\n1) kdoc.history.list(\"trash\") → 回收站文件列表\n2) kdoc.history.list(\"version\", file_id=xxx) → 版本历史\n3) kdoc.history.restore(file_id, \"trash\") → 从回收站还原\n4) kdoc.history.restore(file_id, \"version\", version=3) → 回滚到第 3 版\n5) ⚠️ kdoc.history.destroy(file_id) → 彻底删除（需二次确认）\n```\n\n---\n\n## 20. 完整场景案例（v3.0.0 新增，v3.7.0 更新）\n\n### 场景 A：月度销售复盘（全链路）\n```\n1) kdoc.et.create(name=\"2026-07 销售复盘\")\n2) kdoc.et.range.write(sheet_id, \"A1:C21\", 表头+20 行数据) ← 批量写入\n3) kdoc.et.formula.set(sheet_id, \"D2\", \"=C2*0.1\") ← 提成列\n4) kdoc.office.convert(file_id, \"pdf\") ← 导出 PDF\n5) kdoc.notification.send(channel=\"wecom\", content=\"复盘已生成\")\n```\n\n### 场景 B：合同 OCR → 在线文档（免密钥本地优先）\n```\n1) kdoc.local.ocr.extract(\"contract.jpg\") ← 本地 Tesseract，无需 Key\n2) kdoc.local.docx.generate(content=, template=\"contract\")\n3) kdoc.file.upload(file_path=\"output.docx\") ← 上传为在线文档\n```\n\n### 场景 C：项目规划脑图 + 流程图（本地渲染）\n```\n1) kdoc.local.mindmap.generate(code=\"graph TD; 目标-->阶段1; 阶段1-->任务A\")\n2) kdoc.local.flowchart.generate(code=\"flowchart TD; 开始([开始])-->审核{通过?}\")\n3) 分别 kdoc.file.upload 两个 SVG → 在线可视化\n```\n\n### 场景 D：误删恢复（金山独有）\n```\n1) kdoc.trash.list(limit=20)\n2) kdoc.trash.recover(file_id) ← 救回，不丢数据\n```\n\n### 场景 E：大批量导入（硬件自适应）\n```\n1) kdoc.local.hardware.profile → 取得 workers/batch_chunk\n2) 按 batch_chunk 分块调用 kdoc.batch.create\n3) kdoc.batch.query 轮询直至完成（并发不超过 workers，不卡机）\n```\n\n### 场景 F：多人协作冲突解决（v3.3.0 新增）\n```\n1) kdoc.version.list(file_id) → 获取最近 3 个版本（基准版 + A修改 + B修改）\n2) kdoc.conflict.detect(base, a, b) → 检测冲突块\n3) kdoc.conflict.merge(base, a, b) → 自动合并无冲突段 + 标注冲突段\n4) kdoc.conflict.diff(a, b) → Git 风格可视化\n5) 用户选择保留A/保留B/手动合并 → kdoc.conflict.resolve(strategy=\"keep_a\")\n6) ⚠️ 强制确认 → kdoc.file.upload 覆盖回云端\n```\n\n### 场景 G：政企文档合规检查（v3.4.0 新增）\n```\n1) kdoc.file.content(file_id) → 取全文\n2) kdoc.compliance.sensitive(text) → 扫描敏感词（命中\"反动\"、\"毒品\"等）\n3) kdoc.compliance.leak(text) → 检测数据泄露（手机号/身份证号脱敏）\n4) kdoc.compliance.classify(text) → 建议密级（如\"秘密\"）\n5) kdoc.compliance.format(file_path) → 格式规范检查（字体/字号/行距）\n6) 生成合规报告 → 用户确认 → 修复不合规项\n```\n\n### 场景 H：实时协同编辑（v3.5.0 新增）\n```\n1) kdoc.realtime.create(\"alice\") → Alice 创建协同文档\n2) kdoc.realtime.insert(\"alice\", 0, \"项目计划：\") → Alice 插入文本\n3) kdoc.realtime.insert(\"bob\", 5, \"第一阶段\") → Bob 同时插入\n4) kdoc.realtime.get_text(\"alice\") → Alice 看到合并后的文本\n5) kdoc.realtime.stats(\"alice\") → 查看协同统计\n```\n\n### 场景 I：文档对比（v3.5.0 新增）\n```\n1) kdoc.file.content(file_id) → 获取当前版本\n2) kdoc.version.list(file_id) → 获取历史版本\n3) kdoc.compare.diff(current, history) → 差异高亮\n4) kdoc.compare.summary(current, history) → 变更摘要\n5) kdoc.compare.export(current, history, format=\"html\") → 导出 HTML 报告\n```\n\n### 场景 J：7 品类智能路由（v3.6.0 更新）\n```\n1) 用户说\"帮我写一份智能文档\" → kdoc.category_resolve(\"智能文档\")\n → {category: \"doc\", sub_type: \"smart_note\", edit_method: \"local_generate_upload\"}\n2) 用户说\"画一个思维导图\" → kdoc.category_resolve(\"思维导图\")\n → {category: \"visualization\", sub_command: \"mindmap\", edit_method: \"local_render_upload\"}\n3) 用户说\"画一个流程图\" → kdoc.category_resolve(\"流程图\")\n → {category: \"visualization\", sub_command: \"flowchart\", edit_method: \"local_render_upload\"}\n4) kdoc.category_list() → 列出全部 7 品类\n```\n\n### 场景 K：WPS AI 段落改写（v3.6.0 新增）\n```\n1) 用户在编辑器中选中段落\n2) kdoc.wps_ai.rewrite(paragraph=\"这个方案很好，值得推广。\", style=\"formal\")\n → 返回改写后的段落（本地降级占位，API 开放后升级为原生）\n3) 用户确认 → 替换原段落\n```\n\n### 场景 L：模板市场一键生成（v3.6.0 新增）\n```\n1) kdoc.template.list() → 列出所有可用模板\n2) kdoc.template.search(\"周报\") → 搜索周报模板\n3) kdoc.template.use(\"weekly-report\", {\"title\": \"周报\", \"author\": \"张三\"})\n → 变量替换 → 生成 Markdown → 保存到 output/\n4) kdoc.file.upload(output_path) → 上传为在线文档\n```\n\n### 场景 M：多维表格看板视图（v3.7.0 新增）\n```\n1) kdoc.dbt.record.query(table_id) → 获取多维表格记录\n2) kdoc.view.render(view_type=\"kanban\", data={\"records\": [...], \"fields\": [...]})\n → 按\"状态\"字段分组卡片 → 返回看板 JSON\n3) 前端渲染：每列一个状态，卡片可拖拽\n```\n\n### 场景 N：数学公式 OCR 识别（v3.7.0 新增）\n```\n1) kdoc.ocr.formula(\"formula.png\", output_format=\"latex\")\n → 本地 Tesseract + 符号映射 → 返回 LaTeX\n2) kdoc.ocr.education(\"exam.jpg\", scene=\"auto\")\n → 自动判断手写/公式/混合 → 返回文本+LaTeX\n3) 可选：kdoc.local.docx.generate(content=latex) → 生成公式文档\n```\n\n### 场景 O：历史管理——误删恢复与版本回滚（v3.7.0 新增）\n```\n1) kdoc.history.list(\"trash\") → 列出回收站文件\n2) kdoc.history.restore(file_id, \"trash\") → 从回收站还原\n3) kdoc.history.list(\"version\", file_id=xxx) → 列出历史版本\n4) kdoc.history.restore(file_id, \"version\", version=3) → 回滚到第 3 版\n5) ⚠️ kdoc.history.destroy(file_id) → 彻底删除（需二次确认）\n```\n\n---\n\n## 12. 核心规则（铁律）\n\n1. 🚨 **品类隔离**：先 `kdoc.file.info` 识别品类再路由，**严禁跨品类操作**。\n2. 📦 **批量优先**：电子表格/多维表格连续 3+ 写入**必须**用批量接口。\n3. 🔒 **权限前置**：所有写入前**必须**校验权限。\n4. 🔄 **异步轮询**：批量/转换/剪藏**必须**子会话轮询，主会话保持响应。\n5. 🗑️ **软删除**：删除**必须**走回收站 API，不物理删除。\n6. 📝 **审计日志**：所有写操作**必须**记录本地审计日志。\n7. ⚡ **限流退避**：收到 429 **必须**自动指数退避（最多 5 次）。\n8. 🔀 **版本防冲突**：写入前获取 `version`，冲突时提示合并。\n9. ✅ **危险操作强制确认**（v3.0.0）：见第 6 节，**未确认不执行**。\n10. 🧠 **性能不拖累**：批量/渲染并发**不得超过** `kdoc.local.hardware.profile` 给出的 `workers`。\n\n---\n\n## 13. 能力边界与失败场景（v3.0.0 新增，务必看清）\n\n| 场景 | 会发生什么 | 应对 |\n|------|-----------|------|\n| 未配置 App Key | 所有 `*云端*` 工具返回 KD001 友好提示 | 改用 `kdoc.local.*` 免密钥工具 |\n| 文件 > 大文件阈值（默认 100MB，低端机 50MB） | 自动转异步上传 + 进度轮询；超限报 KD008 | 压缩或分卷 |\n| 多人同时编辑 | 写入带版本号，冲突报 KD007 | 拉最新版本→合并→重写 |\n| OCR 识别率低 | 扫描件需 ≥200DPI、光线均匀、无反光 | 提升清晰度或人工校对 |\n| 网络中断 | 自动重试（指数退避），关键操作支持离线暂存 | 稍后重试 |\n| 限流 429 | 自动退避，不会崩溃 | 等待后继续 |\n| 本地未装 Tesseract | OCR 降级云端（需 Key），都无则给安装指引 | 装 Tesseract（免费） |\n| 超大表格（>10 万行） | 分块写入，单批不超过 `batch_chunk` | 分批 |\n| 思维导图/流程图为 SVG 图片 | 无法在金山内二次编辑，保留源 mermaid | 改源码重渲染 |\n| 文字/演示只能整文件替换 | 无法逐段编辑 | 本地改源→重新上传覆盖 |\n\n**明确不支持**：本地直接修改已上传 DOCX/PPTX 的某一段（需整文件重生成）；\n对加密/损坏文件 OCR；超过配额的非付费批量操作。\n\n---\n\n## 14. 风险项与限制\n\n| 风险项 | 影响 | 规避 |\n|--------|------|------|\n| 账号权限未配置 | 无法调用任何 API | 首次使用引导绑定 App |\n| API 配额不足（测试 500/天） | 写入被拒 | 申请正式应用（10 万/天） |\n| 整文件替换限制 | 文字/演示无法逐段编辑 | 降级为「本地生成→上传覆盖」 |\n| OCR 依赖清晰度 | 识别率受图片质量影响 | 提示扫描件 ≥200DPI |\n| SVG 不可二次编辑 | 脑图/流程图为图片 | 导出本地 SVG 保留源 |\n| 大文件超时（>阈值） | 上传失败 | 异步上传 + 轮询 |\n| 版本冲突 | 多人编辑丢数据 | 写入前校验版本号 |\n| 网络依赖 | 云端功能需联网 | 关键操作离线暂存 |\n\n---\n\n## 15. 深度绑定在线文档（v3.0.0 强化）\n\nKingDoc **直连金山文档（WPS）开放平台原生 API**（`https://developer.kdocs.cn/api/v1/openapi`），\n而非简单桥接：\n\n- **原生能力全覆盖**：文件/文件夹/回收站/版本/权限/空间/通知/用户均调用官方端点。\n- **精细编辑**：电子表格走 `et` API（单元格/公式），多维表格走 `dbt` API（记录/字段/视图）。\n- **本地增强**：文字/演示/脑图/流程图用本地库生成**原生格式**（DOCX/PPTX/SVG）后上传覆盖，\n 既保真又免去服务端复杂排版。\n- **政企可用**：国内网络直连、文档全中文、权限模型对齐企业协作。\n\n---\n\n## 16. 四大 MCP 服务（v3.0.0 架构）\n\n| 服务名 | 工具前缀 | 职责 | 对标腾讯 |\n|--------|---------|------|---------|\n| `kingdoc-docs` | `kdoc.file.*` / `folder.*` / `space.*` / `trash.*` / `version.*` / `batch.*` / `notification.*` / `user.*` | 文件管理+回收站+版本+批量+通知+用户 | tencent-docs |\n| `kingdoc-docx` | `kdoc.local.docx.*` | 文字/智能文档/脑图/流程图 本地生成+上传+OCR | doc-mcp |\n| `kingdoc-pptx` | `kdoc.local.pptx.*` | 演示文稿 本地生成+上传 | slide-mcp |\n| `kingdoc-sheet` | `kdoc.et.*` / `kdoc.dbt.*` / `kdoc.form.*` | 表格/多维表/收集表 API 精细编辑 | sheet-mcp |\n\n> 4 个 MCP 服务共享同一 Token，可独立限流、独立降级。\n\n---\n\n## 17. 性能与硬件自适应（v3.0.0 新增，绝不拖累电脑）\n\n`engine/hardware.py` 在首次运行时**自动采集本机 CPU 核数/内存**并计算出安全并发：\n\n| 机器档位 | 并发子进程 `workers` | 批量分块 | 大文件阈值 |\n|---------|---------------------|---------|-----------|\n| 低端（≤2核/<4GB） | 1 | 50 | 50MB |\n| 普通 | min(核数,4) | 200 | 100MB |\n| 高端（≥8核/≥16GB） | min(核数,8) | 500 | 100MB |\n\n- 画像缓存到 `.kingdoc_hardware_profile.json`（30 分钟复用），不频繁探测。\n- 批量写表、脑图/流程图并行渲染**不得超过 `workers`**，保证用户电脑流畅。\n- AI 在执行批量/渲染任务前应调用 `kdoc.local.hardware.profile` 读取参数。\n\n```bash\npython -m engine.hardware # 查看本机画像与推荐参数\n```\n\n---\n\n## 18. 🚫 禁止上传的文件类型（v3.0.0 强化）\n\n为安全，用户「上传附件」默认拦截以下全部类型（来源：产品安全规范）：\n\n1. **Windows 可执行/批处理**：`.bat` `.cmd` `.ps1` `.vbs` `.exe` `.dll` `.lnk` `.msi`\n2. **Office 二进制文档**：`.docx` `.xlsx` `.pptx` `.doc` `.xls` `.ppt` `.xlsm` `.docm` `.pptm`\n3. **二进制镜像/安装包**：`.iso` `.dmg` `.zip` `.rar` `.7z` `.tar` `.gz` `.apk` `.jar`\n4. **系统缓存/隐藏文件**：`.DS_Store` `.git`（目录） `.env` `.log` `.tmp`\n5. **其他风险脚本**：`.sh` `.com` `.scr` `.hta` `.reg`\n\n**内部豁免**：技能「本地生成→上传覆盖」产物（`.docx/.pptx/.xlsx/.pdf/.svg/.png/.txt/.md`\n等）经 `internal=True` 通道上传，**仅限技能自身生成**，用户无法借道上传任意同类文件。\n命中拦截将抛出 `KD009`。详见 `references/security.md`。\n\n---\n\n## 19. 错误码\n\n| 错误码 | 含义 | 解决方案 |\n|--------|------|---------|\n| KD001 | Token 鉴权失败 | 重新执行 `setup` 授权（或改用本地免密钥工具） |\n| KD002 | 权限不足 | 升级应用权限或联系管理员 |\n| KD003 | 配额不足 | 申请提额 |\n| KD004 | 文档类型不匹配 | `kdoc.file.info` 确认品类后按路由表 |\n| KD005 | 文档不存在 | 检查 `file_id` |\n| KD006 | 限流（429） | 自动指数退避重试 |\n| KD007 | 版本冲突 | 获取最新版本后重写 |\n| KD008 | 文件过大 | 走异步上传 |\n| KD009 | 文件类型被拦截 | 见第 18 节禁止类型 |\n| KD010 | 服务暂不可用 | 稍后重试 |\n| KD011 | 参数错误 | 检查 `file_id`/`content` 等必填项 |\n| KD012 | 文件夹不存在 | 检查 `folder_id` |\n| KD013 | 收集表已截止 | 已过截止日期 |\n| KD014 | Webhook 回调失败 | 检查回调 URL |\n| KD015 | 转换失败 | 格式不支持或文件损坏 |\n\n---\n\n## 20. 🔄 自动更新提示与反馈\n\n**每天首次使用自动检查更新**（本地缓存，每天仅查一次，离线不打扰）。\n发现新版本时 AI 会主动提示升级，**不会自动安装**：\n\n```bash\n# 手动检查 / 仅看提醒文案\npython -m engine.update_check --version 3.0.0 --reminder\n```\n\n> 📮 **有更好建议**：njskills@agent.qq.com\n\n---\n\n## 更新日志\n\n| v4.2.0 | 2026-09-19 | 增加：团队知识库模式引擎 `engine/knowledge_hub.py`（空间级本地倒排索引全文检索，可选 jieba 中文分词，权限矩阵先鉴权后检索，无 read 权限文档不进结果集，硬件自适应分块建索引）；增加：政企合规中心引擎 `engine/compliance_center.py`（密级标注公开/内部/秘密/机密随文档元数据落库，敏感词+数据泄露全量扫描聚合报告，数据不出域声明，本地 OCR 强制云端仅元数据）；增加：主题一键生成引擎 `engine/topic_generator.py`（WPS AI 适配层 generate：大纲→智能文档/PPT/表格初稿，本地降级模板驱动+分段生成，真源可用无缝切换）；增加：跨品类对比与时间线引擎 `engine/cross_compare.py`（版本历史轮询→who/when/what 时间线，表格/多维表格单元格级 diff 视图，跨品类差异化）；优化：OCR 收敛为唯一入口 `engine/local/ocr.py`（删除重复维护的 `engine/ocr/local_ocr.py`，优先桥接 wps-office-suite OCR，未装则 Tesseract 最小兜底，数据不出域）；增加：MCP 工具 19 个（kdoc.khub.* 4 个、kdoc.compliance.* 5 个、kdoc.topic.* 2 个、kdoc.compare.* 3 个、kdoc.ocr_bridge_status 1 个、复用 kdoc.local.ocr.extract_text_bridged）；增加：知识中枢/政企合规/主题生成/跨品类对比/OCR 桥接场景案例；优化：SKILL.md 版本号 4.1.0→4.2.0；优化：description 增强到 30 项增强 |\n| v4.1.0 | 2026-09-08 | 增加：AirScript 在线自动化引擎 `engine/airscript.py`（自然语言→脚本生成→预检（危险操作拦截）→用户确认→在线执行；能力域：定时通知/数据汇总/表格批量操作/字段计算；SQLite 执行历史+待确认队列）；增加：多维表格字段自动化引擎 `engine/dbf_auto.py`（公式字段/关联字段/汇总字段创建与批量填充，16 种字段类型，硬件自适应削峰）；增加：视图渲染引擎 `engine/view_render.py`（看板 matplotlib 柱图 + 甘特 mermaid 时间线，硬件自适应渲染并发）；增加：CRDT 表格扩展引擎 `engine/crdt_table.py`（单元格级操作日志 + 向量时钟，冲突时保留双方并标记，支持电子表格/多维表格/智能文档）；增加：Excel/CSV 双向导入导出引擎 `engine/bidata_io.py`（openpyxl 读写，date/link/select/person 四类字段序列化规则文档化，配额削峰）；增加：Webhook 与通知中心引擎 `engine/webhook_center.py`（新增/修改/删除事件订阅，HMAC 签名校验 + SQLite 去重队列，金山协作/企微/钉钉三通道分发，zwjh 记忆桥接）；增加：MCP 工具 24 个（kdoc.airscript.* 7 个、kdoc.dbf.* 5 个、kdoc.view.* 3 个、kdoc.crdt_table.* 6 个、kdoc.bidata.* 5 个、kdoc.webhook.* 8 个）；增加：AirScript/多维表格/视图渲染/CRDT/Webhook 场景案例；优化：SKILL.md 版本号 4.0.0→4.1.0；优化：description 增强到 24 项增强 |\n| v4.0.0 | 2026-08-31 | 增加：本地桥接引擎 `engine/local_bridge.py`（wps-office-suite 双向互通：白名单探测 + SQLite 映射表 + 下行拉取/处理/覆盖 + 上行 mtime 监听同步 + JSON 契约 + 子进程超时自动关闭）；增加：记忆桥接引擎 `engine/memory_bridge.py`（zwjh 记忆库打通：白名单探测 + stdio JSON-RPC 调用 deposit + 关键事件写入长期记忆 + 未安装→本地待迁移日志 + 一次性导入）；增加：表单答卷收集统计 `engine/form_analytics.py`（答卷列表/内容接口 + 按题统计 + 交叉分析 + 未填名单 + 图表生成 + 导出 CSV/Excel + 写回智能文档）；增加：MCP 工具 12 个（kdoc.bridge.* 5 个、kdoc.memory.* 3 个、kdoc.form.* 4 个）；增加：桥接/记忆/表单场景案例；优化：SKILL.md 版本号 3.9.0→4.0.0；优化：description 增强到 21 项增强 |\n| v3.9.0 | 2026-08-24 | 增加：块级编辑引擎 `engine/blocks.py`（段落级在线编辑，block_id CRUD，块类型映射表，未知块类型跳过不中断）；增加：演示页替换引擎 `engine/page_swap.py`（双路径自动选择：页级更新/整文件替换 + 页数校验 diff）；增加：配额管理器 `engine/quota_manager.py`（SQLite 按天计数 500 次/天 + 令牌桶限速 5 req/s + 429 指数退避 + 批量任务硬件自适应削峰）；增加：格式转换引擎 `engine/format_converter.py`（补齐 jpg/png/txt 三类目标格式，全格式覆盖 pdf/jpg/png/txt/docx/xlsx/pptx/html/md，云端优先→本地兜底失败降级链）；增加：MCP 工具 9 个（kdoc.block.* 5 个、kdoc.page_swap 1 个、kdoc.quota.* 3 个、kdoc.office.convert.enhanced 1 个）；增加：块级编辑/页替换/配额管理/格式转换场景案例；优化：SKILL.md 版本号 3.8.0→3.9.0 |\n| v3.8.0 | 2026-08-22 | 增加：智能画布元素级编辑引擎 `engine/element_engine/`（元素CRUD + Markdown追加 + 增量同步，对标腾讯文档·智能画布）；增加：空间节点管理引擎 `engine/space_tree/`（目录树查询 + 链接节点创建 + 递归删除 + 目录可视化）；增加：全文搜索引擎 `engine/content_search/`（文档内容搜索 + 结果定位高亮，超越腾讯）；增加：统一删除入口 `kdoc.file_delete_unified`（合并软删除/彻底删除/直接删除）；增加：MCP 工具 10 个（kdoc.element.* 5 个、kdoc.space.* 4 个、kdoc.content_search.* 2 个、kdoc.file_delete_unified 1 个）；增加：智能画布/空间管理/全文搜索/统一删除场景案例；优化：品类路由表从 8→9（新增 smart_canvas + content_search）；优化：history 模块新增 delete() 统一方法 |\n| v3.7.0 | 2026-08-19 | 增加：多维表格视图增强引擎 `engine/views/`（看板/日历/甘特图三种视图，对标 Airtable，本地渲染，硬件自适应）；增加：手写/公式识别 OCR `engine/ocr/`（数学公式识别 LaTeX/MathML 输出，教育场景统一入口）；增加：历史管理模块 `engine/history/`（合并回收站+版本历史，统一 history list/restore 入口）；增加：MCP 工具 6 个（kdoc.view.* 2 个、kdoc.ocr.* 2 个、kdoc.history.* 3 个）；增加：多维表格视图增强/公式识别/历史管理场景案例；优化：OCR 升级为强制本地模式，数据不出域，移除云端调用路径；优化：品类路由表从 7→8（新增 history_mgmt） |\n| v3.6.0 | 2026-08-16 | 增加：文档模板市场引擎 `engine/template_marketplace.py`（git 仓库管理模板，支持 list/search/use/refresh，变量替换一键生成）；增加：WPS AI 深度集成（段落级 AI 操作：rewrite/summarize/continue，本地降级占位，API 开放后升级为原生）；增加：可视化品类合并 `engine/categories.py`（8→7 品类，合并 mindmap+flowchart→visualization，共享 mermaid 渲染管线）；增加：MCP 工具 7 个（kdoc.template.* 4 个、kdoc.wps_ai.* 3 个）；增加：可视化品类合并/WPS AI 深度集成/模板市场场景案例；优化：品类路由表从 8→7，引擎逻辑不变 |\n| v3.5.0 | 2026-08-08 | 增加：实时协同编辑引擎 `engine/realtime_collab.py`（序列 CRDT 自研实现，零第三方依赖）；增加：文档对比模块 `engine/doc_comparator.py`（复用 difflib，差异高亮+变更摘要+导出）；增加：品类元数据 `engine/categories.py`（9 品类精简为 8 品类，合并 doc+smart_note，子类型自动识别）；增加：MCP 工具 12 个（kdoc.realtime.* 5 个、kdoc.compare.* 3 个、kdoc.category.* 2 个、kdoc.file.* 品类路由更新）；增加：实时协同+文档对比+8 品类智能路由场景案例；优化：品类路由表从 9→8，引擎逻辑不变 |\n| v3.4.0 | 2026-07-30 | 增加：文档内容合规检查模块 `engine/compliance_check.py`（自研正则+规则引擎，零第三方依赖）；增加：敏感词扫描 `kdoc.compliance.sensitive`（内置词库+用户黑白名单）、数据泄露检测 `kdoc.compliance.leak`（手机号/身份证号/银行卡号/邮箱，Luhn+校验码验证）、格式规范检查 `kdoc.compliance.format`（DOCX/PPTX/TXT/MD）、密级自动标注 `kdoc.compliance.classify`（公开/内部/秘密/机密）；增加：合规检查 MCP 工具 4 个；增加：敏感词库 `references/sensitive_words.txt`、格式规范 `references/format_spec.md`、用户黑白名单模板；增加：政企文档合规检查场景案例 |\n| v3.3.0 | 2026-07-21 | 增加：协同编辑冲突解决模块 `engine/conflict_resolver.py`（自研 difflib 实现，零第三方依赖）；增加：冲突检测 `kdoc.conflict.detect`、智能合并 `kdoc.conflict.merge`（自动合并无冲突段 + 标注冲突段）、Git diff 可视化 `kdoc.conflict.diff`、解决模板 `kdoc.conflict.resolve`（keep_a/keep_b/manual/auto_merge）；增加：冲突解决 MCP 工具 4 个；增加：大文档 diff 分块硬件自适应处理；增加：多人协作冲突解决场景案例；优化：冲突段强制用户确认，绝不自动覆盖 |\n| v3.2.0 | 2026-07-17 | 增加：WPS AI 能力适配层（写作辅助/数据分析/PPT 生成/阅读助手），本地降级优先、自研逻辑实现、零密钥可用；增加：WPS AI 适配器 `engine/wps_ai/adapter.py`；增加：本地降级后端 `engine/wps_ai/backends/local_fallback.py`；增加：能力定义与意图映射 `engine/wps_ai/capabilities.py`；增加：WPS AI API 调研记录 `engine/wps_ai/research_notes.md`；优化：MCP Server 注册 5 个 WPS AI 工具；优化：版本号 3.0.0→3.2.0 |\n| v3.1.0 | 2026-07-15 | 增加：wps-office-suite 互通方案调研（已废弃，因平台合规不允许双 skill 互通） |\n| v3.0.0 | 2026-07-12 | 增加：危险操作强制确认铁律与确认清单（删除/彻底删除/覆盖/批量/权限/清空回收站/版本回滚/Webhook）；增加：禁止文件类型扩展至完整 35 类（执行脚本/Office 二进制/归档镜像/系统文件/风险脚本）；增加：用户上传拦截与技能内部生成豁免白名单；增加：`engine/hardware.py` 硬件自适应性能调度（自动采集 CPU/内存，自动分配并发子进程数与批量分块）；增加：本地 OCR 模块 `engine/local/ocr.py`（优先本地 Tesseract，降级云端，给安装指引）；增加：能力边界与失败场景专章；增加：自然语言触发示例专章；增加：完整场景案例专章（5 个端到端场景）；增加：FAQ 专章（8 个高频问题）；补齐：缺失参考文档 `et_references.md`/`office_references.md`/`rate_limit.md`；补齐：技能图标 `assets/icon.png`；补齐：`engine/__init__.py` 与 `engine/api/mcp_server.py`（真实 MCP Server 入口）；优化：MCP Server 深度直连金山文档开放平台原生 API；优化：每日更新提醒 + 反馈邮箱 `njskills@agent.qq.com` |\n| v2.3.0 | 2026-07-05 | 增加：智能文档/思维导图/流程图 3 品类，品类总数 6→9；增加：本地 Tesseract OCR；增加：网页剪藏；增加：HTML 一键上云；优化：MCP 服务拆分 1→4，独立限流/降级 |\n| v2.1.0 | 2026-07-02 | 增加：每日自动更新检查；增加：纯文本提取 API；增加：多维表 Webhook 事件监听；增加：批量异步任务；增加：SKILL.md 首次使用必读引导 |\n| v2.0.0 | 2026-07-02 | 初始版本发布：6 品类 + 40+ MCP 工具 + 5 层安全防御 |\n\n---\n\n## 22. 详细文档参考\n\n| 文档 | 路径 |\n|------|------|\n| 鉴权流程 | `references/auth.md` |\n| 多维表格 API | `references/dbt_references.md` |\n| 电子表格 API | `references/et_references.md` |\n| 文本提取/格式转换 | `references/office_references.md` |\n| 限流/性能/硬件自适应 | `references/rate_limit.md` |\n| 安全设计 | `references/security.md` |\n| 错误码 | `references/error_codes.md` |\n| 常见工作流 | `references/workflows.md` |\n\n---\n\n## 23. 安装说明\n\n**前置要求**：Python 3.10+；云端功能需金山开放平台 App（免费）；OCR 可选装 Tesseract。\n\n```bash\n# Linux / macOS\nbash setup.sh\n# Windows (PowerShell)\npowershell -ExecutionPolicy Bypass -File setup.ps1\n```\n安装后重启 WorkBuddy 生效。本地生成/OCR/硬件画像无需任何配置即可用。\n\n---\n\n## 24. 📮 反馈与建议\n\n本技能持续迭代。有任何功能建议、问题或更好的实现思路，欢迎反馈：\n\n**📧 有更好建议：njskills@agent.qq.com**\n\n也可在每日更新提醒中一键查看新版本。\n\n---\n\n## 25. ❓ FAQ（v3.0.0 新增）\n\n**Q1：没有金山 App Key 能用吗？**\n能。本地生成 DOCX/PPTX、思维导图/流程图 SVG、本地 OCR、硬件画像均零密钥可用；\n仅「上传云端/多人协作/回收站/版本」等联网能力需 Key。\n\n**Q2：为什么删除前要确认？**\n防止误操作。删除进回收站可恢复；「彻底删除」「清空回收站」为不可逆操作，需二次确认（见第 6 节）。\n\n**Q3：OCR 一定要装 Tesseract 吗？**\n首选本地 Tesseract（免费、离线、无 key）。未装时自动降级云端 OCR（需 Key），都无则给出安装指引，不崩溃。\n\n**Q4：大文件传不上去？**\n超过阈值（默认 100MB，低端机 50MB）会自动转异步上传 + 轮询；仍失败请压缩或分卷。\n\n**Q5：会不会把我的电脑拖卡？**\n不会。技能自动按本机硬件分配并发子进程数（见第 17 节），批量/渲染均受限。\n\n**Q6：报 KD009 文件被拦截？**\n你上传的文件属于禁止类型（见第 18 节）。技能自身生成的 docx/pptx/pdf/svg 等不受影响。\n\n**Q7：如何升级？**\n每天首次使用会自动提醒；也可 `python -m engine.update_check --version 3.0.0 --reminder`。\n\n**Q8：文字/演示文档能改其中一段吗？**\n当前为整文件替换模式：本地改源文件→重新上传覆盖。逐段精细编辑需金山在线编辑器。\n\n---\n\n*最后更新：2026-09-19 | v4.2.0*\n\n---\n\n## 26. 块级编辑引擎（v3.9.0 新增，段落级在线编辑）\n\n> v3.8.0 实现了整文件替换和元素级编辑，v3.9.0 进一步下沉到**段落级块编辑**。\n> 以 `block_id` 为操作主键，直接修改文档中的某个段落/标题/列表/表格，无需整文件重生成。\n\n### 26.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.block.list` | 拉取文档块列表 | 返回所有块的结构化数据 |\n| `kdoc.block.replace` | 按 block_id 替换块 | 修改指定块的内容 |\n| `kdoc.block.insert` | 按 block_id 插入新块 | 在指定块前后插入 |\n| `kdoc.block.delete` | 按 block_id 删除块 | 删除指定块 |\n| `kdoc.block.move` | 按 block_id 移动块 | 调整块顺序 |\n\n### 26.2 块类型映射表\n\n| 金山 API 类型 | 内部类型 | 说明 |\n|-------------|---------|------|\n| paragraph | paragraph | 段落 |\n| heading | heading | 标题 |\n| list | list | 列表 |\n| table | table | 表格 |\n| image | image | 图片 |\n| divider | divider | 分隔线 |\n| code | code | 代码块 |\n| quote | quote | 引用 |\n| todo | todo | 待办事项 |\n| callout | callout | 提示框 |\n| equation | equation | 公式 |\n\n**未知块类型处理**：跳过并提示，绝不报错中断。\n\n### 26.3 工作流程\n\n```\n1) kdoc.block.list(file_id) → 获取块列表\n2) 用户定位要修改的 block_id\n3) kdoc.block.replace(file_id, block_id, new_content) → 替换内容\n4) 或 kdoc.block.insert(file_id, block_id, content, position=\"after\") → 插入新块\n5) 或 kdoc.block.delete(file_id, block_id) → 删除块\n6) 或 kdoc.block.move(file_id, block_id, target_id, position) → 移动块\n```\n\n### 26.4 安全约束\n\n- 块级编辑属于「覆盖文件」操作，**必须走强制确认铁律**\n- 批量替换时自动降并发（硬件自适应）\n- 未知块类型跳过并提示，不中断流程\n\n---\n\n## 27. 演示页替换引擎（v3.9.0 新增，双路径自动选择）\n\n> 单页内容本地 python-pptx 重生成后，探测演示 API 是否支持页级更新。\n> 支持则仅覆盖该页，不支持则整文件替换并在完成后 diff 提示页数校验。\n\n### 27.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.page_swap` | 替换指定页 | 自动选择页级更新或整文件替换 |\n\n### 27.2 双路径自动选择\n\n```\n1) 探测 API 是否支持页级更新\n ├── 支持 → 仅覆盖该页（API 调用）\n └── 不支持 → 整文件替换（本地重生成 + 上传覆盖）\n2) 替换完成后执行页数校验 diff\n3) 返回替换结果 + 页数变化提示\n```\n\n### 27.3 安全约束\n\n- 整文件替换属于「覆盖文件」危险操作，**必须走强制确认铁律**\n- 页数校验 diff 确保替换前后页数一致\n- 页数变化时明确提示用户\n\n---\n\n## 28. 配额管理器（v3.9.0 新增，API 配额与限流）\n\n> 保护测试与生产环境，避免 API 配额耗尽导致服务中断。\n\n### 28.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.quota.check` | 检查配额状态 | 返回剩余配额、使用率 |\n| `kdoc.quota.dashboard` | 配额看板 | 配额+令牌桶+硬件+小时分布 |\n| `kdoc.quota.batch_params` | 安全批量参数 | 硬件自适应削峰建议 |\n\n### 28.2 配额三件套\n\n| 组件 | 说明 | 配置 |\n|------|------|------|\n| SQLite 按天计数 | 记录每日请求量 | 默认 500 次/天 |\n| 令牌桶限速 | 控制请求速率 | 默认 5 req/s，突发 10 |\n| 429 指数退避 | 限流时自动重试 | 最多 5 次，最大 60 秒 |\n\n### 28.3 硬件自适应削峰\n\n```\n批量任务 → 读取 hardware.py → 计算安全并发\n → 读取配额余量 → 计算可执行任务数\n → 令牌桶限速 → 控制请求速率\n → 返回建议参数（workers, batch_chunk, 预估时间）\n```\n\n### 28.4 配额看板展示\n\n- 当日配额使用率（进度条）\n- 令牌桶状态（令牌数/速率/突发）\n- 小时分布图（峰值时段）\n- 硬件自适应建议\n- 推荐执行时段\n\n---\n\n## 29. 格式转换补全（v3.9.0 升级，全格式覆盖）\n\n> 补齐 jpg/png/txt 三类缺失的目标格式，全量覆盖参数校验与失败降级链。\n\n### 29.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.office.convert.enhanced` | 格式转换（增强版） | 云端优先 → 本地兜底 |\n\n### 29.2 支持的目标格式（v3.9.0 补齐后）\n\n| 格式 | 说明 | 本地兜底 |\n|------|------|---------|\n| pdf | PDF 文档 | LibreOffice |\n| jpg | JPEG 图片 | Pillow / ImageMagick |\n| png | PNG 图片 | Pillow / ImageMagick |\n| txt | 纯文本 | 直接提取 |\n| docx | Word 文档 | python-docx |\n| xlsx | Excel 表格 | openpyxl |\n| pptx | PPT 演示 | python-pptx |\n| html | HTML 文档 | 简单转换 |\n| md | Markdown | 简单转换 |\n\n### 29.3 失败降级链\n\n```\n云端转换（金山 API）\n ↓ 失败\n本地转换（python-docx / python-pptx / LibreOffice）\n ↓ 失败\n返回错误 + 安装指引\n```\n\n### 29.4 参数校验\n\n- 源格式与目标格式是否支持\n- 本地兜底是否可用（检查依赖）\n- 文件大小是否超限\n- 转换矩阵校验\n\n---\n\n## 30. 本地桥接引擎（v4.0 新增，wps-office-suite 双向互通）\n\n> 与 wps-office-suite 双向互通：白名单探测安装路径 + SQLite 映射表 + 子进程 JSON 契约。\n> 下行：云端→本地→wps 处理→回传覆盖；上行：mtime 监听→上传同步。\n\n### 30.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.bridge.status` | 桥接状态 | wps 安装状态、映射数量 |\n| `kdoc.bridge.download` | 下行：拉取云端文档 | 下载到本地临时目录 |\n| `kdoc.bridge.process` | 下行：wps 处理 | subprocess 调 wps 脚本 |\n| `kdoc.bridge.upload` | 上行：上传覆盖 | 本地文件覆盖云端 |\n| `kdoc.bridge.sync` | 上行：同步 | mtime 变化自动同步 |\n\n### 30.2 双向互通流程\n\n```\n下行（云端→本地→wps→云端）：\n kdoc.bridge.download → 拉取到临时目录\n kdoc.bridge.process → subprocess 调 wps 脚本（JSON 契约）\n kdoc.bridge.upload → 回传覆盖云端\n\n上行（本地变化→云端）：\n 监听映射表 mtime → 变化后自动上传同步\n```\n\n### 30.3 JSON 契约格式\n\n```json\n{\n \"action\": \"analyze|convert|format|extract\",\n \"input\": \"/path/to/local/file\",\n \"output\": \"/path/to/output\",\n \"params\": {}\n}\n```\n\n### 30.4 安全约束\n\n- 子进程超时自动关闭（120 秒）\n- 白名单探测，不扫描全盘\n- 未安装 wps：入口隐藏，云端功能不受影响\n\n---\n\n## 31. 记忆桥接引擎（v4.0 新增，zwjh 记忆库打通）\n\n> 文档关键事件（创建/重要编辑/分享）经 zwjh MCP 总线写入长期记忆。\n> 用户问 zwjh 上周改了什么文档时可答。\n\n### 31.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.memory.status` | 记忆桥接状态 | zwjh 安装状态、待迁移事件数 |\n| `kdoc.memory.deposit` | 发送事件 | 写入 zwjh 或待迁移日志 |\n| `kdoc.memory.migrate` | 一次性导入 | 待迁移事件批量写入 zwjh |\n\n### 31.2 工作流程\n\n```\n文档事件 → deposit_event()\n ├── zwjh 已安装 → stdio JSON-RPC 调用 deposit → 写入长期记忆\n └── zwjh 未安装 → 写入本地待迁移日志 → 未来安装后 migrate 一次性导入\n```\n\n### 31.3 安全约束\n\n- 子进程超时自动关闭（30 秒）\n- 不打包 zwjh 代码，仅走标准 MCP stdio 协议\n- 未安装 zwjh：事件写本地，不丢失\n\n---\n\n## 32. 表单答卷收集统计（v4.0 新增，云端数据本地智能加工）\n\n> 拉取答卷自动聚合（按题统计、交叉分析、未填名单），结果写回智能文档表格并生成图表页。\n\n### 32.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.form.analyze` | 分析答卷 | 按题统计 + 交叉分析 + 未填名单 |\n| `kdoc.form.export` | 导出答卷 | CSV / Excel |\n| `kdoc.form.chart_data` | 图表数据 | 供前端渲染 |\n| `kdoc.form.write_to_doc` | 写回智能文档 | 统计结果写入表格 |\n\n### 32.2 分析能力\n\n| 能力 | 说明 |\n|------|------|\n| 按题统计 | 选择题分布、数值题均值/最大/最小、文本题字数 |\n| 交叉分析 | 两两选择题关联分析 |\n| 未填名单 | 找出未填题的答卷 |\n| 图表生成 | 自动生成图表数据（饼图/柱状图/直方图） |\n\n### 32.3 安全约束\n\n- 硬件自适应：批量拉取时分块处理\n- 导出文件不落地敏感目录\n- 写回智能文档需用户确认\n\n---\n\n## 33. AirScript 在线自动化（v4.1.0 新增，自然语言→脚本→确认→执行）\n\n> 封装金山开放平台 AirScript 脚本创建/执行接口，是在线侧的自动化补全。\n> 自然语言意图 → 脚本生成（本地规则引擎模板，无需外部 LLM）→ 预检（危险操作拦截）→ 用户确认 → 在线执行。\n\n### 33.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.airscript.list_capabilities` | 列出能力域 | 定时通知/数据汇总/表格批量操作/字段计算 |\n| `kdoc.airscript.generate` | 生成脚本 | 根据能力域和参数生成 AirScript |\n| `kdoc.airscript.precheck` | 脚本预检 | 扫描 DELETE/OVERWRITE/DROP 等危险操作 |\n| `kdoc.airscript.submit` | 提交确认 | 提交脚本等待用户确认 |\n| `kdoc.airscript.execute` | 执行脚本 | 用户确认后在线执行 |\n| `kdoc.airscript.history` | 执行历史 | 查看已执行脚本记录 |\n| `kdoc.airscript.pending` | 待确认列表 | 查看待确认脚本 |\n\n### 33.2 安全阀机制\n\n```\n自然语言意图 → 脚本生成 → 预检扫描\n ├── 安全 → 用户确认 → 执行\n └── 危险 → 拦截 + 二次确认\n ├── 用户同意 → 执行\n └── 用户取消 → 终止\n```\n\n### 33.3 危险操作关键词\n\nDELETE / DROP / TRUNCATE / OVERWRITE / REPLACE / REMOVE / CLEAR / UPDATE_ALL / BATCH_DELETE\n\n---\n\n## 34. 多维表格字段自动化（v4.1.0 新增，公式/关联/汇总字段）\n\n> 字段层支持公式字段/关联字段/汇总字段的创建与批量填充，走 et/dbt/form API 记录级接口。\n\n### 34.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.dbf.list_field_types` | 列出字段类型 | 16 种类型 |\n| `kdoc.dbf.list_formula_templates` | 公式模板 | SUM/AVG/COUNT/IF/CONCAT 等 |\n| `kdoc.dbf.create_field` | 创建字段 | 公式/关联/汇总/基础字段 |\n| `kdoc.dbf.batch_fill` | 批量填充 | 硬件自适应削峰 |\n| `kdoc.dbf.history` | 操作历史 | 查看操作记录 |\n\n### 34.2 字段类型\n\ntext / number / select / multi_select / date / person / link / formula / relation / rollup / checkbox / url / email / phone / currency / percent\n\n---\n\n## 35. 视图渲染引擎（v4.1.0 新增，看板/甘特图）\n\n> 视图层本地渲染看板（matplotlib 柱图）与甘特（mermaid 时间线）两种视图导出图片。\n\n### 35.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.view.render_kanban` | 渲染看板 | matplotlib 柱图 |\n| `kdoc.view.render_gantt` | 渲染甘特图 | mermaid 时间线 |\n| `kdoc.view.render_advanced` | 高级渲染 | 直接传入数据渲染 |\n\n### 35.2 硬件自适应\n\n- 渲染并发不超过 hardware.py 的 workers\n- 大数据集自动分页\n\n---\n\n## 36. CRDT 表格扩展（v4.1.0 新增，单元格级无冲突协作）\n\n> 把序列 CRDT 协同从智能文档扩展到电子表格与多维表格。\n> 单元格级操作日志 + 向量时钟，冲突时保留双方并标记。\n\n### 36.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.crdt_table.create` | 创建会话 | 指定品类和客户端 |\n| `kdoc.crdt_table.set_cell` | 设置单元格 | 单元格级操作日志 |\n| `kdoc.crdt_table.get_cell` | 获取单元格 | 含冲突信息 |\n| `kdoc.crdt_table.resolve` | 解决冲突 | 选择保留的值 |\n| `kdoc.crdt_table.get_conflicts` | 获取冲突 | 所有冲突单元格 |\n| `kdoc.crdt_table.state` | 表格状态 | 完整状态 |\n\n### 36.2 冲突解决策略\n\n- 并发操作 → 保留双方修改 → 标记冲突单元格\n- 用户选择保留值 → 解决冲突\n\n---\n\n## 37. Excel/CSV 双向导入导出（v4.1.0 新增，四类字段序列化）\n\n> openpyxl 读写与字段类型映射约定，导入走批量记录创建（复用配额管理器削峰），导出支持视图级筛选快照。\n\n### 37.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.bidata.get_field_rules` | 字段规则 | date/link/select/person 序列化规则 |\n| `kdoc.bidata.import_csv` | 导入 CSV | 硬件自适应削峰 |\n| `kdoc.bidata.import_excel` | 导入 Excel | openpyxl 读写 |\n| `kdoc.bidata.export_csv` | 导出 CSV | 视图级筛选快照 |\n| `kdoc.bidata.export_excel` | 导出 Excel | 视图级筛选快照 |\n\n### 37.2 四类字段序列化规则\n\n| 类型 | 序列化方式 |\n|------|-----------|\n| date | ISO 8601 字符串 (YYYY-MM-DD) |\n| link | JSON {url, title} |\n| select | 逗号分隔字符串 |\n| person | JSON {name, email} |\n\n---\n\n## 38. Webhook 与通知中心（v4.1.0 新增，三通道分发）\n\n> 订阅记录新增/修改/删除三类事件，签名校验 + SQLite 去重队列，通知通道整合金山协作消息/企微/钉钉三路。\n\n### 38.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.webhook.list_events` | 事件类型 | 5 种事件 |\n| `kdoc.webhook.list_channels` | 通知通道 | 3 种通道 |\n| `kdoc.webhook.subscribe` | 订阅事件 | 签名校验 |\n| `kdoc.webhook.unsubscribe` | 取消订阅 | — |\n| `kdoc.webhook.list_subscriptions` | 列出订阅 | — |\n| `kdoc.webhook.process_event` | 处理事件 | 签名校验+去重+分发 |\n| `kdoc.webhook.history` | 事件历史 | — |\n| `kdoc.webhook.statistics` | 统计信息 | — |\n\n### 38.2 通知通道\n\n- 金山协作消息（kdocs）\n- 企业微信（wecom）\n- 钉钉（dingtalk）\n\n### 38.3 安全机制\n\n- HMAC 签名校验\n- SQLite 去重队列（事件哈希去重）\n- 事件可触发写入 zwjh 记忆（桥接存在时）\n\n---\n\n## 39. 团队知识库模式（v4.2.0 新增，知识中枢）\n\n> v4.2 企业文档中枢落地：空间级全文检索 + 权限感知过滤。\n> 遵守平台权限边界——检索前按空间成员权限矩阵过滤，用户无 read 权限的文档不进入结果集。\n\n### 39.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.khub.index` | 构建知识库索引 | 注入文档集建本地倒排索引 |\n| `kdoc.khub.search` | 权限感知全文检索 | 先鉴权后检索，无权限剔除 |\n| `kdoc.khub.permission` | 注入空间权限矩阵 | doc_id→级别（1 read/2 edit/3 admin） |\n| `kdoc.khub.status` | 知识中枢状态 | 文档数/词项/jieba 状态 |\n\n### 39.2 检索流程\n\n1. 分词：中文走 jieba（可选，未装退化为字符级），英文/数字按词边界切分\n2. 倒排取候选：token → 文档集\n3. 权限过滤：依据 `kdoc.khub.permission` 注入的矩阵，剔除无 read 权限文档\n4. 打分排序：命中词频排序，返回 snippet\n\n### 39.3 安全约束\n\n- 权限边界强制：无矩阵登记的空间文档视为无权限，绝不进入结果\n- 硬件自适应：索引构建按 batch_chunk 分块，不卡顿\n- 云端降级：无 backend 时接受外部文档集建本地索引\n\n---\n\n## 40. 政企合规中心（v4.2.0 新增，差异化主战场）\n\n> 把散点合规检查聚合为政企可采购的能力叙事：密级标注 + 全量扫描 + 数据不出域。\n\n### 40.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.compliance.label` | 密级标注落库 | 公开/内部/秘密/机密 |\n| `kdoc.compliance.get` | 查询密级 | 返回已标注级别 |\n| `kdoc.compliance.scan` | 全量扫描报告 | 敏感词+泄露+密级建议聚合 |\n| `kdoc.compliance.declare` | 数据不出域声明 | 本地 OCR 强制、云端仅元数据 |\n| `kdoc.compliance.status` | 合规中心状态 | 级别/引擎清单 |\n\n### 40.2 能力\n\n- 密级标注：随文档元数据落库（SQLite），检索/分享前可被权限层引用\n- 全量扫描：复用 v3.4 合规检查（敏感词 + 手机号/身份证/银行卡号/邮箱 Luhn 校验 + 密级建议），聚合为政企报告\n- 数据不出域：本地 OCR 强制（Tesseract / wps_ocr 均为本地引擎），云端仅同步元数据\n\n---\n\n## 41. 主题一键生成（v4.2.0 新增，WPS AI 对齐）\n\n> 对标腾讯文档·AI 生成：输入主题与大纲要点，本地降级引擎生成初稿，WPS AI 真源开放后无缝切换。\n\n### 41.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.topic.generate` | 主题生成 | 大纲→智能文档/PPT/表格初稿 |\n| `kdoc.topic.status` | 适配层状态 | 当前生效 AI 源（local/wps_ai） |\n\n### 41.2 实现原理\n\n- 适配层：本地生成（零密钥）优先；WPS AI 真源可用时切换，接口统一\n- 三类产出：智能文档（Markdown 初稿）/ PPT（幻灯片大纲）/ 表格（字段+样例行）\n- 本地降级：模板驱动 + 分段生成，硬件自适应不卡顿\n\n---\n\n## 42. 跨品类对比与时间线（v4.2.0 新增，差异化）\n\n> 版本历史轮询→who/when/what 时间线；表格/多维表格品类新增单元格级 diff 视图（跨品类对比是腾讯文档没有的）。\n\n### 42.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.compare.timeline` | 版本时间线 | 逐版本 difflib 生成变更摘要 |\n| `kdoc.compare.cells` | 单元格级 diff | 表格/多维表格跨版本差异 |\n| `kdoc.compare.status` | 对比状态 | 品类/硬件信息 |\n\n### 42.2 实现原理\n\n- 时间线：轮询版本历史（云端）或接受快照列表（本地），逐版本 difflib 生成「谁-何时-改了什么」\n- 单元格 diff：按 (行,列) 比对，标注新增/修改/删除单元格（表格品类差异化能力）\n\n---\n\n## 43. OCR 收敛（v4.2.0 优化，生态专职工具）\n\n> 删除重复维护的本地 OCR 预处理代码，收敛为唯一入口，桥接生态专职工具。\n\n### 43.1 收敛说明\n\n- 删除 `engine/ocr/local_ocr.py` 重复预处理面，公式/教育场景统一 import `engine.local.ocr`\n- 唯一入口 `engine/local/ocr.py`：优先桥接 wps-office-suite OCR（subprocess JSON 契约 {image_path, lang}）\n- 未装 wps 保留 Tesseract 最小兜底；两路均本地引擎，数据不出域\n- MCP `kdoc.local.ocr.extract` 与 `kdoc.ocr.formula`/`kdoc.ocr.education` 均经此入口\n\n### 43.2 安全约束\n\n- 子进程超时自动关闭，不残留\n- 绝不调用任何外部 OCR API（数据不出域）\n\n---\n\n*最后更新：2026-09-19 | v4.2.0*\n\nFile v4.2.0:README.md\n\n# KingDoc — 金山文档 AI 协作助手\n\n> 让 AI 直接操作你的金山在线文档，创建、编辑、管理一站搞定。\n> **v4.2**：知识中枢与政企合规 · 团队知识库模式（空间级倒排检索 + 权限矩阵先鉴权后检索，可选 jieba 中文分词）· 政企合规中心（密级标注公开/内部/秘密/机密落库 + 敏感词/数据泄露全量扫描报告 + 数据不出域声明）· 主题一键生成（WPS AI 适配层 generate：大纲→智能文档/PPT/表格初稿，本地降级可切真源）· 跨品类对比与时间线（版本历史轮询→who/when/what 时间线 + 表格单元格级 diff）· OCR 收敛（唯一入口，优先桥接 wps-office-suite，未装则 Tesseract 最小兜底，数据不出域）· 多维表格深化与在线自动化 · AirScript 脚本引擎（自然语言→脚本→预检→确认→在线执行）· 多维表格字段自动化（公式/关联/汇总字段批量填充）· 视图渲染（matplotlib 看板柱图 + mermaid 甘特时间线）· CRDT 表格扩展（单元格级操作日志 + 向量时钟冲突标记）· Excel/CSV 双向导入导出（date/link/select/person 四类字段序列化）· Webhook 通知中心（新增/修改/删除事件订阅 + 金山协作/企微/钉钉三通道）· 生态互通（wps-office-suite 双向桥接 + zwjh 记忆库打通）· 表单答卷收集统计 · 块级编辑 · 演示页替换 · 配额管理器 · 格式转换全格式覆盖 · 智能画布元素级编辑 · 全文搜索 · 多维表格视图增强 · 手写/公式识别 OCR · 历史管理 · 文档模板市场 · WPS AI 深度集成 · 实时协同编辑 · 文档对比 · 文档合规检查 · 协同冲突解决 · 硬件自适应性能 · 免密钥本地能力。\n\n## ✨ 特性\n\n- 📝 **9 品类全覆盖** — 文档/智能画布/表格/演示/多维表格/收集表/可视化/历史管理/全文搜索/附件\n- 🎨 **智能画布元素级编辑** — 对标腾讯文档·智能画布，元素 CRUD + Markdown 增量追加\n- 🔍 **全文搜索** — 超越腾讯：搜文档内容+结果定位高亮\n- 📊 **多维表格视图增强** — 看板/日历/甘特图，对标 Airtable，本地渲染\n- 🗂️ **空间节点管理** — 目录树/链接节点/递归删除/目录可视化\n- ✍️ **手写/公式识别** — 教育场景，LaTeX/MathML 输出，强制本地 Tesseract\n- 🕐 **历史管理** — 回收站+版本历史统一入口（list/restore/destroy/delete --force）\n- 🔗 **全生命周期** — 创建/编辑/删除/移动/复制/权限/版本历史/回收站\n- 🆚 **对标腾讯文档** — 腾讯有的全有，腾讯没有的也有（回收站/版本/转换/OCR/通知）\n- 🤖 **WPS AI 深度集成** — 写作辅助/数据分析/PPT 生成/阅读助手/段落改写/段落总结/段落续写，本地降级优先、零密钥可用\n- 🔄 **实时协同编辑** — 序列 CRDT 算法，多人同时编辑无冲突\n- 📊 **文档对比** — 差异高亮/变更摘要/导出报告，复用 difflib 引擎\n- 🔄 **协同冲突解决** — 冲突检测/智能合并/Git diff 可视化/解决模板，自研 difflib 实现\n- 📋 **文档合规检查** — 敏感词扫描/数据泄露检测/格式规范检查/密级标注，自研规则引擎\n- 🏢 **团队知识库模式** — 空间级全文检索 + 权限矩阵先鉴权后检索，无权限文档不进结果\n- 🔐 **政企合规中心** — 密级标注落库（公开/内部/秘密/机密）+ 全量扫描报告 + 数据不出域声明\n- 💡 **主题一键生成** — WPS AI 适配层 generate：大纲→智能文档/PPT/表格初稿，本地降级可切真源\n- 🔭 **跨品类对比与时间线** — 版本历史轮询→who/when/what 时间线 + 表格单元格级 diff（腾讯没有的差异化）\n- 🔧 **OCR 收敛** — 唯一入口，优先桥接 wps-office-suite OCR，未装则 Tesseract 最小兜底，数据不出域\n- 🧠 **硬件自适应** — 自动按本机 CPU/内存分配并发，绝不拖累电脑\n- 📁 **文档模板市场** — 行业模板库一键复用，变量替换快速创建文档\n- 🔓 **免密钥本地能力** — 本地生成 DOCX/PPTX/脑图/流程图、本地 OCR、硬件画像、WPS AI，零配置\n- 🛡️ **安全优先** — 软删除/权限前置/限流退避/审计日志/危险操作强制确认/文件类型拦截\n\n## 🚀 快速开始\n\n### 1. 安装\n\n```bash\n# Linux / macOS\nbash D:\\skill\\kingdoc\\setup.sh\n# Windows (PowerShell)\npowershell -ExecutionPolicy Bypass -File D:\\skill\\kingdoc\\setup.ps1\n```\n\n### 2. 配置 App Key（仅云端协作需要）\n\n从 [金山开放平台](https://developer.kdocs.cn) 获取 AppID + AppSecret，安装脚本引导输入。\n**本地生成/OCR/硬件画像/WPS AI 无需 Key。**\n\n### 3. 直接使用\n\n对 WorkBuddy 说：\n- \"帮我写一份会议纪要\" → 本地生成并上传\n- \"把这个 PDF 传到云端\" → 上传（自动拦截禁止类型）\n- \"这份文档改坏了，回退到上周\" → 版本回滚\n- \"识别这张发票的文字\" → 本地 OCR（免密钥）\n- \"帮我润色这段文字\" → WPS AI 写作辅助（免密钥）\n- \"分析这列数据的趋势\" → WPS AI 数据分析（免密钥）\n- \"根据大纲生成 PPT\" → WPS AI PPT 生成（免密钥）\n- \"总结这份文档\" → WPS AI 阅读助手（免密钥）\n- \"把多维表格显示为看板\" → 多维表格视图增强（免密钥）\n- \"识别这个数学公式\" → 公式识别 OCR（免密钥）\n- \"恢复回收站里的文件\" → 历史管理（需 App Key）\n\n## 📖 支持的文档类型（8 品类）\n\n| 类型 | 创建 | 编辑 |\n|------|------|------|\n| 文字/智能文档 | ✅ 自动排版 | ✅ 本地生成+上传覆盖 |\n| 电子表格 | ✅ 自动创建 | ✅ 单元格/公式精细编辑 |\n| 演示文稿 | ✅ 自动排版 | ✅ 本地生成+上传覆盖 |\n| 多维表格 | ✅ 自动创建 | ✅ 记录/字段/视图精细编辑 |\n| 收集表 | ✅ 自动创建 | ✅ 配置+答卷管理 |\n| 可视化（思维导图/流程图） | ✅ 本地渲染 SVG | ✅ 上传覆盖 |\n| 历史管理（回收站+版本） | — | ✅ 列出/恢复/彻底删除/回滚 |\n| 附件上传 | ✅ — | — |\n\n## 📊 多维表格视图增强（v3.7.0 新增）\n\n| 视图 | 说明 | 适用场景 |\n|------|------|---------|\n| 看板 | 按状态字段分组卡片 | 任务管理/项目跟踪 |\n| 日历 | 按日期字段月/周布局 | 日程/活动排期 |\n| 甘特图 | 时间轴+任务依赖 | 项目进度管理 |\n\n## ✍️ 手写/公式识别 OCR（v3.7.0 新增）\n\n| 能力 | 工具 | 输出 |\n|------|------|------|\n| 数学公式识别 | `kdoc.ocr.formula` | LaTeX / MathML |\n| 教育场景 OCR | `kdoc.ocr.education` | 文本 + LaTeX |\n| 基础 OCR | `kdoc.local.ocr.extract` | 文本 |\n\n> 强制本地 Tesseract，数据不出域，零配置可用。\n\n## 🕐 历史管理（v3.7.0 新增）\n\n| 能力 | 工具 | 操作 |\n|------|------|------|\n| 列出历史 | `kdoc.history.list` | trash / version |\n| 恢复文件 | `kdoc.history.restore` | 还原/回滚 |\n| 彻底删除 | `kdoc.history.destroy` | ⚠️ 需二次确认 |\n\n## 🤖 WPS AI 能力（v3.2.0 新增）\n\n| 能力 | 工具 | 操作 |\n|------|------|------|\n| AI 写作辅助 | `kdoc.wps_ai.write` | 润色/扩写/缩写/续写/改写 |\n| AI 数据分析 | `kdoc.wps_ai.analyze` | 自然语言提问 → 统计+公式建议 |\n| AI PPT 生成 | `kdoc.wps_ai.ppt` | Markdown 大纲 → 自动生成 PPT |\n| AI 阅读助手 | `kdoc.wps_ai.read` | 总结/问答/思维导图 |\n| 意图检测 | `kdoc.wps_ai.detect_intent` | 识别用户输入匹配的能力 |\n\n> WPS AI 目前无公开开发者 API，采用**本地降级 + 自研逻辑**实现，零密钥可用。\n> 未来如 WPS AI 开放 API，只需新增后端即可升级。\n\n## 🧠 性能（不拖累电脑）\n\n首次运行自动采集硬件并分配并发子进程数：\n\n| 机器档位 | 并发子进程 | 批量分块 |\n|---------|-----------|---------|\n| 低端（≤2核/<4GB） | 1 | 50 |\n| 普通 | min(核数,4) | 200 |\n| 高端（≥8核/≥16GB） | min(核数,8) | 500 |\n\n## 🚫 安全：禁止上传的文件类型\n\n用户上传默认拦截：`.bat .cmd .ps1 .vbs .exe .dll .lnk .msi`、\n`.docx .xlsx .pptx .doc .xls .ppt .xlsm .docm .pptm`、\n`.iso .dmg .zip .rar .7z .tar .gz .apk .jar`、\n`.DS_Store .git .env .log .tmp`、`.sh .com .scr .hta .reg`。\n技能内部生成的 docx/pptx/pdf/svg 等经豁免通道上传。\n\n## 📚 文档\n\n- [SKILL.md](SKILL.md) — 完整功能参考（含 FAQ、能力边界、场景案例）\n- [references/security.md](references/security.md) — 安全设计\n- [references/rate_limit.md](references/rate_limit.md) — 限流与硬件自适应\n- [references/office_references.md](references/office_references.md) — 文本提取/格式转换\n\n## 🔄 更新与反馈\n\n每天首次使用自动提醒更新（不自动安装）。\n**有更好建议：njskills@agent.qq.com**\n\n## 📄 协议\n\nMIT License\n\nFile v4.2.0:_meta.json\n\n{\n \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n \"slug\": \"kingdoc\",\n \"version\": \"4.2.0\",\n \"publishedAt\": 1789785144592\n}\n\nFile v4.2.0:references/auth.md\n\n# 金山开放平台 API 参考\n\n> 本文档定义 KingDoc 与金山开放平台 API 的对接方式，包括鉴权、请求格式、错误处理和核心接口。\n\n---\n\n## 1. 鉴权概述\n\n### 1.1 获取 AppID / AppSecret\n\n1. 访问 [金山开放平台](https://developer.kdocs.cn)\n2. 创建一个新应用\n3. 获取 `App ID` 和 `App Secret`\n4. 在本地配置：`config.json`\n\n### 1.2 OAuth 2.0 Client Credentials\n\n```\nPOST https://open.kdocs.cn/oauth/token\n\nBody:\n grant_type = client_credentials\n client_id = \n client_secret = \n scope = user:file:write user:file:read team:file:write team:file:read\n```\n\n**响应**：\n\n```json\n{\n \"access_token\": \"eyJhbGciOiJIUzI1NiIs...\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 7200,\n \"scope\": \"user:file:write user:file:read\"\n}\n```\n\n### 1.3 使用 Token\n\n在请求 Header 中传递：\n\n```\nAuthorization: Bearer \n```\n\n---\n\n## 2. 基础 URL\n\n| 环境 | 基础 URL |\n|------|---------|\n| 生产环境 | `https://developer.kdocs.cn/api/v1/openapi` |\n| 沙箱环境 | `https://sandbox.kdocs.cn/api/v1/openapi` |\n\n---\n\n## 3. 统一响应格式\n\n所有 API 返回：\n\n```json\n{\n \"code\": 0,\n \"message\": \"OK\",\n \"data\": { ... },\n \"trace_id\": \"trace_abc123\"\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| code | int | 0 = 成功，非 0 = 错误 |\n| message | string | 状态信息 |\n| data | object | 业务数据（仅成功时存在） |\n| trace_id | string | 追踪 ID，排查问题用 |\n\n---\n\n## 4. 个人文档 API\n\n### 4.1 创建文档\n\n```\nPOST /personal/files\n\nBody:\n{\n \"name\": \"文档标题\",\n \"type\": \"doc\",\n \"folder_id\": \"可选，父文件夹 ID\",\n \"content\": \"可选，初始内容\"\n}\n```\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| name | string | ✅ | 文档标题 |\n| type | string | ✅ | 文档类型：doc / sheet / ppt / dbt / form |\n| folder_id | string | ❌ | 父文件夹 ID（不填为根目录） |\n| content | string | ❌ | 初始内容（Markdown） |\n\n**成功响应**：\n\n```json\n{\n \"code\": 0,\n \"message\": \"OK\",\n \"data\": {\n \"file_id\": \"file_abc123\",\n \"name\": \"文档标题\",\n \"type\": \"doc\",\n \"url\": \"https://docs.wps.cn/doc/file_abc123\",\n \"created_at\": 1719849600\n }\n}\n```\n\n### 4.2 获取文档内容\n\n```\nGET /personal/files/:file_id/content\n```\n\n**响应**：\n\n```json\n{\n \"code\": 0,\n \"data\": {\n \"file_id\": \"file_abc123\",\n \"content\": \"文档正文...\",\n \"version\": 3\n }\n}\n```\n\n### 4.3 更新文档内容\n\n```\nPUT /personal/files/:file_id/content\n\nBody:\n{\n \"content\": \"更新的内容\",\n \"version\": 3\n}\n```\n\n> ⚠️ `version` 必须与当前版本一致，否则返回版本冲突错误。\n\n### 4.4 删除文档（软删除）\n\n```\nDELETE /personal/files/:file_id\n```\n\n> ⚠️ 删除后文档进入回收站，可恢复。\n\n### 4.5 彻底删除\n\n```\nDELETE /personal/files/:file_id/permanent\n```\n\n---\n\n## 5. 空间/文件夹 API\n\n### 5.1 创建文件夹\n\n```\nPOST /personal/folders\n\nBody:\n{\n \"name\": \"文件夹名称\",\n \"parent_id\": \"可选，父文件夹 ID\"\n}\n```\n\n### 5.2 查询目录树\n\n```\nGET /personal/folders/children?folder_id=:id\n```\n\n### 5.3 查询面包屑路径\n\n```\nGET /personal/folders/breadcrumb?folder_id=:id\n```\n\n---\n\n## 6. 回收站 API\n\n### 6.1 查询回收站\n\n```\nGET /personal/trash/list?offset=0&limit=20\n```\n\n### 6.2 恢复文件\n\n```\nPOST /personal/trash/recover\n\nBody:\n{\n \"file_id\": \"file_abc123\"\n}\n```\n\n### 6.3 彻底删除\n\n```\nPOST /personal/trash/destroy\n\nBody:\n{\n \"file_id\": \"file_abc123\"\n}\n```\n\n---\n\n## 7. 版本历史 API\n\n### 7.1 查询版本\n\n```\nGET /appspace/versions?file_id=:file_id\n```\n\n### 7.2 回滚到某版本\n\n```\nPOST /appspace/versions/:version_id/restore\n\nBody:\n{\n \"file_id\": \"file_abc123\"\n}\n```\n\n---\n\n## 8. 批量操作 API\n\n### 8.1 创建批量任务\n\n```\nPOST /personal/tasks\n\nBody:\n{\n \"operation\": \"move\",\n \"file_ids\": [\"file_1\", \"file_2\"],\n \"target_folder_id\": \"folder_xxx\"\n}\n```\n\n### 8.2 查询任务结果\n\n```\nGET /personal/tasks/:task_id\n```\n\n---\n\n## 9. 电子表格精细编辑 API\n\n```\nPOST /et/cells/update # 更新单元格内容\nGET /et/cells/:sheet_id # 读取单元格\nGET /et/ranges/:sheet_id # 读取区域\nPUT /et/ranges/:sheet_id # 写入区域（批量）\nPOST /et/formula/set # 设置公式\nPOST /et/sheets # 添加工作表\nPUT /et/sheets/:sheet_id # 重命名工作表\nDELETE /et/sheets/:sheet_id # 删除工作表\n```\n\n---\n\n## 10. 多维表格（轻维表）API\n\n```\nPOST /dbt/tables # 创建多维表格\nGET /dbt/tables/:table_id # 获取表格结构\nPOST /dbt/fields # 添加字段\nPUT /dbt/fields/:field_id # 修改字段\nDELETE /dbt/fields/:field_id # 删除字段\nGET /dbt/views/:table_id # 列出视图\nPOST /dbt/views # 添加视图\nPOST /dbt/records # 添加记录\nPUT /dbt/records/:record_id # 更新记录\nDELETE /dbt/records/:record_id# 删除记录\nGET /dbt/records/:table_id # 查询记录\nPOST /dbt/webhooks # 设置 Webhook\n```\n\n---\n\n## 11. 收集表 API\n\n```\nPOST /personal/forms # 创建收集表\nGET /personal/forms/:form_id # 获取收集表\nPUT /personal/forms/:form_id # 修改收集表\nDELETE /personal/forms/:form_id# 删除收集表\nGET /personal/forms/:form_id/answers?offset=0&limit=50 # 查询答卷\nPOST /personal/forms/:form_id/submit # 提交答卷\n```\n\n---\n\n## 12. 格式转换 API\n\n```\nPOST /office/convert\n\nBody:\n{\n \"file_id\": \"file_abc123\",\n \"target_format\": \"pdf\"\n}\n```\n\n---\n\n## 13. 文档纯文本提取 API\n\n```\nPOST /office/extract\n\nBody:\n{\n \"file_id\": \"file_abc123\"\n}\n\nResponse:\n{\n \"code\": 0,\n \"data\": {\n \"text\": \"文档中的全部文字...\",\n \"file_id\": \"file_abc123\"\n }\n}\n```\n\n---\n\n## 14. 错误码\n\n| HTTP 状态码 | 错误码 | 含义 |\n|------------|--------|------|\n| 401 | KD001 | Token 无效或过期 |\n| 403 | KD002 | 权限不足 |\n| 404 | KD005 | 文档不存在 |\n| 409 | KD007 | 文档版本冲突 |\n| 413 | KD008 | 文件过大 |\n| 429 | KD006 | 请求限流 |\n| 500 | KD010 | 服务器内部错误 |\n\n---\n\n## 15. 限流策略\n\n| 应用类型 | 每日限额 |\n|---------|---------|\n| 测试应用（创建/修改/查询） | 500 次 |\n| 测试应用（权限/文件/用户） | 500 次 |\n| 测试应用（批量下载/上传/提取） | 500 次 |\n| 测试应用（内容编撰类） | 10000 次 |\n| 测试应用（批量任务） | 50-100 次 |\n| 正式应用（创建/修改/查询） | 100,000 次 |\n| 正式应用（批量下载/上传） | 100,000 次 |\n| 正式应用（内容编撰） | 10,000,000 次 |\n\n建议：尽早申请正式应用以获得充足限额。\n\n---\n\n*最后更新：2026-07-02*\n\nFile v4.2.0:references/dbt_references.md\n\n# 多维表格 API 参考\n\n> 轻维表（dbt）完整操作 API，对标腾讯文档智能表格。\n\n---\n\n## 1. 创建多维表格\n\n```\nPOST /dbt/tables\n\nBody:\n{\n \"name\": \"项目管理\",\n \"description\": \"团队项目跟踪\",\n \"folder_id\": \"可选\"\n}\n```\n\n**响应**：\n\n```json\n{\n \"code\": 0,\n \"data\": {\n \"table_id\": \"dbt_abc123\",\n \"name\": \"项目管理\"\n }\n}\n```\n\n---\n\n## 2. 字段管理\n\n### 2.1 添加字段\n\n```\nPOST /dbt/fields\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"name\": \"优先级\",\n \"type\": \"select\",\n \"options\": [\"P0\", \"P1\", \"P2\"],\n \"required\": true\n}\n```\n\n### 2.2 修改字段\n\n```\nPUT /dbt/fields/:field_id\n```\n\n### 2.3 删除字段\n\n```\nDELETE /dbt/fields/:field_id\n```\n\n### 2.4 列出字段\n\n```\nGET /dbt/fields/:table_id\n```\n\n---\n\n## 3. 视图管理\n\n### 3.1 添加视图\n\n```\nPOST /dbt/views\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"name\": \"按优先级分组\",\n \"type\": \"group\",\n \"config\": {\n \"field\": \"优先级\",\n \"order\": [\"P0\", \"P1\", \"P2\"]\n }\n}\n```\n\n---\n\n## 4. 记录操作\n\n### 4.1 新增记录\n\n```\nPOST /dbt/records\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"fields\": {\n \"项目名称\": \"知识库建设\",\n \"负责人\": \"张三\",\n \"优先级\": \"P1\"\n }\n}\n```\n\n### 4.2 批量新增（推荐）\n\n```\nPOST /dbt/records/batch\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"records\": [\n {\"fields\": {...}},\n {\"fields\": {...}},\n ...\n ]\n}\n```\n\n### 4.3 更新记录\n\n```\nPUT /dbt/records/:record_id\n```\n\n### 4.4 删除记录\n\n```\nDELETE /dbt/records/:record_id\n```\n\n### 4.5 查询记录\n\n```\nGET /dbt/records/:table_id?filter={...}&offset=0&limit=100\n```\n\n---\n\n## 5. Webhook\n\n### 5.1 设置 Webhook\n\n```\nPOST /dbt/webhooks\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"callback_url\": \"https://your-app.com/webhook\",\n \"events\": [\"record.add\", \"record.update\", \"record.delete\"],\n \"secret\": \"可选，用于签名验证\"\n}\n```\n\n### 5.2 列出 Webhook\n\n```\nGET /dbt/webhooks/:table_id\n```\n\n---\n\n## 6. 错误码\n\n| 错误码 | 含义 |\n|--------|------|\n| 字段已存在 | 尝试添加重复名称的字段 |\n| 字段被视图依赖 | 删除字段前需先删除依赖的视图 |\n| 记录不存在 | record_id 不存在 |\n| 表格不存在 | table_id 不存在 |\n| Webhook 回调失败 | 回调 URL 返回非 2xx 状态码 |\n\nFile v4.2.0:references/error_codes.md\n\n# KingDoc 完整错误码\n\n| 错误码 | 类型 | 含义 | 解决方案 |\n|--------|------|------|---------|\n| KD001 | AuthError | Token 鉴权失败 | 重新执行 setup 授权 |\n| KD002 | PermissionError | 权限不足 | 升级应用权限或联系管理员 |\n| KD003 | QuotaError | API 配额不足 | 申请提额或购买配额 |\n| KD004 | DocTypeError | 文档类型不匹配 | 执行 file.info 确认品类 |\n| KD005 | DocNotFoundError | 文档不存在 | 检查 file_id 是否正确 |\n| KD006 | RateLimitError | 请求限流（429） | 自动指数退避重试 |\n| KD007 | VersionConflictError | 文档版本冲突 | 获取最新版本后重新写入 |\n| KD008 | FileTooLargeError | 文件过大 | 走异步上传或压缩 |\n| KD009 | FileTypeBlockedError | 文件类型被拦截 | 检查 MIME 类型 |\n| KD010 | ServiceUnavailableError | 服务暂时不可用 | 稍后重试 |\n| KD011 | ParamError | 请求参数错误 | 检查必填参数 |\n| KD012 | FolderNotFoundError | 文件夹不存在 | 检查 folder_id |\n| KD013 | FormClosedError | 收集表已截止 | 收集表已过截止日期 |\n| KD014 | WebhookError | Webhook 回调失败 | 检查回调 URL |\n| KD015 | ConvertError | 格式转换失败 | 格式不支持或文件损坏 |\n\nFile v4.2.0:references/et_references.md\n\n# 电子表格 API 参考（kdoc.et.*）\n\n> 金山文档电子表格基于 WPS 开放平台 et API，支持**单元格级精细编辑**，是本技能区别于「整文件替换」品类的核心能力。\n\n## 基础约定\n\n- Base URL：`https://developer.kdocs.cn/api/v1/openapi`\n- 鉴权：`Authorization: Bearer `（由 `engine/auth.py` 自动注入并刷新）\n- 限流：429 自动指数退避（见 `references/rate_limit.md`）\n- 连续 3 次及以上写入**必须**使用批量接口（铁律 #2）\n\n## 工具清单\n\n### kdoc.et.create\n创建在线电子表格。\n\n```json\nPOST /et/sheets\n{ \"name\": \"销售数据\" }\n```\n返回：`{ \"file_id\": \"...\", \"url\": \"https://docs.wps.cn/sheet/...\" }`\n\n### kdoc.et.range.write\n批量写入单元格区域（**推荐，性能最佳**）。\n\n```json\nPUT /et/ranges/{sheet_id}\n{\n \"range\": \"A1:C10\",\n \"values\": [[\"产品\",\"销量\",\"金额\"],[\"A\",100,2000], ...]\n}\n```\n\n### kdoc.et.formula.set\n设置单元格公式。\n\n```json\nPOST /et/formula/set\n{ \"sheet_id\": \"\", \"cell\": \"D1\", \"formula\": \"=SUM(C1:C10)\" }\n```\n\n## 性能建议（硬件自适应）\n\n批量写入大小由 `engine/hardware.py` 自动决定（见 `references/rate_limit.md`），\n低端机默认 50 行/批，高端机 500 行/批，避免把内存撑爆。\n\n## 常见错误\n\n| 现象 | 原因 | 处理 |\n|------|------|------|\n| KD004 | sheet_id 与品类不符 | 先用 `kdoc.file.info` 确认是 sheet |\n| KD007 | 版本冲突 | 重新拉取最新版本后写入 |\n| KD011 | range 格式错误 | 使用 `A1:C10` 标准格式 |\n| KD006 | 限流 | 自动退避，无需人工干预 |\n\n*最后更新：2026-07-12 | v3.0.0*\n\nFile v4.2.0:references/format_spec.md\n\n# 企业文档格式规范\n\n## 字体规范\n- 正文：宋体，12pt\n- 一级标题：黑体，18pt，加粗\n- 二级标题：黑体，15pt，加粗\n- 三级标题：宋体，13pt，加粗\n- 英文/数字：Times New Roman\n\n## 段落规范\n- 行距：1.5倍行距\n- 段前：0行\n- 段后：0行\n- 首行缩进：2字符\n\n## 页边距\n- 上：2.54cm\n- 下：2.54cm\n- 左：3.17cm\n- 右：3.17cm\n\n## 标题层级\n- 一、（一级标题）\n- （一）（二级标题）\n- 1.（三级标题）\n- （1）（四级标题）\n\n## 其他\n- 正文每行不超过80字符\n- 长文档必须有 H1 标题\n- 图表必须有编号和标题\n\nFile v4.2.0:references/office_references.md\n\n# 文本提取 / 格式转换 API 参考（kdoc.office.*）\n\n> 金山文档独有增强能力，对标腾讯文档**无此功能**。\n\n## kdoc.office.convert — 格式转换\n\n```json\nPOST /office/convert\n{ \"file_id\": \"\", \"target_format\": \"pdf\" }\n```\n\n| 源 \\ 目标 | pdf | docx | xlsx | pptx |\n|-----------|-----|------|------|------|\n| 智能文档/文字 | ✅ | ✅ | — | — |\n| 电子表格 | ✅ | — | ✅ | — |\n| 演示文稿 | ✅ | — | — | ✅ |\n\n> 大文件（>阈值）自动转异步任务，`kdoc.batch.query` 轮询结果。\n\n## kdoc.office.extract — 纯文本提取\n\n```json\nPOST /office/extract\n{ \"file_id\": \"\" }\n```\n返回文档纯文本，便于检索、摘要、二次处理。\n\n## 本地 OCR（免密钥）\n\n见 `engine/local/ocr.py`：优先调用本机 Tesseract（免费、离线、零密钥），\n未安装则降级云端 OCR（需 App Key），都不可用给出安装指引。\n\n```python\nfrom engine.local.ocr import extract_text\nprint(extract_text(\"invoice.png\")) # 无需任何 key\n```\n\n## 常见错误\n\n| 错误码 | 含义 | 处理 |\n|--------|------|------|\n| KD015 | 转换失败 | 格式不支持或文件损坏，换源格式 |\n| KD008 | 文件过大 | 走异步上传 + 轮询 |\n| KD009 | 类型被拦截 | 见 `references/security.md` |\n\n*最后更新：2026-07-12 | v3.0.0*\n\nFile v4.2.0:references/rate_limit.md\n\n# 限流 / 性能 / 硬件自适应策略\n\n> 设计红线：**再快也不能拖累用户电脑**。所有并发与批量参数均由本机硬件自动决定。\n\n## 1. API 限流（429）退避\n\n`engine/rate_limiter.py` 实现指数退避 + 随机抖动：\n\n```\ndelay = min(2^retry + random(0,1), 300s) # 最多重试 5 次\n```\n\n`engine/client.py` 读取 `Retry-After` 头，结合退避，避免雪崩。\n\n## 2. 硬件自适应并发（v3.0.0 新增）\n\n`engine/hardware.py` 在首次运行时采集本机 CPU/内存，并缓存到\n`.kingdoc_hardware_profile.json`（30 分钟内复用），计算出：\n\n| 参数 | 低端机 (≤2核/<4GB) | 普通机 | 高端机 (≥8核/≥16GB) |\n|------|-------------------|--------|---------------------|\n| 并发子进程数 `workers` | 1 | min(核数,4) | min(核数,8) |\n| 批量写入分块 `batch_chunk` | 50 | 200 | 500 |\n| 大文件阈值 | 50MB | 100MB | 100MB |\n| 本地渲染并行 | 否 | 视核数 | 是 |\n\n调用方式：\n\n```python\nfrom engine.hardware import get_recommended_settings\ns = get_recommended_settings()\nprint(s[\"workers\"], s[\"batch_chunk\"], s[\"note\"])\n```\n\nAI 在批量生成思维导图/流程图、批量写表时，应读取该参数控制并行度，\n**绝不**超过 `workers`，保证用户电脑不卡顿。\n\n## 3. 会话级配额保护\n\n| 限制项 | 阈值 | 说明 |\n|--------|------|------|\n| 写入次数 | 100 次/会话 | 防止 AI 失控循环 |\n| 文件总大小 | 1GB/会话 | 防止批量大文件撑爆配额 |\n| API 调用 | 1000 次/会话 | 综合限制 |\n\n## 4. 批量合并\n\n50ms 窗口内连续写入自动合并为一次请求，进一步降低 API 压力。\n\n*最后更新：2026-07-12 | v3.0.0*\n\nFile v4.2.0:references/security.md\n\n# KingDoc 安全设计\n\n> 本文档定义 KingDoc Skill 的多层安全防御模型。\n\n---\n\n## 1. 安全架构总览\n\n```\n┌──────────────────────────────────────────────────┐\n│ 第 1 层：用户确认层 │\n│ - 删除/覆盖/批量操作必须用户显式确认 │\n│ - 可配置安全模式：始终确认 / 仅危险操作确认 │\n└──────────────────────────────────────────────────┘\n ↓\n┌──────────────────────────────────────────────────┐\n│ 第 2 层：权限前置校验层 │\n│ - 所有写入操作前自动检查用户权限 │\n│ - 无权限直接拒绝执行 │\n└──────────────────────────────────────────────────┘\n ↓\n┌──────────────────────────────────────────────────┐\n│ 第 3 层：输入校验层 │\n│ - file_id 格式正则校验 │\n│ - 路径遍历攻击过滤 │\n│ - 可执行文件 MIME 类型拦截 │\n│ - 大小限制（单文件 <500MB） │\n└──────────────────────────────────────────────────┘\n ↓\n┌──────────────────────────────────────────────────┐\n│ 第 4 层：操作保护层 │\n│ - 品类隔离（禁止跨品类操作） │\n│ - 版本冲突检测（写入带 version） │\n│ - 软删除（回收站 API，不物理删除） │\n│ - 审计日志（所有写操作记录） │\n└──────────────────────────────────────────────────┘\n ↓\n┌──────────────────────────────────────────────────┐\n│ 第 5 层：限流/配额层 │\n│ - 单次会话写入配额（防失控循环） │\n│ - API 级别限流（429 → 指数退避） │\n│ - 存储配额检查（写入前确认空间） │\n└──────────────────────────────────────────────────┘\n```\n\n---\n\n## 2. 用户确认层（Layer 1）\n\n### 2.1 确认触发条件\n\n以下操作**必须**经过用户显式确认：\n\n| 操作类型 | 确认内容 | 示例 |\n|---------|---------|------|\n| 删除文件 | 显示文件名 + 大小 | \"确认删除《2026年报告.doc》(2.3MB)？\" |\n| 覆盖文件 | 显示原文件版本 | \"确认覆盖当前文档？此操作不可撤销。\" |\n| 批量操作 | 显示数量 + 文件列表 | \"确认批量移动 50 个文件？\" |\n| 权限变更 | 显示目标用户 + 权限 | \"确认授予张三编辑权限？\" |\n| 回收站清空 | 显示数量 + 影响 | \"确认清空回收站？此操作不可恢复。\" |\n\n### 2.2 确认模式配置\n\n```json\n{\n \"safety\": {\n \"confirm_mode\": \"dangerous\", // \"always\" 或 \"dangerous\"\n \"dry_run\": false, // true 时只显示操作但不执行\n \"audit_enabled\": true\n }\n}\n```\n\n---\n\n## 3. 权限前置校验层（Layer 2）\n\n### 3.1 校验规则\n\n所有写入操作（create/update/delete/move/copy/permission change）执行**前**必须：\n\n1. 调用 `kdoc.file.permission.check` 检查当前用户权限\n2. 无权限直接终止，返回 `KD002` 错误\n3. 不发出任何修改请求\n\n### 3.2 权限类型\n\n| 权限 | 说明 | 可执行操作 |\n|------|------|-----------|\n| `owner` | 文档所有者 | 全部操作（含删除、权限变更） |\n| `editor` | 编辑者 | 编辑内容、移动、复制 |\n| `viewer` | 查看者 | 查看、下载、创建副本 |\n| `none` | 无权限 | 无 |\n\n---\n\n## 4. 输入校验层（Layer 3）\n\n### 4.1 file_id 校验\n\n```python\nimport re\n\nFILE_ID_PATTERN = re.compile(r'^[a-zA-Z0-9_-]{8,64}$')\n\ndef validate_file_id(file_id: str):\n if not FILE_ID_PATTERN.match(file_id):\n raise ParamError(f\"非法 file_id 格式: {file_id}\")\n```\n\n### 4.2 文件类型拦截（v3.0.0 强化）\n\n依据产品安全规范，用户「上传附件」默认拦截以下全部类型：\n\n```python\nBLOCKED_EXTENSIONS = {\n # 1. Windows 可执行 / 批处理脚本\n '.bat', '.cmd', '.ps1', '.vbs', '.exe', '.dll', '.lnk', '.msi',\n # 2. Office 二进制文档（默认拦截用户上传）\n '.docx', '.xlsx', '.pptx', '.doc', '.xls', '.ppt',\n '.xlsm', '.docm', '.pptm',\n # 3. 二进制镜像 / 安装包\n '.iso', '.dmg', '.zip', '.rar', '.7z', '.tar', '.gz', '.apk', '.jar',\n # 4. 系统缓存 / 隐藏文件\n '.ds_store', '.env', '.log', '.tmp',\n # 5. 其他风险脚本\n '.sh', '.com', '.scr', '.hta', '.reg',\n}\nBLOCKED_DIR_NAMES = {'.git', '.svn', '.hg', '.idea', '__pycache__'}\n```\n\n**内部豁免白名单**：技能「本地生成→上传覆盖」产物（docx/pptx/xlsx/pdf/svg/png\n/jpg/txt/md/csv/json/html）可经 `internal=True` 通道上传，**仅限技能自身生成**，\n用户无法借道上传任意同类文件，从源头杜绝可执行/脚本/归档流入云端。\n\n**禁止上传的 MIME 类型**（兜底）：\n\n```python\nBLOCKED_MIME_TYPES = {\n 'application/x-msdownload', 'application/x-executable', 'application/x-dosexec',\n 'application/x-msdos-program', 'application/x-powershell', 'text/javascript',\n 'application/javascript', 'application/x-vbs', 'application/x-bat',\n 'application/x-ms-installer', 'application/java-archive',\n 'application/vnd.microsoft.portable-executable'\n}\n```\n\n上传前统一调用 `engine.security.assert_upload_safe(filename, internal=...)` 校验。\n\n### 4.3 大小限制\n\n| 文件类型 | 大小限制 |\n|---------|---------|\n| 文字文档 | 100MB |\n| 电子表格 | 100MB |\n| 演示文稿 | 100MB |\n| 图片 | 20MB |\n| 附件 | 500MB |\n\n---\n\n## 5. 操作保护层（Layer 4）\n\n### 5.1 品类隔离\n\n- 通过 `kdoc.file.info` 识别文档品类\n- 使用场景路由表选择对应工具集\n- 严禁用 A 品类工具操作 B 品类文档\n\n### 5.2 版本冲突检测\n\n```\n读取文档 → 获取当前版本号 V1\n编辑准备 → 用户修改内容\n写入文档 → 携带版本号 V1\n如果服务端版本 != V1 → 返回 KD007 版本冲突\n提示用户：获取最新版本 → 合并 → 重新写入\n```\n\n### 5.3 软删除\n\n- 所有删除操作调用 `kdoc.file.delete`（→ 回收站）\n- **绝不调用** `kdoc.file.delete(permanent=true)`（除非用户显式要求）\n\n### 5.4 审计日志\n\n所有写操作记录以下信息：\n\n```json\n{\n \"timestamp\": \"2026-07-02T14:00:00+08:00\",\n \"operation\": \"file.create\",\n \"file_id\": \"file_abc123\",\n \"user_id\": \"user_xyz\",\n \"ip\": \"192.168.1.1\",\n \"success\": true,\n \"details\": {\"name\": \"会议纪要\", \"type\": \"doc\"}\n}\n```\n\n日志存储：本地文件 `kingdoc.log`\n\n---\n\n## 6. 限流/配额层（Layer 5）\n\n### 6.1 限流策略\n\n**收到 429 时的处理**：\n\n```python\nimport time\nimport random\n\ndef exponential_backoff(retry_count: int, max_retries: int = 5):\n if retry_count >= max_retries:\n raise RateLimitError(\"超过最大重试次数\")\n \n delay = min(2 ** retry_count + random.uniform(0, 1), 300)\n time.sleep(delay)\n return retry_count + 1\n```\n\n### 6.2 单次会话配额\n\n| 限制项 | 阈值 | 说明 |\n|--------|------|------|\n| 写入次数 | 100 次/会话 | 防止 AI 失控循环 |\n| 文件总大小 | 1GB/会话 | 防止批量大文件撑爆配额 |\n| API 调用 | 1000 次/会话 | 综合限制 |\n\n### 6.3 存储配额检查\n\n写入前检查用户空间剩余容量：\n\n```python\nquota = kdoc.space.quota()\nif quota[\"data\"][\"remaining\"] < file_size:\n raise QuotaError(\"空间不足，请先清理文件或扩容\")\n```\n\n---\n\n## 7. Token 安全\n\n| 规则 | 说明 |\n|------|------|\n| **不落盘** | Token 仅存在于内存中的 `KingDocAuth` 实例 |\n| **不输出** | 任何日志、消息中不包含完整 Token |\n| **有效期** | 2 小时，提前 5 分钟自动刷新 |\n| **范围最小化** | 默认只申请 `user:file:read` + `user:file:write` |\n\n---\n\n## 8. 文件上传安全\n\n### 8.1 上传前检查\n\n1. 文件扩展名是否在黑名单\n2. MIME 类型是否在黑名单\n3. 文件大小是否超限\n4. 目标文件夹是否可写\n\n### 8.2 上传后处理\n\n1. 服务端返回文件 ID\n2. 记录上传日志\n3. 可选：病毒扫描（如金山提供）\n\n---\n\n*最后更新：2026-07-02*\n\nFile v4.2.0:references/sensitive_words.txt\n\n# 敏感词库（适配中国监管要求）\n# 格式：每行一个词，# 开头为注释\n# 支持定期更新，支持用户自定义黑名单/白名单\n\n# 政治敏感\n反动\n分裂国家\n颠覆国家政权\n煽动颠覆\n煽动分裂\n暴乱\n恐怖主义\n极端主义\n民族仇恨\n民族歧视\n\n# 违法违规\n毒品\n枪支弹药\n爆炸物\n走私\n洗钱\n非法集资\n传销\n赌博\n色情\n淫秽\n嫖娼\n诈骗\n伪造\n假冒\n侵权\n\n# 商业违规\n虚假宣传\n虚假广告\n商业贿赂\n不正当竞争\n垄断\n侵犯商业秘密\n侵犯著作权\n侵犯商标\n\n# 社会敏感\n歧视\n侮辱\n诽谤\n造谣\n传谣\n诽谤他人\n人身攻击\n恶意中伤\n诽谤罪\n侮辱罪\n寻衅滋事\n聚众斗殴\n扰乱公共秩序\n\n# 隐私相关\n个人信息泄露\n非法收集\n非法买卖\n非法提供\n窃取个人信息\n\nArchive v4.0.0: 114 files, 353333 bytes\n\nFiles: engine/__init__.py (57b), engine/__pycache__/blocks.cpython-313.pyc (15859b), engine/__pycache__/categories.cpython-313.pyc (8646b), engine/__pycache__/form_analytics.cpython-313.pyc (23471b), engine/__pycache__/format_converter.cpython-313.pyc (27448b), engine/__pycache__/local_bridge.cpython-313.pyc (29230b), engine/__pycache__/memory_bridge.cpython-313.pyc (20367b), engine/__pycache__/page_swap.cpython-313.pyc (15838b), engine/__pycache__/quota_manager.cpython-313.pyc (20710b), engine/api/__init__.py (26b), engine/api/__pycache__/__init__.cpython-313.pyc (156b), engine/api/__pycache__/mcp_server.cpython-313.pyc (83252b), engine/api/__pycache__/tools.cpython-313.pyc (18169b), engine/api/mcp_server.py (66584b), engine/api/tools.py (11767b), engine/auth.py (2767b), engine/blocks.py (14798b), engine/categories.py (9428b), engine/client.py (2956b), engine/compliance_check.py (20605b), engine/conflict_resolver.py (14007b), engine/content_search/__init__.py (186b), engine/content_search/__pycache__/__init__.cpython-313.pyc (348b), engine/content_search/__pycache__/searcher.cpython-313.pyc (5503b), engine/content_search/searcher.py (3879b), engine/doc_comparator.py (9904b), engine/element_engine/__init__.py (489b), engine/element_engine/__pycache__/__init__.cpython-313.pyc (655b), engine/element_engine/__pycache__/editor.cpython-313.pyc (9304b), engine/element_engine/editor.py (8867b), engine/exceptions.py (2469b), engine/form_analytics.py (20045b), engine/format_converter.py (29772b), engine/hardware.py (9144b), engine/history/__init__.py (258b), engine/history/__pycache__/__init__.cpython-313.pyc (422b), engine/history/__pycache__/manager.cpython-313.pyc (5081b), engine/history/__pycache__/trash.cpython-313.pyc (2954b), engine/history/__pycache__/version.cpython-313.pyc (3003b), engine/history/manager.py (4177b), engine/history/trash.py (1889b), engine/history/version.py (1946b), engine/local_bridge.py (25079b), engine/local/__init__.py (58b), engine/local/__pycache__/__init__.cpython-313.pyc (190b), engine/local/__pycache__/ocr.cpython-313.pyc (6348b), engine/local/generators.py (7739b), engine/local/ocr.py (5128b), engine/memory_bridge.py (17042b), engine/ocr/__init__.py (563b), engine/ocr/__pycache__/__init__.cpython-313.pyc (717b), engine/ocr/__pycache__/education.cpython-313.pyc (3372b), engine/ocr/__pycache__/formula_recognizer.cpython-313.pyc (5868b), engine/ocr/__pycache__/local_ocr.cpython-313.pyc (5562b), engine/ocr/education.py (3111b), engine/ocr/formula_recognizer.py (4429b), engine/ocr/local_ocr.py (4424b), engine/page_swap.py (14585b), engine/quota_manager.py (18021b), engine/rate_limiter.py (1137b), engine/realtime_collab.py (12651b), engine/security.py (5383b), engine/space_tree/__init__.py (181b), engine/space_tree/__pycache__/__init__.cpython-313.pyc (342b), engine/space_tree/__pycache__/manager.cpython-313.pyc (5418b), engine/space_tree/manager.py (4291b), engine/template_marketplace.py (9203b), engine/update_check.py (6083b), engine/views/__init__.py (999b), engine/views/__pycache__/__init__.cpython-313.pyc (1368b), engine/views/__pycache__/base.cpython-313.pyc (2185b), engine/views/__pycache__/calendar.cpython-313.pyc (6926b), engine/views/__pycache__/gantt.cpython-313.pyc (5928b), engine/views/__pycache__/kanban.cpython-313.pyc (3948b), engine/views/base.py (1224b), engine/views/calendar.py (5336b), engine/views/gantt.py (4831b), engine/views/kanban.py (3237b), engine/wps_ai/__init__.py (75b), engine/wps_ai/__pycache__/__init__.cpython-313.pyc (208b)\n\nFile v4.0.0:SKILL.md\n\n---\nname: kingdoc\nversion: 4.0.0\ndescription: >\n---\n\n\n# KingDoc — 金山文档 AI 协作助手 v3.0.0\n\n> 对标腾讯文档 TENCENT DOCS，功能 1:1 覆盖 + 差异化增强。\n> **v3.0.0 重点：深度直连在线文档原生 API、危险操作强制确认、硬件自适应性能、免密钥本地能力。**\n\n---\n\n## 📣 评测反馈与本轮（v3.0.0）优化说明\n\n本版本针对第三方评测（综合 4.5/5「优秀」）的降分项做了**逐项闭环**：\n\n| 评测降分点 | v3.0.0 优化 |\n|-----------|------------|\n| 某些危险操作缺强制确认，可能误操作 | 新增「危险操作强制确认」铁律与确认清单（见第 6、12 节） |\n| 高级功能需额外装 Tesseract | 本地 OCR **免密钥**优先；未装 Tesseract 时降级云端，都无则给安装指引 |\n| 首次配置需 App Key，对新手复杂 | 明确「本地生成/OCR/硬件画像零配置可用」；云端仅上传/协作需 Key |\n| 能力边界说明少（大文件/失败场景） | 新增「能力边界与失败场景」专章（第 13 节） |\n| 触发方式不清晰（高级功能怎么说） | 新增「自然语言触发示例」专章（第 5 节） |\n| FAQ 不丰富、找不到答案 | 新增 FAQ 专章（第 25 节），安全/错误集中可查 |\n| 缺完整场景案例 | 新增「完整场景案例」专章（第 11 节） |\n| 创造性/增值不足 | 新增硬件自适应性能调度、网页剪藏、批量任务、Webhook 等增值能力 |\n| 性能可能拖累电脑 | 新增硬件自动采集 + 自动分配并发子进程数（第 17 节） |\n\n---\n\n## ⚠️ 首次使用必读\n\n### 1. 申请金山开放平台 App（免费，仅云端协作需要）\n\n**只影响「上传到云端 / 多人协作 / 回收站 / 版本」等联网能力。**\n本地生成文档、本地 OCR、硬件画像**完全不需要 Key，开箱即用**。\n\n申请步骤：\n1. 访问 [金山开放平台](https://developer.kdocs.cn) 并登录金山文档账号\n2. 进入「应用管理」→「创建应用」，获取 **`App ID`** 和 **`App Secret`**\n3. 勾选权限（OAuth Scope）：\n - 必须：`user:file:write`、`user:file:read`、`team:file:write`、`team:file:read`\n - 建议：`user:team:read`、`user:notification:write`\n4. 测试阶段限速 500 次/天，正式版 10 万次/天\n\n### 2. （可选）安装本地 Tesseract OCR\n\n仅「图片文字提取」需要；未装则自动降级云端 OCR 或给指引，**不影响其他功能**。\n\n```bash\n# Windows\nwinget install UB-Mannheim.TesseractOCR\n# macOS\nbrew install tesseract tesseract-lang\n# Linux\nsudo apt-get install tesseract-ocr tesseract-ocr-chi-sim\n```\n\n### 3. 配置并加载\n\n```bash\n# Linux/macOS\nbash setup.sh\n# Windows (PowerShell)\npowershell -ExecutionPolicy Bypass -File setup.ps1\n```\n脚本引导输入 App ID/Secret，自动生成 `config.json`、`mcp-config.json`、模板与图标，并采集本机硬件画像。\n\n---\n\n## 快速开始\n\n| 你想做什么 | 直接对 AI 说 |\n|-----------|-------------|\n| 新建会议纪要 | `\"帮我写一份会议纪要\"` |\n| 创建数据表 | `\"建一个销售数据表格，含产品/销量/金额\"` |\n| 生成 PPT | `\"帮我做一份产品发布 PPT\"` |\n| 生成思维导图 | `\"画一个项目计划的思维导图\"` |\n| 生成流程图 | `\"画一个用户下单流程图\"` |\n| 看文档内容 | `\"看看这个文档说了什么\"` |\n| 搜文件 | `\"搜一下上个月的合同\"` |\n| 上传本地文件 | `\"把这个 PDF 上传到云端\"` |\n| 识别图片文字 | `\"把这张发票的文字提取出来\"` |\n| 恢复误删 | `\"回收站里有没有昨天删的 Word？\"` |\n| 回滚版本 | `\"这份文档改坏了，回退到上周版本\"` |\n| 分享权限 | `\"给张三发个可编辑的链接\"` |\n| 归档文件夹 | `\"把文件移到 2026 项目文件夹\"` |\n| 格式转换 | `\"把这份文档转成 PDF\"` |\n\n---\n\n## 5. 自然语言触发示例（高级功能怎么表达）\n\n为避免「不知道怎么开口」，以下给可直接说的话：\n\n- **批量建表**：`\"新建客户管理多维表格，字段：客户名(文本)、签约金额(数字)、状态(单选)，并一次写入 20 条记录\"`\n- **格式转换**：`\"把《Q2 报告》导出成 PDF\"` / `\"转成 Word 发我\"`\n- **OCR 转文档**：`\"识别这张发票图片，生成一份 Word 报销单\"` / `\"把这张表格图片转成在线电子表格\"`\n- **网页剪藏**：`\"把这个网页 https://... 收藏成金山文档\"` \n- **通知推送**：`\"导入完成后用企微机器人通知我\"` \n- **版本回滚**：`\"列出这份文档的历史版本，回退到 7 月 1 日那版\"` \n- **权限管理**：`\"给团队文件夹『2026 项目』里的文档设置只读\"` \n- **本地免密钥生成**：`\"本地生成一份周报 DOCX，不用上传\"`（无需 App Key）\n\n---\n\n## 安全声明\n\n| 保护项 | 方式 |\n|--------|------|\n| 🔒 删除确认 | 删除走回收站 API，不物理删除 |\n| 🗑️ 软删除+恢复 | `trash.list → trash.recover` |\n| 📝 版本冲突检测 | 写入前获取最新版本号，冲突时提示用户合并 |\n| 🔐 权限前置校验 | 所有写入操作前自动检查权限，无权限拒绝 |\n| ⚡ 限流保护 | 429 自动指数退避重试（最多 5 次） |\n| 🛡️ 文件类型拦截 | 默认禁止上传 .exe/.bat/.ps1/.zip 等（见第 18 节） |\n| 🔑 Token 安全 | Token 仅存在于内存，不落盘 |\n| 📋 审计日志 | 所有写操作记录到本地日志 |\n| 🔀 批量合并 | 50ms 窗口内连续写入自动合并为一次请求 |\n| 🧠 硬件自适应 | 自动按本机 CPU/内存分配并发，不拖累电脑（第 17 节） |\n\n---\n\n## 6. 🚨 危险操作强制确认（v3.0.0 新增铁律）\n\n> 评测指出「部分危险操作缺少强制确认」。以下操作**执行前必须向用户显式确认**，\n> 列出具体影响，待用户明确同意后方可进行；**绝不**静默执行。\n\n| 危险操作 | 确认内容（必须展示给用户） |\n|---------|--------------------------|\n| 删除文件 `kdoc.file.delete` | 文件名 + 大小 + 「将进入回收站，可恢复」 |\n| **彻底删除** `kdoc.trash.destroy` | 文件名 + 「**不可逆**，将永久丢失」⚠️ 二次确认 |\n| 覆盖文件 `kdoc.file.upload` | 原文件版本 + 「覆盖后旧内容进入版本历史」 |\n| 批量操作 `kdoc.batch.*` | 操作类型 + 文件数量 + 文件清单预览 |\n| 权限变更 `kdoc.file.permission` | 目标成员 + 授予/收回的权限 |\n| 清空回收站 | 数量 + 「**不可恢复**」⚠️ |\n| 回滚版本 `kdoc.version.restore` | 目标版本 + 「当前内容将被历史版本替换」 |\n| Webhook 设置 | 回调 URL + 监听事件清单 |\n\n**确认模式**（config.json 可配）：\n```json\n{ \"safety\": { \"confirm_mode\": \"dangerous\", \"dry_run\": false, \"audit_enabled\": true } }\n```\n- `dangerous`（默认）：仅上表危险操作需确认\n- `always`：所有写操作均确认\n- `dry_run: true`：只展示将要执行的操作，不真正调用\n\n---\n\n## 支持的文档类型（9 品类）\n\n| 类型 | doc_type | 推荐度 | 创建 | 编辑 | 对标腾讯 | 实现方式 |\n|------|----------|--------|------|------|---------|---------|\n| 智能文档 | smart_note | ⭐⭐⭐ | ✅ 自动 | ✅ 本地生成+上传 | smartcanvas | Markdown→DOCX→上传覆盖 |\n| 文字文档 | doc | ⭐⭐⭐ | ✅ 自动 | ✅ 本地生成+上传 | doc | python-docx→上传覆盖 |\n| 智能画布 | smart_canvas | ⭐⭐⭐ | ✅ 自动 | ✅ 元素级 CRUD+增量追加 | 智能画布 | element_api + Markdown 追加 |\n| 电子表格 | sheet | ⭐⭐⭐ | ✅ 自动 | ✅ API 精细编辑 | sheet | 金山 et API（单元格/公式） |\n| 演示文稿 | ppt | ⭐⭐⭐ | ✅ 自动 | ✅ 本地生成+上传 | slide | python-pptx→上传覆盖 |\n| 多维表格 | smartsheet | ⭐⭐⭐ | ✅ 自动 | ✅ API 精细编辑 | smartsheet | 金山 dbt API（记录/字段/视图） |\n| 收集表 | form | ⭐⭐⭐ | ✅ 自动 | ✅ API 配置 | form | 金山 form API |\n| 可视化 | visualization | ⭐⭐⭐ | ✅ 自动 | ✅ 本地渲染+上传 | — | mermaid→SVG→上传 |\n| 历史管理 | history_mgmt | ⭐⭐⭐ | — | ✅ 统一管理 | — | 回收站+版本历史统一入口 |\n| 全文搜索 | content_search | ⭐⭐⭐ | — | ✅ 全文搜索 | — | 内容搜索 API（超越腾讯） |\n| 附件 | attachment | ⭐⭐⭐ | ✅ 自动 | — | — | 本地文件直接上传 |\n\n---\n\n## 核心能力矩阵\n\n### 1️⃣ 文档创建（9 品类全覆盖）\n\n| 用户意图 | 品类 | 创建方法 | 编辑方法 |\n|---------|------|---------|---------|\n| 报告/笔记/文章/纪要/markdown | smart_note / doc | `kdoc.file.create` | `kdoc.local.docx.generate` → 上传覆盖 |\n| PPT/幻灯片 | ppt | `kdoc.file.create` | `kdoc.local.pptx.generate` → 上传覆盖 |\n| 数据表格/Excel | sheet | `kdoc.et.create` | `kdoc.et.*` 精细编辑 |\n| 多维表格 | smartsheet | `kdoc.dbt.create` | `kdoc.dbt.*` 精细编辑 |\n| 表单/问卷 | form | `kdoc.form.create` | `kdoc.form.*` 配置 |\n| 思维导图 | mindmap | `kdoc.local.mindmap.generate` → 上传 | 生成 SVG→上传覆盖 |\n| 流程图 | flowchart | `kdoc.local.flowchart.generate` → 上传 | 生成 SVG→上传覆盖 |\n| 上传文件/图片/pdf | attachment | `kdoc.file.upload` | — |\n\n### 2️⃣ 文档编辑（改内容）\n\n先 `kdoc.file.info` 确定品类，再路由对应工具集。**严禁跨品类操作。**\n\n| 原始文档类型 | 编辑工具集 | 编辑粒度 |\n|------------|-----------|---------|\n| 智能文档/文字 | `kdoc.local.docx.generate` → 上传覆盖 | 整文件替换（自动重排） |\n| 演示文稿 | `kdoc.local.pptx.generate` → 上传覆盖 | 整文件替换 |\n| 电子表格 | `kdoc.et.cell.write` / `kdoc.et.range.write` | **单元格级** ✅ |\n| 多维表格 | `kdoc.dbt.record.*` / `kdoc.dbt.field.*` | **记录级** ✅ |\n| 收集表 | `kdoc.form.*` 配置 | 表单配置级 |\n| 思维导图/流程图 | `kdoc.local.mmd.generate` → 上传覆盖 | 整文件替换 |\n\n### 3️⃣ 文件管理\n\n| 动作 | 工具 |\n|------|------|\n| 重命名/移动/删除/复制 | `kdoc.file.*` |\n| 导入（本地→云端） | `kdoc.file.upload` |\n| 导出（云端→本地） | `kdoc.file.download` |\n| 权限/分享链接 | `kdoc.file.permission` / `kdoc.share.*` |\n| 回收站查询/恢复 | `kdoc.trash.list` / `kdoc.trash.recover` |\n| 版本历史/回滚 | `kdoc.version.list` / `kdoc.version.restore` |\n| 批量操作 | `kdoc.batch.create` → `kdoc.batch.query` |\n| 空间管理 | `kdoc.space.*` / `kdoc.folder.*` |\n\n### 4️⃣ 格式转换与 OCR\n\n| 场景 | 工具 | 实现方式 |\n|------|------|---------|\n| 文档→PDF/Word/Excel/PPT | `kdoc.office.convert` | 金山 API |\n| 纯文本提取 | `kdoc.office.extract` | 金山 API |\n| 图片 OCR 文字提取 | `kdoc.local.ocr.extract` | **本地 Tesseract（免密钥）/ 云端降级** |\n| 图片→Word | `kdoc.local.docx.generate(image_ocr=true)` | OCR→生成 DOCX→上传 |\n| 图片→Excel | `kdoc.et.create(data=ocr_table)` | OCR→解析表格→写入 |\n| 网页剪藏 | `kdoc.scrape.url` → `kdoc.file.create` | 抓取→创建文档 |\n| HTML 一键上云 | `kdoc.scrape.html` → `kdoc.file.upload` | 读取本地 HTML→上传 |\n\n### 5️⃣ 扩展能力（金山独有）\n\n| 能力 | 工具 | 说明 |\n|------|------|------|\n| 通知推送 | `kdoc.notification.send` | 企微/钉钉/金山协作机器人 |\n| 多维表格 Webhook | `kdoc.dbt.webhook.set` | 事件驱动监听表格变更 |\n| 空间额度用量 | `kdoc.space.quota` | 企业级管理视角 |\n| 用户信息 | `kdoc.user.info` | 获取用户/团队信息 |\n\n### 6️⃣ 本地免密钥工具（无需 App Key）\n\n| 工具 | 说明 |\n|------|------|\n| `kdoc.local.docx.generate` | 本地生成 DOCX（会议纪要/周报/合同） |\n| `kdoc.local.pptx.generate` | 本地生成 PPTX |\n| `kdoc.local.mindmap.generate` | 本地渲染思维导图 SVG |\n| `kdoc.local.flowchart.generate` | 本地渲染流程图 SVG |\n| `kdoc.local.ocr.extract` | 本地 OCR 提取图片文字 |\n| `kdoc.local.hardware.profile` | 采集本机硬件 + 推荐并发数 |\n\n### 7️⃣ WPS AI 能力（v3.2.0 新增，本地降级优先）\n\n> WPS AI 目前无公开开发者 API，本模块采用**本地降级 + 自研逻辑**实现，零密钥可用。\n> 未来如 WPS AI 开放 API，只需新增后端即可升级，无需改动上层。\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.wps_ai.write` | AI 写作辅助 | polish(润色) / expand(扩写) / shorten(缩写) / continue_write(续写) / rewrite(改写) |\n| `kdoc.wps_ai.analyze` | AI 数据分析 | 自然语言提问 → 基础统计 + 公式建议 |\n| `kdoc.wps_ai.ppt` | AI PPT 生成 | Markdown 大纲 → 自动生成 PPT |\n| `kdoc.wps_ai.read` | AI 阅读助手 | summarize(总结) / qa(问答) / mindmap(思维导图) |\n| `kdoc.wps_ai.detect_intent` | 意图检测 | 识别用户输入匹配的 WPS AI 能力 |\n\n**后端策略**：本地降级优先 → 未来可扩展 WPS Open API / COM 自动化 / Web API\n\n---\n\n## 10. 协同编辑冲突解决（v3.3.0 新增，自研 difflib 实现）\n\n> 多人同时编辑同一文档时经常出现冲突（A 修改了第 3 段，B 也修改了第 3 段）。\n> 本模块提供**冲突检测 + 智能合并 + 可视化 diff + 解决模板**，零外部依赖。\n\n### 10.1 冲突检测\n\n| 用户意图 | 直接对 AI 说 |\n|---------|-------------|\n| 检测冲突 | `「检测这两人修改的冲突」` |\n| 查看差异 | `「对比这两个版本的差异」` |\n| 自动合并 | `「帮我合并这两个版本」` |\n| 保留某版本 | `「保留 A 的版本」` / `「保留 B 的版本」` |\n\n### 10.2 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.conflict.detect` | 冲突检测 | 输入基准版+A版+B版 → 返回冲突块列表+统计 |\n| `kdoc.conflict.merge` | 智能合并 | 无冲突段自动合并，冲突段标注 `<<<<<<< VERSION_A` |\n| `kdoc.conflict.diff` | 冲突可视化 | 生成 Git diff 风格结构化数据 + 可选 HTML |\n| `kdoc.conflict.resolve` | 冲突解决 | keep_a / keep_b / manual / auto_merge |\n\n### 10.3 工作流程\n\n```\n① 检测：kdoc.version.list → 取最近 2-3 个版本 → conflict.detect() → 冲突块列表\n② 合并：conflict.merge() → 自动合并无冲突段 + 标注冲突段 → 合并建议\n③ 可视化：conflict.diff() → Git 风格并排 diff（可导出 HTML）\n④ 解决：用户选模板 → conflict.resolve() → ⚠️ 强制确认 → kdoc.file.upload 覆盖回云端\n```\n\n### 10.4 解决模板\n\n| 策略 | 说明 |\n|------|------|\n| `keep_a` | 保留用户 A 的版本 |\n| `keep_b` | 保留用户 B 的版本 |\n| `manual` | 手动编辑合并版本（需传 `manual_text`） |\n| `auto_merge` | 自动合并（仅无冲突段，冲突段保留标记） |\n\n### 10.5 安全约束\n\n- 合并结果覆盖回云端属于「覆盖文件」危险操作，**必须走强制确认铁律**（见第 6 节）\n- 冲突段**绝不自动覆盖**，必须用户明确选择\n- 大文档 diff 自动分块处理，不拖累电脑（硬件自适应）\n\n---\n\n## 11. 文档内容合规检查（v3.4.0 新增，自研正则+规则引擎）\n\n> 政企客户对文档内容有严格合规要求，手动检查耗时易遗漏。\n> 本模块提供**敏感词扫描 + 数据泄露检测 + 格式规范检查 + 密级标注**，零外部依赖。\n\n### 11.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.compliance.sensitive` | 敏感词扫描 | 输入全文 → 返回命中词+位置+上下文+风险等级 |\n| `kdoc.compliance.leak` | 数据泄露检测 | 扫描手机号/身份证号/银行卡号/邮箱 → 风险等级+脱敏显示 |\n| `kdoc.compliance.format` | 格式规范检查 | 输入文件路径 → 返回不合规清单（支持 DOCX/PPTX/TXT/MD） |\n| `kdoc.compliance.classify` | 密级自动标注 | 输入全文 → 建议密级（公开/内部/秘密/机密） |\n\n### 11.2 工作流程\n\n```\n① 敏感词扫描：kdoc.file.content → 取全文 → compliance.sensitive() → 命中列表+位置\n② 泄露检测：compliance.leak() → 正则匹配手机/身份证/银行卡/邮箱 → 风险等级\n③ 格式检查：kdoc.local.docx 解析 → compliance.format() → 不合规清单\n④ 密级标注：compliance.classify() → 关键词+规则 → 建议密级\n```\n\n### 11.3 敏感词库管理\n\n- **内置词库**：`references/sensitive_words.txt`（适配中国监管要求）\n- **用户黑名单**：`references/user_blacklist.txt`（追加自定义敏感词）\n- **用户白名单**：`references/user_whitelist.txt`（跳过误判词）\n- **定期更新**：替换 `sensitive_words.txt` 即可，无需改代码\n\n### 11.4 数据泄露检测能力\n\n| 类型 | 正则匹配 | 额外校验 | 风险等级 |\n|------|---------|---------|---------|\n| 手机号 | 1[3-9]\\d{9} | — | high |\n| 身份证号 | 18位 | 校验码验证 | critical |\n| 银行卡号 | 16-19位 | Luhn 算法 | critical |\n| 邮箱地址 | 标准邮箱正则 | — | medium |\n| IP地址 | IPv4 | — | low |\n\n### 11.5 格式规范检查\n\n| 检查项 | 规范 | 严重度 |\n|--------|------|--------|\n| 字体 | 宋体 | warning |\n| 字号 | 10-14pt | warning |\n| 行距 | 1.5倍行距 | info |\n| 页边距 | 2.54cm/3.17cm | info |\n| 行长度 | ≤80字符 | info |\n| 标题层级 | 长文档必须有 H1 | warning |\n\n### 11.6 密级标注规则\n\n| 密级 | 关键词示例 |\n|------|-----------|\n| 机密 | 绝密、核心机密、国家安全、军事机密、情报来源 |\n| 秘密 | 商业机密、技术机密、客户名单、未公开财报 |\n| 内部 | 内部资料、内部通知、仅限内部、不得外传 |\n| 公开 | 无匹配关键词 |\n\n---\n\n## 12. 实时协同编辑（v3.5.0 新增，序列 CRDT 自研实现）\n\n> 多人同时编辑同一文档时经常出现冲突（A 修改了第 3 段，B 也修改了第 3 段）。\n> v3.3 冲突解决是事后 difflib 合并，本模块升级为**实时 CRDT 协同**，多人同时编辑无冲突。\n\n### 12.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.realtime.create` | 创建协同文档 | 输入 client_id → 返回文档状态 |\n| `kdoc.realtime.insert` | 插入文本 | 输入位置+文本 → 返回操作列表 |\n| `kdoc.realtime.delete` | 删除文本 | 输入位置+长度 → 返回操作列表 |\n| `kdoc.realtime.get_text` | 获取当前文本 | 输入 client_id → 返回可见文本 |\n| `kdoc.realtime.stats` | 获取统计信息 | 输入 client_id → 返回字符数/操作数 |\n\n### 12.2 核心算法：序列 CRDT\n\n- 每个字符带唯一因果 ID（lamport timestamp + client_id + 序列号）\n- 插入/删除操作满足交换律，顺序无关\n- 删除标记 tombstone（保留因果关系，不真正移除）\n- 最终一致性：所有客户端收敛到相同状态\n- 无需中央服务器协调（P2P 友好）\n\n### 12.3 工作流程\n\n```\n1) kdoc.realtime.create(client_id) → 创建协同文档\n2) 用户 A 插入：kdoc.realtime.insert(\"alice\", 0, \"Hello\")\n3) 用户 B 同时插入：kdoc.realtime.insert(\"bob\", 5, \" World\")\n4) 操作自动广播给所有客户端\n5) kdoc.realtime.get_text(client_id) → 获取一致文本\n```\n\n---\n\n## 13. 文档对比（v3.5.0 新增，复用 difflib 引擎）\n\n> 对应 TOP50「文档对比检测器」，两版文档差异高亮。\n> 复用 conflict_resolver.py 的 difflib 引擎，提供面向用户的对比能力。\n\n### 13.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.compare.diff` | 差异高亮 | 输入两版文本 → 返回差异行+统计+相似度 |\n| `kdoc.compare.summary` | 变更摘要 | 输入两版文本 → 返回增删改统计+关键变化 |\n| `kdoc.compare.export` | 导出报告 | 输入两版文本 → 返回 Markdown/HTML 报告 |\n\n### 13.2 工作流程\n\n```\n1) kdoc.file.content(file_id) → 获取当前版本\n2) kdoc.version.list(file_id) → 获取历史版本\n3) kdoc.compare.diff(current, history) → 差异高亮\n4) kdoc.compare.summary(current, history) → 变更摘要\n5) kdoc.compare.export(current, history, format=\"html\") → 导出报告\n```\n\n---\n\n## 14. 可视化品类合并（v3.5.0 精简 9→8 品类，v3.6.0 进一步精简为 7 品类）\n\n> 为降低认知门槛、统一渲染管线，v3.6.0 将思维导图和流程图合并为「可视化」品类。\n\n### 14.1 合并前后对比\n\n| 合并前（v3.5.0 8 品类） | 合并后（v3.6.0 7 品类） |\n|-------------------------|-------------------------|\n| 文档 / 电子表格 / 演示文稿 / 多维表格 / 收集表 / **思维导图** / **流程图** / 附件 | 文档 / 电子表格 / 演示文稿 / 多维表格 / 收集表 / **可视化** / 附件 |\n\n### 14.2 子命令路由\n\n合并后用户仍可用原有表达方式，引擎自动识别子命令：\n\n| 用户表达 | 品类 | 子命令 |\n|---------|------|--------|\n| \"画一个思维导图\" | visualization | mindmap |\n| \"画一个流程图\" | visualization | flowchart |\n| \"画个脑图\" | visualization | mindmap |\n\n### 14.3 共享渲染管线\n\n```\n用户意图 → 品类路由 → visualization\n ↓\n 子命令识别：mindmap 或 flowchart\n ↓\n 共享 mermaid→SVG 渲染管线\n ↓\n 上传为在线文档\n```\n\n### 14.4 引擎逻辑不变\n\n- 底层仍调用 `engine/local/generators.py` 的 `MindmapGenerator` / `FlowchartGenerator`\n- 渲染方式仍为 mermaid→SVG→上传覆盖\n- 仅改品类元数据（`engine/categories.py`）+ 路由表\n\n---\n\n## 15. WPS AI 深度集成（v3.2 本地降级 → v3.6 段落级 AI 操作）\n\n> v3.2 已实现全文级 AI 写作辅助（polish/expand/shorten），v3.6 升级为**段落级 AI 深度集成**。\n\n### 15.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.wps_ai.rewrite` | AI 段落改写 | formal/casual/concise/elaborate |\n| `kdoc.wps_ai.summarize` | AI 段落总结 | 提取核心要点 |\n| `kdoc.wps_ai.continue` | AI 段落续写 | 根据方向继续写作 |\n\n### 15.2 工作流程\n\n```\n1) 用户在编辑器中选中段落\n2) 触发 AI 操作（改写/总结/续写）\n3) 适配器路由到本地降级后端\n4) 返回处理结果 → 用户确认 → 替换原段落\n5) 未来 WPS AI API 开放后，切换为原生后端，无需改上层代码\n```\n\n### 15.3 后端策略\n\n```\n当前（v3.6）：本地降级占位（返回原文+提示）\n未来：WPS AI 开放 API → 升级为原生后端（实现 WpsAiDeepBackend 接口即可）\n```\n\n---\n\n## 16. 文档模板市场（v3.6.0 新增，行业模板库一键复用）\n\n> 降低文档创建门槛，提供行业模板库 + 变量替换 + 一键生成。\n\n### 16.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.template.list` | 列出所有可用模板 | 可按类别筛选 |\n| `kdoc.template.search` | 搜索模板 | 按关键词搜索 |\n| `kdoc.template.use` | 使用模板 | 变量替换生成文档 |\n| `kdoc.template.refresh` | 刷新模板仓库 | git pull |\n\n### 16.2 模板仓库结构\n\n```\ntemplates/\n├── meeting.md # 会议纪要模板\n├── weekly-report.md # 周报模板\n├── project-plan.md # 项目计划模板\n├── contract.md # 合同模板\n├── pitch-deck.md # 融资路演模板\n└── ...\n```\n\n### 16.3 变量替换\n\n模板使用 `{{变量名}}` 语法，使用时传入变量字典：\n\n```yaml\n---\nname: weekly-report\ncategory: 工作汇报\ndescription: 标准周报模板\n---\n\n# {{title}}\n> 作者：{{author}} | 日期：{{date}}\n\n## 本周完成\n{{completed}}\n\n## 下周计划\n{{plan}}\n\n## 风险与风险\n{{risks}}\n```\n\n调用：`kdoc.template.use(\"weekly-report\", {\"title\": \"周报\", \"author\": \"张三\", ...})`\n\n### 16.4 工作流程\n\n```\n1) kdoc.template.list() → 列出可用模板\n2) 用户选择模板 → kdoc.template.use(name, variables)\n3) 引擎替换变量 → 生成 Markdown → 保存到 output/\n4) 返回生成内容 + 文件路径\n5) 可选：上传为在线文档\n```\n\n---\n\n## 17. 多维表格视图增强（v3.7.0 新增，对标 Airtable）\n\n> 对标 Airtable 的多维表格视图能力，支持看板/日历/甘特图三种视图。\n> 零第三方依赖，本地渲染引擎。\n\n### 17.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.view.render` | 视图渲染 | kanban / calendar / gantt |\n| `kdoc.view.list` | 列出可用视图 | 返回视图类型清单 |\n\n### 17.2 视图类型\n\n| 视图 | 说明 | 适用场景 |\n|------|------|---------|\n| 看板 | 按状态字段分组卡片 | 任务管理/项目跟踪 |\n| 日历 | 按日期字段月/周布局 | 日程/活动排期 |\n| 甘特图 | 时间轴+任务依赖 | 项目进度管理 |\n\n### 17.3 工作流程\n\n```\n1) kdoc.dbt.record.query → 获取多维表格记录\n2) kdoc.view.render(view_type=\"kanban\", data={records, fields})\n3) 本地引擎渲染 → 返回结构化 JSON\n4) 前端可视化展示（不依赖外部 API）\n```\n\n### 17.4 硬件自适应\n\n- 视图渲染使用 `hardware.py` 的 `workers` 限制并发\n- 大数据集（>1000 行）自动分页\n\n---\n\n## 18. 手写/公式识别 OCR（v3.7.0 新增，教育场景）\n\n> 覆盖教育手写公式场景，强制本地 Tesseract，数据不出域。\n\n### 18.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.ocr.formula` | 数学公式识别 | 图片 → LaTeX/MathML |\n| `kdoc.ocr.education` | 教育场景统一入口 | 自动判断手写/公式/混合 |\n| `kdoc.local.ocr.extract` | 基础 OCR（v3.7.0 升级） | 强制本地，数据不出域 |\n\n### 18.2 降级策略\n\n```\n优先级：本地 Tesseract → 提示安装（❌ 禁止调用外部 OCR API）\n```\n\n### 18.3 工作流程\n\n```\n1) kdoc.ocr.education(image_path, scene=\"auto\")\n2) 自动判断场景：handwriting / formula / mixed\n3) 返回文本 + LaTeX（如有公式）\n4) 可选：生成 DOCX/PPTX 文档\n```\n\n---\n\n## 19. 历史管理（v3.7.0 新增，合并回收站+版本历史）\n\n> 统一入口管理回收站和版本历史，降低认知门槛。\n\n### 19.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.history.list` | 列出历史记录 | trash / version |\n| `kdoc.history.restore` | 恢复文件 | 还原/回滚 |\n| `kdoc.history.destroy` | ⚠️ 彻底删除 | 仅回收站 |\n\n### 19.2 统一 CLI 接口\n\n```bash\nkdoc history list --from trash|version [--limit 20]\nkdoc history restore --from trash|version [--version ]\nkdoc history destroy # ⚠️ 需二次确认\n```\n\n### 19.3 工作流程\n\n```\n1) kdoc.history.list(\"trash\") → 回收站文件列表\n2) kdoc.history.list(\"version\", file_id=xxx) → 版本历史\n3) kdoc.history.restore(file_id, \"trash\") → 从回收站还原\n4) kdoc.history.restore(file_id, \"version\", version=3) → 回滚到第 3 版\n5) ⚠️ kdoc.history.destroy(file_id) → 彻底删除（需二次确认）\n```\n\n---\n\n## 20. 完整场景案例（v3.0.0 新增，v3.7.0 更新）\n\n### 场景 A：月度销售复盘（全链路）\n```\n1) kdoc.et.create(name=\"2026-07 销售复盘\")\n2) kdoc.et.range.write(sheet_id, \"A1:C21\", 表头+20 行数据) ← 批量写入\n3) kdoc.et.formula.set(sheet_id, \"D2\", \"=C2*0.1\") ← 提成列\n4) kdoc.office.convert(file_id, \"pdf\") ← 导出 PDF\n5) kdoc.notification.send(channel=\"wecom\", content=\"复盘已生成\")\n```\n\n### 场景 B：合同 OCR → 在线文档（免密钥本地优先）\n```\n1) kdoc.local.ocr.extract(\"contract.jpg\") ← 本地 Tesseract，无需 Key\n2) kdoc.local.docx.generate(content=, template=\"contract\")\n3) kdoc.file.upload(file_path=\"output.docx\") ← 上传为在线文档\n```\n\n### 场景 C：项目规划脑图 + 流程图（本地渲染）\n```\n1) kdoc.local.mindmap.generate(code=\"graph TD; 目标-->阶段1; 阶段1-->任务A\")\n2) kdoc.local.flowchart.generate(code=\"flowchart TD; 开始([开始])-->审核{通过?}\")\n3) 分别 kdoc.file.upload 两个 SVG → 在线可视化\n```\n\n### 场景 D：误删恢复（金山独有）\n```\n1) kdoc.trash.list(limit=20)\n2) kdoc.trash.recover(file_id) ← 救回，不丢数据\n```\n\n### 场景 E：大批量导入（硬件自适应）\n```\n1) kdoc.local.hardware.profile → 取得 workers/batch_chunk\n2) 按 batch_chunk 分块调用 kdoc.batch.create\n3) kdoc.batch.query 轮询直至完成（并发不超过 workers，不卡机）\n```\n\n### 场景 F：多人协作冲突解决（v3.3.0 新增）\n```\n1) kdoc.version.list(file_id) → 获取最近 3 个版本（基准版 + A修改 + B修改）\n2) kdoc.conflict.detect(base, a, b) → 检测冲突块\n3) kdoc.conflict.merge(base, a, b) → 自动合并无冲突段 + 标注冲突段\n4) kdoc.conflict.diff(a, b) → Git 风格可视化\n5) 用户选择保留A/保留B/手动合并 → kdoc.conflict.resolve(strategy=\"keep_a\")\n6) ⚠️ 强制确认 → kdoc.file.upload 覆盖回云端\n```\n\n### 场景 G：政企文档合规检查（v3.4.0 新增）\n```\n1) kdoc.file.content(file_id) → 取全文\n2) kdoc.compliance.sensitive(text) → 扫描敏感词（命中\"反动\"、\"毒品\"等）\n3) kdoc.compliance.leak(text) → 检测数据泄露（手机号/身份证号脱敏）\n4) kdoc.compliance.classify(text) → 建议密级（如\"秘密\"）\n5) kdoc.compliance.format(file_path) → 格式规范检查（字体/字号/行距）\n6) 生成合规报告 → 用户确认 → 修复不合规项\n```\n\n### 场景 H：实时协同编辑（v3.5.0 新增）\n```\n1) kdoc.realtime.create(\"alice\") → Alice 创建协同文档\n2) kdoc.realtime.insert(\"alice\", 0, \"项目计划：\") → Alice 插入文本\n3) kdoc.realtime.insert(\"bob\", 5, \"第一阶段\") → Bob 同时插入\n4) kdoc.realtime.get_text(\"alice\") → Alice 看到合并后的文本\n5) kdoc.realtime.stats(\"alice\") → 查看协同统计\n```\n\n### 场景 I：文档对比（v3.5.0 新增）\n```\n1) kdoc.file.content(file_id) → 获取当前版本\n2) kdoc.version.list(file_id) → 获取历史版本\n3) kdoc.compare.diff(current, history) → 差异高亮\n4) kdoc.compare.summary(current, history) → 变更摘要\n5) kdoc.compare.export(current, history, format=\"html\") → 导出 HTML 报告\n```\n\n### 场景 J：7 品类智能路由（v3.6.0 更新）\n```\n1) 用户说\"帮我写一份智能文档\" → kdoc.category_resolve(\"智能文档\")\n → {category: \"doc\", sub_type: \"smart_note\", edit_method: \"local_generate_upload\"}\n2) 用户说\"画一个思维导图\" → kdoc.category_resolve(\"思维导图\")\n → {category: \"visualization\", sub_command: \"mindmap\", edit_method: \"local_render_upload\"}\n3) 用户说\"画一个流程图\" → kdoc.category_resolve(\"流程图\")\n → {category: \"visualization\", sub_command: \"flowchart\", edit_method: \"local_render_upload\"}\n4) kdoc.category_list() → 列出全部 7 品类\n```\n\n### 场景 K：WPS AI 段落改写（v3.6.0 新增）\n```\n1) 用户在编辑器中选中段落\n2) kdoc.wps_ai.rewrite(paragraph=\"这个方案很好，值得推广。\", style=\"formal\")\n → 返回改写后的段落（本地降级占位，API 开放后升级为原生）\n3) 用户确认 → 替换原段落\n```\n\n### 场景 L：模板市场一键生成（v3.6.0 新增）\n```\n1) kdoc.template.list() → 列出所有可用模板\n2) kdoc.template.search(\"周报\") → 搜索周报模板\n3) kdoc.template.use(\"weekly-report\", {\"title\": \"周报\", \"author\": \"张三\"})\n → 变量替换 → 生成 Markdown → 保存到 output/\n4) kdoc.file.upload(output_path) → 上传为在线文档\n```\n\n### 场景 M：多维表格看板视图（v3.7.0 新增）\n```\n1) kdoc.dbt.record.query(table_id) → 获取多维表格记录\n2) kdoc.view.render(view_type=\"kanban\", data={\"records\": [...], \"fields\": [...]})\n → 按\"状态\"字段分组卡片 → 返回看板 JSON\n3) 前端渲染：每列一个状态，卡片可拖拽\n```\n\n### 场景 N：数学公式 OCR 识别（v3.7.0 新增）\n```\n1) kdoc.ocr.formula(\"formula.png\", output_format=\"latex\")\n → 本地 Tesseract + 符号映射 → 返回 LaTeX\n2) kdoc.ocr.education(\"exam.jpg\", scene=\"auto\")\n → 自动判断手写/公式/混合 → 返回文本+LaTeX\n3) 可选：kdoc.local.docx.generate(content=latex) → 生成公式文档\n```\n\n### 场景 O：历史管理——误删恢复与版本回滚（v3.7.0 新增）\n```\n1) kdoc.history.list(\"trash\") → 列出回收站文件\n2) kdoc.history.restore(file_id, \"trash\") → 从回收站还原\n3) kdoc.history.list(\"version\", file_id=xxx) → 列出历史版本\n4) kdoc.history.restore(file_id, \"version\", version=3) → 回滚到第 3 版\n5) ⚠️ kdoc.history.destroy(file_id) → 彻底删除（需二次确认）\n```\n\n---\n\n## 12. 核心规则（铁律）\n\n1. 🚨 **品类隔离**：先 `kdoc.file.info` 识别品类再路由，**严禁跨品类操作**。\n2. 📦 **批量优先**：电子表格/多维表格连续 3+ 写入**必须**用批量接口。\n3. 🔒 **权限前置**：所有写入前**必须**校验权限。\n4. 🔄 **异步轮询**：批量/转换/剪藏**必须**子会话轮询，主会话保持响应。\n5. 🗑️ **软删除**：删除**必须**走回收站 API，不物理删除。\n6. 📝 **审计日志**：所有写操作**必须**记录本地审计日志。\n7. ⚡ **限流退避**：收到 429 **必须**自动指数退避（最多 5 次）。\n8. 🔀 **版本防冲突**：写入前获取 `version`，冲突时提示合并。\n9. ✅ **危险操作强制确认**（v3.0.0）：见第 6 节，**未确认不执行**。\n10. 🧠 **性能不拖累**：批量/渲染并发**不得超过** `kdoc.local.hardware.profile` 给出的 `workers`。\n\n---\n\n## 13. 能力边界与失败场景（v3.0.0 新增，务必看清）\n\n| 场景 | 会发生什么 | 应对 |\n|------|-----------|------|\n| 未配置 App Key | 所有 `*云端*` 工具返回 KD001 友好提示 | 改用 `kdoc.local.*` 免密钥工具 |\n| 文件 > 大文件阈值（默认 100MB，低端机 50MB） | 自动转异步上传 + 进度轮询；超限报 KD008 | 压缩或分卷 |\n| 多人同时编辑 | 写入带版本号，冲突报 KD007 | 拉最新版本→合并→重写 |\n| OCR 识别率低 | 扫描件需 ≥200DPI、光线均匀、无反光 | 提升清晰度或人工校对 |\n| 网络中断 | 自动重试（指数退避），关键操作支持离线暂存 | 稍后重试 |\n| 限流 429 | 自动退避，不会崩溃 | 等待后继续 |\n| 本地未装 Tesseract | OCR 降级云端（需 Key），都无则给安装指引 | 装 Tesseract（免费） |\n| 超大表格（>10 万行） | 分块写入，单批不超过 `batch_chunk` | 分批 |\n| 思维导图/流程图为 SVG 图片 | 无法在金山内二次编辑，保留源 mermaid | 改源码重渲染 |\n| 文字/演示只能整文件替换 | 无法逐段编辑 | 本地改源→重新上传覆盖 |\n\n**明确不支持**：本地直接修改已上传 DOCX/PPTX 的某一段（需整文件重生成）；\n对加密/损坏文件 OCR；超过配额的非付费批量操作。\n\n---\n\n## 14. 风险项与限制\n\n| 风险项 | 影响 | 规避 |\n|--------|------|------|\n| 账号权限未配置 | 无法调用任何 API | 首次使用引导绑定 App |\n| API 配额不足（测试 500/天） | 写入被拒 | 申请正式应用（10 万/天） |\n| 整文件替换限制 | 文字/演示无法逐段编辑 | 降级为「本地生成→上传覆盖」 |\n| OCR 依赖清晰度 | 识别率受图片质量影响 | 提示扫描件 ≥200DPI |\n| SVG 不可二次编辑 | 脑图/流程图为图片 | 导出本地 SVG 保留源 |\n| 大文件超时（>阈值） | 上传失败 | 异步上传 + 轮询 |\n| 版本冲突 | 多人编辑丢数据 | 写入前校验版本号 |\n| 网络依赖 | 云端功能需联网 | 关键操作离线暂存 |\n\n---\n\n## 15. 深度绑定在线文档（v3.0.0 强化）\n\nKingDoc **直连金山文档（WPS）开放平台原生 API**（`https://developer.kdocs.cn/api/v1/openapi`），\n而非简单桥接：\n\n- **原生能力全覆盖**：文件/文件夹/回收站/版本/权限/空间/通知/用户均调用官方端点。\n- **精细编辑**：电子表格走 `et` API（单元格/公式），多维表格走 `dbt` API（记录/字段/视图）。\n- **本地增强**：文字/演示/脑图/流程图用本地库生成**原生格式**（DOCX/PPTX/SVG）后上传覆盖，\n 既保真又免去服务端复杂排版。\n- **政企可用**：国内网络直连、文档全中文、权限模型对齐企业协作。\n\n---\n\n## 16. 四大 MCP 服务（v3.0.0 架构）\n\n| 服务名 | 工具前缀 | 职责 | 对标腾讯 |\n|--------|---------|------|---------|\n| `kingdoc-docs` | `kdoc.file.*` / `folder.*` / `space.*` / `trash.*` / `version.*` / `batch.*` / `notification.*` / `user.*` | 文件管理+回收站+版本+批量+通知+用户 | tencent-docs |\n| `kingdoc-docx` | `kdoc.local.docx.*` | 文字/智能文档/脑图/流程图 本地生成+上传+OCR | doc-mcp |\n| `kingdoc-pptx` | `kdoc.local.pptx.*` | 演示文稿 本地生成+上传 | slide-mcp |\n| `kingdoc-sheet` | `kdoc.et.*` / `kdoc.dbt.*` / `kdoc.form.*` | 表格/多维表/收集表 API 精细编辑 | sheet-mcp |\n\n> 4 个 MCP 服务共享同一 Token，可独立限流、独立降级。\n\n---\n\n## 17. 性能与硬件自适应（v3.0.0 新增，绝不拖累电脑）\n\n`engine/hardware.py` 在首次运行时**自动采集本机 CPU 核数/内存**并计算出安全并发：\n\n| 机器档位 | 并发子进程 `workers` | 批量分块 | 大文件阈值 |\n|---------|---------------------|---------|-----------|\n| 低端（≤2核/<4GB） | 1 | 50 | 50MB |\n| 普通 | min(核数,4) | 200 | 100MB |\n| 高端（≥8核/≥16GB） | min(核数,8) | 500 | 100MB |\n\n- 画像缓存到 `.kingdoc_hardware_profile.json`（30 分钟复用），不频繁探测。\n- 批量写表、脑图/流程图并行渲染**不得超过 `workers`**，保证用户电脑流畅。\n- AI 在执行批量/渲染任务前应调用 `kdoc.local.hardware.profile` 读取参数。\n\n```bash\npython -m engine.hardware # 查看本机画像与推荐参数\n```\n\n---\n\n## 18. 🚫 禁止上传的文件类型（v3.0.0 强化）\n\n为安全，用户「上传附件」默认拦截以下全部类型（来源：产品安全规范）：\n\n1. **Windows 可执行/批处理**：`.bat` `.cmd` `.ps1` `.vbs` `.exe` `.dll` `.lnk` `.msi`\n2. **Office 二进制文档**：`.docx` `.xlsx` `.pptx` `.doc` `.xls` `.ppt` `.xlsm` `.docm` `.pptm`\n3. **二进制镜像/安装包**：`.iso` `.dmg` `.zip` `.rar` `.7z` `.tar` `.gz` `.apk` `.jar`\n4. **系统缓存/隐藏文件**：`.DS_Store` `.git`（目录） `.env` `.log` `.tmp`\n5. **其他风险脚本**：`.sh` `.com` `.scr` `.hta` `.reg`\n\n**内部豁免**：技能「本地生成→上传覆盖」产物（`.docx/.pptx/.xlsx/.pdf/.svg/.png/.txt/.md`\n等）经 `internal=True` 通道上传，**仅限技能自身生成**，用户无法借道上传任意同类文件。\n命中拦截将抛出 `KD009`。详见 `references/security.md`。\n\n---\n\n## 19. 错误码\n\n| 错误码 | 含义 | 解决方案 |\n|--------|------|---------|\n| KD001 | Token 鉴权失败 | 重新执行 `setup` 授权（或改用本地免密钥工具） |\n| KD002 | 权限不足 | 升级应用权限或联系管理员 |\n| KD003 | 配额不足 | 申请提额 |\n| KD004 | 文档类型不匹配 | `kdoc.file.info` 确认品类后按路由表 |\n| KD005 | 文档不存在 | 检查 `file_id` |\n| KD006 | 限流（429） | 自动指数退避重试 |\n| KD007 | 版本冲突 | 获取最新版本后重写 |\n| KD008 | 文件过大 | 走异步上传 |\n| KD009 | 文件类型被拦截 | 见第 18 节禁止类型 |\n| KD010 | 服务暂不可用 | 稍后重试 |\n| KD011 | 参数错误 | 检查 `file_id`/`content` 等必填项 |\n| KD012 | 文件夹不存在 | 检查 `folder_id` |\n| KD013 | 收集表已截止 | 已过截止日期 |\n| KD014 | Webhook 回调失败 | 检查回调 URL |\n| KD015 | 转换失败 | 格式不支持或文件损坏 |\n\n---\n\n## 20. 🔄 自动更新提示与反馈\n\n**每天首次使用自动检查更新**（本地缓存，每天仅查一次，离线不打扰）。\n发现新版本时 AI 会主动提示升级，**不会自动安装**：\n\n```bash\n# 手动检查 / 仅看提醒文案\npython -m engine.update_check --version 3.0.0 --reminder\n```\n\n> 📮 **有更好建议**：njskills@agent.qq.com\n\n---\n\n## 更新日志\n\n| v4.0.0 | 2026-08-31 | 增加：本地桥接引擎 `engine/local_bridge.py`（wps-office-suite 双向互通：白名单探测 + SQLite 映射表 + 下行拉取/处理/覆盖 + 上行 mtime 监听同步 + JSON 契约 + 子进程超时自动关闭）；增加：记忆桥接引擎 `engine/memory_bridge.py`（zwjh 记忆库打通：白名单探测 + stdio JSON-RPC 调用 deposit + 关键事件写入长期记忆 + 未安装→本地待迁移日志 + 一次性导入）；增加：表单答卷收集统计 `engine/form_analytics.py`（答卷列表/内容接口 + 按题统计 + 交叉分析 + 未填名单 + 图表生成 + 导出 CSV/Excel + 写回智能文档）；增加：MCP 工具 12 个（kdoc.bridge.* 5 个、kdoc.memory.* 3 个、kdoc.form.* 4 个）；增加：桥接/记忆/表单场景案例；优化：SKILL.md 版本号 3.9.0→4.0.0；优化：description 增强到 21 项增强 |\n| v3.9.0 | 2026-08-24 | 增加：块级编辑引擎 `engine/blocks.py`（段落级在线编辑，block_id CRUD，块类型映射表，未知块类型跳过不中断）；增加：演示页替换引擎 `engine/page_swap.py`（双路径自动选择：页级更新/整文件替换 + 页数校验 diff）；增加：配额管理器 `engine/quota_manager.py`（SQLite 按天计数 500 次/天 + 令牌桶限速 5 req/s + 429 指数退避 + 批量任务硬件自适应削峰）；增加：格式转换引擎 `engine/format_converter.py`（补齐 jpg/png/txt 三类目标格式，全格式覆盖 pdf/jpg/png/txt/docx/xlsx/pptx/html/md，云端优先→本地兜底失败降级链）；增加：MCP 工具 9 个（kdoc.block.* 5 个、kdoc.page_swap 1 个、kdoc.quota.* 3 个、kdoc.office.convert.enhanced 1 个）；增加：块级编辑/页替换/配额管理/格式转换场景案例；优化：SKILL.md 版本号 3.8.0→3.9.0 |\n| v3.8.0 | 2026-08-22 | 增加：智能画布元素级编辑引擎 `engine/element_engine/`（元素CRUD + Markdown追加 + 增量同步，对标腾讯文档·智能画布）；增加：空间节点管理引擎 `engine/space_tree/`（目录树查询 + 链接节点创建 + 递归删除 + 目录可视化）；增加：全文搜索引擎 `engine/content_search/`（文档内容搜索 + 结果定位高亮，超越腾讯）；增加：统一删除入口 `kdoc.file_delete_unified`（合并软删除/彻底删除/直接删除）；增加：MCP 工具 10 个（kdoc.element.* 5 个、kdoc.space.* 4 个、kdoc.content_search.* 2 个、kdoc.file_delete_unified 1 个）；增加：智能画布/空间管理/全文搜索/统一删除场景案例；优化：品类路由表从 8→9（新增 smart_canvas + content_search）；优化：history 模块新增 delete() 统一方法 |\n| v3.7.0 | 2026-08-19 | 增加：多维表格视图增强引擎 `engine/views/`（看板/日历/甘特图三种视图，对标 Airtable，本地渲染，硬件自适应）；增加：手写/公式识别 OCR `engine/ocr/`（数学公式识别 LaTeX/MathML 输出，教育场景统一入口）；增加：历史管理模块 `engine/history/`（合并回收站+版本历史，统一 history list/restore 入口）；增加：MCP 工具 6 个（kdoc.view.* 2 个、kdoc.ocr.* 2 个、kdoc.history.* 3 个）；增加：多维表格视图增强/公式识别/历史管理场景案例；优化：OCR 升级为强制本地模式，数据不出域，移除云端调用路径；优化：品类路由表从 7→8（新增 history_mgmt） |\n| v3.6.0 | 2026-08-16 | 增加：文档模板市场引擎 `engine/template_marketplace.py`（git 仓库管理模板，支持 list/search/use/refresh，变量替换一键生成）；增加：WPS AI 深度集成（段落级 AI 操作：rewrite/summarize/continue，本地降级占位，API 开放后升级为原生）；增加：可视化品类合并 `engine/categories.py`（8→7 品类，合并 mindmap+flowchart→visualization，共享 mermaid 渲染管线）；增加：MCP 工具 7 个（kdoc.template.* 4 个、kdoc.wps_ai.* 3 个）；增加：可视化品类合并/WPS AI 深度集成/模板市场场景案例；优化：品类路由表从 8→7，引擎逻辑不变 |\n| v3.5.0 | 2026-08-08 | 增加：实时协同编辑引擎 `engine/realtime_collab.py`（序列 CRDT 自研实现，零第三方依赖）；增加：文档对比模块 `engine/doc_comparator.py`（复用 difflib，差异高亮+变更摘要+导出）；增加：品类元数据 `engine/categories.py`（9 品类精简为 8 品类，合并 doc+smart_note，子类型自动识别）；增加：MCP 工具 12 个（kdoc.realtime.* 5 个、kdoc.compare.* 3 个、kdoc.category.* 2 个、kdoc.file.* 品类路由更新）；增加：实时协同+文档对比+8 品类智能路由场景案例；优化：品类路由表从 9→8，引擎逻辑不变 |\n| v3.4.0 | 2026-07-30 | 增加：文档内容合规检查模块 `engine/compliance_check.py`（自研正则+规则引擎，零第三方依赖）；增加：敏感词扫描 `kdoc.compliance.sensitive`（内置词库+用户黑白名单）、数据泄露检测 `kdoc.compliance.leak`（手机号/身份证号/银行卡号/邮箱，Luhn+校验码验证）、格式规范检查 `kdoc.compliance.format`（DOCX/PPTX/TXT/MD）、密级自动标注 `kdoc.compliance.classify`（公开/内部/秘密/机密）；增加：合规检查 MCP 工具 4 个；增加：敏感词库 `references/sensitive_words.txt`、格式规范 `references/format_spec.md`、用户黑白名单模板；增加：政企文档合规检查场景案例 |\n| v3.3.0 | 2026-07-21 | 增加：协同编辑冲突解决模块 `engine/conflict_resolver.py`（自研 difflib 实现，零第三方依赖）；增加：冲突检测 `kdoc.conflict.detect`、智能合并 `kdoc.conflict.merge`（自动合并无冲突段 + 标注冲突段）、Git diff 可视化 `kdoc.conflict.diff`、解决模板 `kdoc.conflict.resolve`（keep_a/keep_b/manual/auto_merge）；增加：冲突解决 MCP 工具 4 个；增加：大文档 diff 分块硬件自适应处理；增加：多人协作冲突解决场景案例；优化：冲突段强制用户确认，绝不自动覆盖 |\n| v3.2.0 | 2026-07-17 | 增加：WPS AI 能力适配层（写作辅助/数据分析/PPT 生成/阅读助手），本地降级优先、自研逻辑实现、零密钥可用；增加：WPS AI 适配器 `engine/wps_ai/adapter.py`；增加：本地降级后端 `engine/wps_ai/backends/local_fallback.py`；增加：能力定义与意图映射 `engine/wps_ai/capabilities.py`；增加：WPS AI API 调研记录 `engine/wps_ai/research_notes.md`；优化：MCP Server 注册 5 个 WPS AI 工具；优化：版本号 3.0.0→3.2.0 |\n| v3.1.0 | 2026-07-15 | 增加：wps-office-suite 互通方案调研（已废弃，因平台合规不允许双 skill 互通） |\n| v3.0.0 | 2026-07-12 | 增加：危险操作强制确认铁律与确认清单（删除/彻底删除/覆盖/批量/权限/清空回收站/版本回滚/Webhook）；增加：禁止文件类型扩展至完整 35 类（执行脚本/Office 二进制/归档镜像/系统文件/风险脚本）；增加：用户上传拦截与技能内部生成豁免白名单；增加：`engine/hardware.py` 硬件自适应性能调度（自动采集 CPU/内存，自动分配并发子进程数与批量分块）；增加：本地 OCR 模块 `engine/local/ocr.py`（优先本地 Tesseract，降级云端，给安装指引）；增加：能力边界与失败场景专章；增加：自然语言触发示例专章；增加：完整场景案例专章（5 个端到端场景）；增加：FAQ 专章（8 个高频问题）；补齐：缺失参考文档 `et_references.md`/`office_references.md`/`rate_limit.md`；补齐：技能图标 `assets/icon.png`；补齐：`engine/__init__.py` 与 `engine/api/mcp_server.py`（真实 MCP Server 入口）；优化：MCP Server 深度直连金山文档开放平台原生 API；优化：每日更新提醒 + 反馈邮箱 `njskills@agent.qq.com` |\n| v2.3.0 | 2026-07-05 | 增加：智能文档/思维导图/流程图 3 品类，品类总数 6→9；增加：本地 Tesseract OCR；增加：网页剪藏；增加：HTML 一键上云；优化：MCP 服务拆分 1→4，独立限流/降级 |\n| v2.1.0 | 2026-07-02 | 增加：每日自动更新检查；增加：纯文本提取 API；增加：多维表 Webhook 事件监听；增加：批量异步任务；增加：SKILL.md 首次使用必读引导 |\n| v2.0.0 | 2026-07-02 | 初始版本发布：6 品类 + 40+ MCP 工具 + 5 层安全防御 |\n\n---\n\n## 22. 详细文档参考\n\n| 文档 | 路径 |\n|------|------|\n| 鉴权流程 | `references/auth.md` |\n| 多维表格 API | `references/dbt_references.md` |\n| 电子表格 API | `references/et_references.md` |\n| 文本提取/格式转换 | `references/office_references.md` |\n| 限流/性能/硬件自适应 | `references/rate_limit.md` |\n| 安全设计 | `references/security.md` |\n| 错误码 | `references/error_codes.md` |\n| 常见工作流 | `references/workflows.md` |\n\n---\n\n## 23. 安装说明\n\n**前置要求**：Python 3.10+；云端功能需金山开放平台 App（免费）；OCR 可选装 Tesseract。\n\n```bash\n# Linux / macOS\nbash setup.sh\n# Windows (PowerShell)\npowershell -ExecutionPolicy Bypass -File setup.ps1\n```\n安装后重启 WorkBuddy 生效。本地生成/OCR/硬件画像无需任何配置即可用。\n\n---\n\n## 24. 📮 反馈与建议\n\n本技能持续迭代。有任何功能建议、问题或更好的实现思路，欢迎反馈：\n\n**📧 有更好建议：njskills@agent.qq.com**\n\n也可在每日更新提醒中一键查看新版本。\n\n---\n\n## 25. ❓ FAQ（v3.0.0 新增）\n\n**Q1：没有金山 App Key 能用吗？**\n能。本地生成 DOCX/PPTX、思维导图/流程图 SVG、本地 OCR、硬件画像均零密钥可用；\n仅「上传云端/多人协作/回收站/版本」等联网能力需 Key。\n\n**Q2：为什么删除前要确认？**\n防止误操作。删除进回收站可恢复；「彻底删除」「清空回收站」为不可逆操作，需二次确认（见第 6 节）。\n\n**Q3：OCR 一定要装 Tesseract 吗？**\n首选本地 Tesseract（免费、离线、无 key）。未装时自动降级云端 OCR（需 Key），都无则给出安装指引，不崩溃。\n\n**Q4：大文件传不上去？**\n超过阈值（默认 100MB，低端机 50MB）会自动转异步上传 + 轮询；仍失败请压缩或分卷。\n\n**Q5：会不会把我的电脑拖卡？**\n不会。技能自动按本机硬件分配并发子进程数（见第 17 节），批量/渲染均受限。\n\n**Q6：报 KD009 文件被拦截？**\n你上传的文件属于禁止类型（见第 18 节）。技能自身生成的 docx/pptx/pdf/svg 等不受影响。\n\n**Q7：如何升级？**\n每天首次使用会自动提醒；也可 `python -m engine.update_check --version 3.0.0 --reminder`。\n\n**Q8：文字/演示文档能改其中一段吗？**\n当前为整文件替换模式：本地改源文件→重新上传覆盖。逐段精细编辑需金山在线编辑器。\n\n---\n\n*最后更新：2026-08-31 | v4.0.0*\n\n---\n\n## 26. 块级编辑引擎（v3.9.0 新增，段落级在线编辑）\n\n> v3.8.0 实现了整文件替换和元素级编辑，v3.9.0 进一步下沉到**段落级块编辑**。\n> 以 `block_id` 为操作主键，直接修改文档中的某个段落/标题/列表/表格，无需整文件重生成。\n\n### 26.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.block.list` | 拉取文档块列表 | 返回所有块的结构化数据 |\n| `kdoc.block.replace` | 按 block_id 替换块 | 修改指定块的内容 |\n| `kdoc.block.insert` | 按 block_id 插入新块 | 在指定块前后插入 |\n| `kdoc.block.delete` | 按 block_id 删除块 | 删除指定块 |\n| `kdoc.block.move` | 按 block_id 移动块 | 调整块顺序 |\n\n### 26.2 块类型映射表\n\n| 金山 API 类型 | 内部类型 | 说明 |\n|-------------|---------|------|\n| paragraph | paragraph | 段落 |\n| heading | heading | 标题 |\n| list | list | 列表 |\n| table | table | 表格 |\n| image | image | 图片 |\n| divider | divider | 分隔线 |\n| code | code | 代码块 |\n| quote | quote | 引用 |\n| todo | todo | 待办事项 |\n| callout | callout | 提示框 |\n| equation | equation | 公式 |\n\n**未知块类型处理**：跳过并提示，绝不报错中断。\n\n### 26.3 工作流程\n\n```\n1) kdoc.block.list(file_id) → 获取块列表\n2) 用户定位要修改的 block_id\n3) kdoc.block.replace(file_id, block_id, new_content) → 替换内容\n4) 或 kdoc.block.insert(file_id, block_id, content, position=\"after\") → 插入新块\n5) 或 kdoc.block.delete(file_id, block_id) → 删除块\n6) 或 kdoc.block.move(file_id, block_id, target_id, position) → 移动块\n```\n\n### 26.4 安全约束\n\n- 块级编辑属于「覆盖文件」操作，**必须走强制确认铁律**\n- 批量替换时自动降并发（硬件自适应）\n- 未知块类型跳过并提示，不中断流程\n\n---\n\n## 27. 演示页替换引擎（v3.9.0 新增，双路径自动选择）\n\n> 单页内容本地 python-pptx 重生成后，探测演示 API 是否支持页级更新。\n> 支持则仅覆盖该页，不支持则整文件替换并在完成后 diff 提示页数校验。\n\n### 27.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.page_swap` | 替换指定页 | 自动选择页级更新或整文件替换 |\n\n### 27.2 双路径自动选择\n\n```\n1) 探测 API 是否支持页级更新\n ├── 支持 → 仅覆盖该页（API 调用）\n └── 不支持 → 整文件替换（本地重生成 + 上传覆盖）\n2) 替换完成后执行页数校验 diff\n3) 返回替换结果 + 页数变化提示\n```\n\n### 27.3 安全约束\n\n- 整文件替换属于「覆盖文件」危险操作，**必须走强制确认铁律**\n- 页数校验 diff 确保替换前后页数一致\n- 页数变化时明确提示用户\n\n---\n\n## 28. 配额管理器（v3.9.0 新增，API 配额与限流）\n\n> 保护测试与生产环境，避免 API 配额耗尽导致服务中断。\n\n### 28.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.quota.check` | 检查配额状态 | 返回剩余配额、使用率 |\n| `kdoc.quota.dashboard` | 配额看板 | 配额+令牌桶+硬件+小时分布 |\n| `kdoc.quota.batch_params` | 安全批量参数 | 硬件自适应削峰建议 |\n\n### 28.2 配额三件套\n\n| 组件 | 说明 | 配置 |\n|------|------|------|\n| SQLite 按天计数 | 记录每日请求量 | 默认 500 次/天 |\n| 令牌桶限速 | 控制请求速率 | 默认 5 req/s，突发 10 |\n| 429 指数退避 | 限流时自动重试 | 最多 5 次，最大 60 秒 |\n\n### 28.3 硬件自适应削峰\n\n```\n批量任务 → 读取 hardware.py → 计算安全并发\n → 读取配额余量 → 计算可执行任务数\n → 令牌桶限速 → 控制请求速率\n → 返回建议参数（workers, batch_chunk, 预估时间）\n```\n\n### 28.4 配额看板展示\n\n- 当日配额使用率（进度条）\n- 令牌桶状态（令牌数/速率/突发）\n- 小时分布图（峰值时段）\n- 硬件自适应建议\n- 推荐执行时段\n\n---\n\n## 29. 格式转换补全（v3.9.0 升级，全格式覆盖）\n\n> 补齐 jpg/png/txt 三类缺失的目标格式，全量覆盖参数校验与失败降级链。\n\n### 29.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.office.convert.enhanced` | 格式转换（增强版） | 云端优先 → 本地兜底 |\n\n### 29.2 支持的目标格式（v3.9.0 补齐后）\n\n| 格式 | 说明 | 本地兜底 |\n|------|------|---------|\n| pdf | PDF 文档 | LibreOffice |\n| jpg | JPEG 图片 | Pillow / ImageMagick |\n| png | PNG 图片 | Pillow / ImageMagick |\n| txt | 纯文本 | 直接提取 |\n| docx | Word 文档 | python-docx |\n| xlsx | Excel 表格 | openpyxl |\n| pptx | PPT 演示 | python-pptx |\n| html | HTML 文档 | 简单转换 |\n| md | Markdown | 简单转换 |\n\n### 29.3 失败降级链\n\n```\n云端转换（金山 API）\n ↓ 失败\n本地转换（python-docx / python-pptx / LibreOffice）\n ↓ 失败\n返回错误 + 安装指引\n```\n\n### 29.4 参数校验\n\n- 源格式与目标格式是否支持\n- 本地兜底是否可用（检查依赖）\n- 文件大小是否超限\n- 转换矩阵校验\n\n---\n\n## 30. 本地桥接引擎（v4.0 新增，wps-office-suite 双向互通）\n\n> 与 wps-office-suite 双向互通：白名单探测安装路径 + SQLite 映射表 + 子进程 JSON 契约。\n> 下行：云端→本地→wps 处理→回传覆盖；上行：mtime 监听→上传同步。\n\n### 30.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.bridge.status` | 桥接状态 | wps 安装状态、映射数量 |\n| `kdoc.bridge.download` | 下行：拉取云端文档 | 下载到本地临时目录 |\n| `kdoc.bridge.process` | 下行：wps 处理 | subprocess 调 wps 脚本 |\n| `kdoc.bridge.upload` | 上行：上传覆盖 | 本地文件覆盖云端 |\n| `kdoc.bridge.sync` | 上行：同步 | mtime 变化自动同步 |\n\n### 30.2 双向互通流程\n\n```\n下行（云端→本地→wps→云端）：\n kdoc.bridge.download → 拉取到临时目录\n kdoc.bridge.process → subprocess 调 wps 脚本（JSON 契约）\n kdoc.bridge.upload → 回传覆盖云端\n\n上行（本地变化→云端）：\n 监听映射表 mtime → 变化后自动上传同步\n```\n\n### 30.3 JSON 契约格式\n\n```json\n{\n \"action\": \"analyze|convert|format|extract\",\n \"input\": \"/path/to/local/file\",\n \"output\": \"/path/to/output\",\n \"params\": {}\n}\n```\n\n### 30.4 安全约束\n\n- 子进程超时自动关闭（120 秒）\n- 白名单探测，不扫描全盘\n- 未安装 wps：入口隐藏，云端功能不受影响\n\n---\n\n## 31. 记忆桥接引擎（v4.0 新增，zwjh 记忆库打通）\n\n> 文档关键事件（创建/重要编辑/分享）经 zwjh MCP 总线写入长期记忆。\n> 用户问 zwjh 上周改了什么文档时可答。\n\n### 31.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.memory.status` | 记忆桥接状态 | zwjh 安装状态、待迁移事件数 |\n| `kdoc.memory.deposit` | 发送事件 | 写入 zwjh 或待迁移日志 |\n| `kdoc.memory.migrate` | 一次性导入 | 待迁移事件批量写入 zwjh |\n\n### 31.2 工作流程\n\n```\n文档事件 → deposit_event()\n ├── zwjh 已安装 → stdio JSON-RPC 调用 deposit → 写入长期记忆\n └── zwjh 未安装 → 写入本地待迁移日志 → 未来安装后 migrate 一次性导入\n```\n\n### 31.3 安全约束\n\n- 子进程超时自动关闭（30 秒）\n- 不打包 zwjh 代码，仅走标准 MCP stdio 协议\n- 未安装 zwjh：事件写本地，不丢失\n\n---\n\n## 32. 表单答卷收集统计（v4.0 新增，云端数据本地智能加工）\n\n> 拉取答卷自动聚合（按题统计、交叉分析、未填名单），结果写回智能文档表格并生成图表页。\n\n### 32.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.form.analyze` | 分析答卷 | 按题统计 + 交叉分析 + 未填名单 |\n| `kdoc.form.export` | 导出答卷 | CSV / Excel |\n| `kdoc.form.chart_data` | 图表数据 | 供前端渲染 |\n| `kdoc.form.write_to_doc` | 写回智能文档 | 统计结果写入表格 |\n\n### 32.2 分析能力\n\n| 能力 | 说明 |\n|------|------|\n| 按题统计 | 选择题分布、数值题均值/最大/最小、文本题字数 |\n| 交叉分析 | 两两选择题关联分析 |\n| 未填名单 | 找出未填题的答卷 |\n| 图表生成 | 自动生成图表数据（饼图/柱状图/直方图） |\n\n### 32.3 安全约束\n\n- 硬件自适应：批量拉取时分块处理\n- 导出文件不落地敏感目录\n- 写回智能文档需用户确认\n\n---\n\n*最后更新：2026-08-31 | v4.0.0*\n\nFile v4.0.0:README.md\n\n# KingDoc — 金山文档 AI 协作助手\n\n> 让 AI 直接操作你的金山在线文档，创建、编辑、管理一站搞定。\n> **v4.0**：生态互通（桥接双通道）· wps-office-suite 双向桥接（本地文件↔云端文档，JSON 契约 + mtime 监听同步）· zwjh 记忆库打通（文档关键事件写入长期记忆，stdio JSON-RPC）· 表单答卷收集统计（按题统计 + 交叉分析 + 未填名单 + 图表生成 + 导出 Excel）· 块级编辑（段落级在线编辑，block_id CRUD）· 演示页替换（双路径自动选择 + 页数校验）· 配额管理器（SQLite 按天计数 + 令牌桶限速 5 req/s + 429 退避）· 格式转换全格式覆盖（jpg/png/txt 补齐，pdf/jpg/png/txt/docx/xlsx/pptx/html/md）· 智能画布元素级精细编辑（对标腾讯文档·智能画布）· 空间节点管理增强（目录树/链接节点/递归删除）· 文档内容全文搜索（超越腾讯：搜内容+结果定位高亮）· 多维表格视图增强（看板/日历/甘特图，对标 Airtable）· 手写/公式识别 OCR（教育场景，LaTeX/MathML 输出）· 历史管理（回收站+版本历史统一入口）· 深度直连 WPS 开放平台原生 API · 文档模板市场（行业模板库一键复用）· WPS AI 深度集成（段落级改写/总结/续写）· 实时协同编辑（序列 CRDT，多人无冲突）· 文档对比（差异高亮/变更摘要/导出）· 文档内容合规检查（敏感词/泄露/格式/密级）· 协同编辑冲突解决（检测/合并/diff/解决）· WPS AI 能力（写作/分析/PPT/阅读）· 硬件自适应性能 · 免密钥本地能力。\n\n## ✨ 特性\n\n- 📝 **9 品类全覆盖** — 文档/智能画布/表格/演示/多维表格/收集表/可视化/历史管理/全文搜索/附件\n- 🎨 **智能画布元素级编辑** — 对标腾讯文档·智能画布，元素 CRUD + Markdown 增量追加\n- 🔍 **全文搜索** — 超越腾讯：搜文档内容+结果定位高亮\n- 📊 **多维表格视图增强** — 看板/日历/甘特图，对标 Airtable，本地渲染\n- 🗂️ **空间节点管理** — 目录树/链接节点/递归删除/目录可视化\n- ✍️ **手写/公式识别** — 教育场景，LaTeX/MathML 输出，强制本地 Tesseract\n- 🕐 **历史管理** — 回收站+版本历史统一入口（list/restore/destroy/delete --force）\n- 🔗 **全生命周期** — 创建/编辑/删除/移动/复制/权限/版本历史/回收站\n- 🆚 **对标腾讯文档** — 腾讯有的全有，腾讯没有的也有（回收站/版本/转换/OCR/通知）\n- 🤖 **WPS AI 深度集成** — 写作辅助/数据分析/PPT 生成/阅读助手/段落改写/段落总结/段落续写，本地降级优先、零密钥可用\n- 🔄 **实时协同编辑** — 序列 CRDT 算法，多人同时编辑无冲突\n- 📊 **文档对比** — 差异高亮/变更摘要/导出报告，复用 difflib 引擎\n- 🔄 **协同冲突解决** — 冲突检测/智能合并/Git diff 可视化/解决模板，自研 difflib 实现\n- 📋 **文档合规检查** — 敏感词扫描/数据泄露检测/格式规范检查/密级标注，自研规则引擎\n- 🧠 **硬件自适应** — 自动按本机 CPU/内存分配并发，绝不拖累电脑\n- 📁 **文档模板市场** — 行业模板库一键复用，变量替换快速创建文档\n- 🔓 **免密钥本地能力** — 本地生成 DOCX/PPTX/脑图/流程图、本地 OCR、硬件画像、WPS AI，零配置\n- 🛡️ **安全优先** — 软删除/权限前置/限流退避/审计日志/危险操作强制确认/文件类型拦截\n\n## 🚀 快速开始\n\n### 1. 安装\n\n```bash\n# Linux / macOS\nbash D:\\skill\\kingdoc\\setup.sh\n# Windows (PowerShell)\npowershell -ExecutionPolicy Bypass -File D:\\skill\\kingdoc\\setup.ps1\n```\n\n### 2. 配置 App Key（仅云端协作需要）\n\n从 [金山开放平台](https://developer.kdocs.cn) 获取 AppID + AppSecret，安装脚本引导输入。\n**本地生成/OCR/硬件画像/WPS AI 无需 Key。**\n\n### 3. 直接使用\n\n对 WorkBuddy 说：\n- \"帮我写一份会议纪要\" → 本地生成并上传\n- \"把这个 PDF 传到云端\" → 上传（自动拦截禁止类型）\n- \"这份文档改坏了，回退到上周\" → 版本回滚\n- \"识别这张发票的文字\" → 本地 OCR（免密钥）\n- \"帮我润色这段文字\" → WPS AI 写作辅助（免密钥）\n- \"分析这列数据的趋势\" → WPS AI 数据分析（免密钥）\n- \"根据大纲生成 PPT\" → WPS AI PPT 生成（免密钥）\n- \"总结这份文档\" → WPS AI 阅读助手（免密钥）\n- \"把多维表格显示为看板\" → 多维表格视图增强（免密钥）\n- \"识别这个数学公式\" → 公式识别 OCR（免密钥）\n- \"恢复回收站里的文件\" → 历史管理（需 App Key）\n\n## 📖 支持的文档类型（8 品类）\n\n| 类型 | 创建 | 编辑 |\n|------|------|------|\n| 文字/智能文档 | ✅ 自动排版 | ✅ 本地生成+上传覆盖 |\n| 电子表格 | ✅ 自动创建 | ✅ 单元格/公式精细编辑 |\n| 演示文稿 | ✅ 自动排版 | ✅ 本地生成+上传覆盖 |\n| 多维表格 | ✅ 自动创建 | ✅ 记录/字段/视图精细编辑 |\n| 收集表 | ✅ 自动创建 | ✅ 配置+答卷管理 |\n| 可视化（思维导图/流程图） | ✅ 本地渲染 SVG | ✅ 上传覆盖 |\n| 历史管理（回收站+版本） | — | ✅ 列出/恢复/彻底删除/回滚 |\n| 附件上传 | ✅ — | — |\n\n## 📊 多维表格视图增强（v3.7.0 新增）\n\n| 视图 | 说明 | 适用场景 |\n|------|------|---------|\n| 看板 | 按状态字段分组卡片 | 任务管理/项目跟踪 |\n| 日历 | 按日期字段月/周布局 | 日程/活动排期 |\n| 甘特图 | 时间轴+任务依赖 | 项目进度管理 |\n\n## ✍️ 手写/公式识别 OCR（v3.7.0 新增）\n\n| 能力 | 工具 | 输出 |\n|------|------|------|\n| 数学公式识别 | `kdoc.ocr.formula` | LaTeX / MathML |\n| 教育场景 OCR | `kdoc.ocr.education` | 文本 + LaTeX |\n| 基础 OCR | `kdoc.local.ocr.extract` | 文本 |\n\n> 强制本地 Tesseract，数据不出域，零配置可用。\n\n## 🕐 历史管理（v3.7.0 新增）\n\n| 能力 | 工具 | 操作 |\n|------|------|------|\n| 列出历史 | `kdoc.history.list` | trash / version |\n| 恢复文件 | `kdoc.history.restore` | 还原/回滚 |\n| 彻底删除 | `kdoc.history.destroy` | ⚠️ 需二次确认 |\n\n## 🤖 WPS AI 能力（v3.2.0 新增）\n\n| 能力 | 工具 | 操作 |\n|------|------|------|\n| AI 写作辅助 | `kdoc.wps_ai.write` | 润色/扩写/缩写/续写/改写 |\n| AI 数据分析 | `kdoc.wps_ai.analyze` | 自然语言提问 → 统计+公式建议 |\n| AI PPT 生成 | `kdoc.wps_ai.ppt` | Markdown 大纲 → 自动生成 PPT |\n| AI 阅读助手 | `kdoc.wps_ai.read` | 总结/问答/思维导图 |\n| 意图检测 | `kdoc.wps_ai.detect_intent` | 识别用户输入匹配的能力 |\n\n> WPS AI 目前无公开开发者 API，采用**本地降级 + 自研逻辑**实现，零密钥可用。\n> 未来如 WPS AI 开放 API，只需新增后端即可升级。\n\n## 🧠 性能（不拖累电脑）\n\n首次运行自动采集硬件并分配并发子进程数：\n\n| 机器档位 | 并发子进程 | 批量分块 |\n|---------|-----------|---------|\n| 低端（≤2核/<4GB） | 1 | 50 |\n| 普通 | min(核数,4) | 200 |\n| 高端（≥8核/≥16GB） | min(核数,8) | 500 |\n\n## 🚫 安全：禁止上传的文件类型\n\n用户上传默认拦截：`.bat .cmd .ps1 .vbs .exe .dll .lnk .msi`、\n`.docx .xlsx .pptx .doc .xls .ppt .xlsm .docm .pptm`、\n`.iso .dmg .zip .rar .7z .tar .gz .apk .jar`、\n`.DS_Store .git .env .log .tmp`、`.sh .com .scr .hta .reg`。\n技能内部生成的 docx/pptx/pdf/svg 等经豁免通道上传。\n\n## 📚 文档\n\n- [SKILL.md](SKILL.md) — 完整功能参考（含 FAQ、能力边界、场景案例）\n- [references/security.md](references/security.md) — 安全设计\n- [references/rate_limit.md](references/rate_limit.md) — 限流与硬件自适应\n- [references/office_references.md](references/office_references.md) — 文本提取/格式转换\n\n## 🔄 更新与反馈\n\n每天首次使用自动提醒更新（不自动安装）。\n**有更好建议：njskills@agent.qq.com**\n\n## 📄 协议\n\nMIT License\n\nFile v4.0.0:_meta.json\n\n{\n \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n \"slug\": \"kingdoc\",\n \"version\": \"4.0.0\",\n \"publishedAt\": 1788255100366\n}\n\nFile v4.0.0:references/auth.md\n\n# 金山开放平台 API 参考\n\n> 本文档定义 KingDoc 与金山开放平台 API 的对接方式，包括鉴权、请求格式、错误处理和核心接口。\n\n---\n\n## 1. 鉴权概述\n\n### 1.1 获取 AppID / AppSecret\n\n1. 访问 [金山开放平台](https://developer.kdocs.cn)\n2. 创建一个新应用\n3. 获取 `App ID` 和 `App Secret`\n4. 在本地配置：`config.json`\n\n### 1.2 OAuth 2.0 Client Credentials\n\n```\nPOST https://open.kdocs.cn/oauth/token\n\nBody:\n grant_type = client_credentials\n client_id = \n client_secret = \n scope = user:file:write user:file:read team:file:write team:file:read\n```\n\n**响应**：\n\n```json\n{\n \"access_token\": \"eyJhbGciOiJIUzI1NiIs...\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 7200,\n \"scope\": \"user:file:write user:file:read\"\n}\n```\n\n### 1.3 使用 Token\n\n在请求 Header 中传递：\n\n```\nAuthorization: Bearer \n```\n\n---\n\n## 2. 基础 URL\n\n| 环境 | 基础 URL |\n|------|---------|\n| 生产环境 | `https://developer.kdocs.cn/api/v1/openapi` |\n| 沙箱环境 | `https://sandbox.kdocs.cn/api/v1/openapi` |\n\n---\n\n## 3. 统一响应格式\n\n所有 API 返回：\n\n```json\n{\n \"code\": 0,\n \"message\": \"OK\",\n \"data\": { ... },\n \"trace_id\": \"trace_abc123\"\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| code | int | 0 = 成功，非 0 = 错误 |\n| message | string | 状态信息 |\n| data | object | 业务数据（仅成功时存在） |\n| trace_id | string | 追踪 ID，排查问题用 |\n\n---\n\n## 4. 个人文档 API\n\n### 4.1 创建文档\n\n```\nPOST /personal/files\n\nBody:\n{\n \"name\": \"文档标题\",\n \"type\": \"doc\",\n \"folder_id\": \"可选，父文件夹 ID\",\n \"content\": \"可选，初始内容\"\n}\n```\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| name | string | ✅ | 文档标题 |\n| type | string | ✅ | 文档类型：doc / sheet / ppt / dbt / form |\n| folder_id | string | ❌ | 父文件夹 ID（不填为根目录） |\n| content | string | ❌ | 初始内容（Markdown） |\n\n**成功响应**：\n\n```json\n{\n \"code\": 0,\n \"message\": \"OK\",\n \"data\": {\n \"file_id\": \"file_abc123\",\n \"name\": \"文档标题\",\n \"type\": \"doc\",\n \"url\": \"https://docs.wps.cn/doc/file_abc123\",\n \"created_at\": 1719849600\n }\n}\n```\n\n### 4.2 获取文档内容\n\n```\nGET /personal/files/:file_id/content\n```\n\n**响应**：\n\n```json\n{\n \"code\": 0,\n \"data\": {\n \"file_id\": \"file_abc123\",\n \"content\": \"文档正文...\",\n \"version\": 3\n }\n}\n```\n\n### 4.3 更新文档内容\n\n```\nPUT /personal/files/:file_id/content\n\nBody:\n{\n \"content\": \"更新的内容\",\n \"version\": 3\n}\n```\n\n> ⚠️ `version` 必须与当前版本一致，否则返回版本冲突错误。\n\n### 4.4 删除文档（软删除）\n\n```\nDELETE /personal/files/:file_id\n```\n\n> ⚠️ 删除后文档进入回收站，可恢复。\n\n### 4.5 彻底删除\n\n```\nDELETE /personal/files/:file_id/permanent\n```\n\n---\n\n## 5. 空间/文件夹 API\n\n### 5.1 创建文件夹\n\n```\nPOST /personal/folders\n\nBody:\n{\n \"name\": \"文件夹名称\",\n \"parent_id\": \"可选，父文件夹 ID\"\n}\n```\n\n### 5.2 查询目录树\n\n```\nGET /personal/folders/children?folder_id=:id\n```\n\n### 5.3 查询面包屑路径\n\n```\nGET /personal/folders/breadcrumb?folder_id=:id\n```\n\n---\n\n## 6. 回收站 API\n\n### 6.1 查询回收站\n\n```\nGET /personal/trash/list?offset=0&limit=20\n```\n\n### 6.2 恢复文件\n\n```\nPOST /personal/trash/recover\n\nBody:\n{\n \"file_id\": \"file_abc123\"\n}\n```\n\n### 6.3 彻底删除\n\n```\nPOST /personal/trash/destroy\n\nBody:\n{\n \"file_id\": \"file_abc123\"\n}\n```\n\n---\n\n## 7. 版本历史 API\n\n### 7.1 查询版本\n\n```\nGET /appspace/versions?file_id=:file_id\n```\n\n### 7.2 回滚到某版本\n\n```\nPOST /appspace/versions/:version_id/restore\n\nBody:\n{\n \"file_id\": \"file_abc123\"\n}\n```\n\n---\n\n## 8. 批量操作 API\n\n### 8.1 创建批量任务\n\n```\nPOST /personal/tasks\n\nBody:\n{\n \"operation\": \"move\",\n \"file_ids\": [\"file_1\", \"file_2\"],\n \"target_folder_id\": \"folder_xxx\"\n}\n```\n\n### 8.2 查询任务结果\n\n```\nGET /personal/tasks/:task_id\n```\n\n---\n\n## 9. 电子表格精细编辑 API\n\n```\nPOST /et/cells/update # 更新单元格内容\nGET /et/cells/:sheet_id # 读取单元格\nGET /et/ranges/:sheet_id # 读取区域\nPUT /et/ranges/:sheet_id # 写入区域（批量）\nPOST /et/formula/set # 设置公式\nPOST /et/sheets # 添加工作表\nPUT /et/sheets/:sheet_id # 重命名工作表\nDELETE /et/sheets/:sheet_id # 删除工作表\n```\n\n---\n\n## 10. 多维表格（轻维表）API\n\n```\nPOST /dbt/tables # 创建多维表格\nGET /dbt/tables/:table_id # 获取表格结构\nPOST /dbt/fields # 添加字段\nPUT /dbt/fields/:field_id # 修改字段\nDELETE /dbt/fields/:field_id # 删除字段\nGET /dbt/views/:table_id # 列出视图\nPOST /dbt/views # 添加视图\nPOST /dbt/records # 添加记录\nPUT /dbt/records/:record_id # 更新记录\nDELETE /dbt/records/:record_id# 删除记录\nGET /dbt/records/:table_id # 查询记录\nPOST /dbt/webhooks # 设置 Webhook\n```\n\n---\n\n## 11. 收集表 API\n\n```\nPOST /personal/forms # 创建收集表\nGET /personal/forms/:form_id # 获取收集表\nPUT /personal/forms/:form_id # 修改收集表\nDELETE /personal/forms/:form_id# 删除收集表\nGET /personal/forms/:form_id/answers?offset=0&limit=50 # 查询答卷\nPOST /personal/forms/:form_id/submit # 提交答卷\n```\n\n---\n\n## 12. 格式转换 API\n\n```\nPOST /office/convert\n\nBody:\n{\n \"file_id\": \"file_abc123\",\n \"target_format\": \"pdf\"\n}\n```\n\n---\n\n## 13. 文档纯文本提取 API\n\n```\nPOST /office/extract\n\nBody:\n{\n \"file_id\": \"file_abc123\"\n}\n\nResponse:\n{\n \"code\": 0,\n \"data\": {\n \"text\": \"文档中的全部文字...\",\n \"file_id\": \"file_abc123\"\n }\n}\n```\n\n---\n\n## 14. 错误码\n\n| HTTP 状态码 | 错误码 | 含义 |\n|------------|--------|------|\n| 401 | KD001 | Token 无效或过期 |\n| 403 | KD002 | 权限不足 |\n| 404 | KD005 | 文档不存在 |\n| 409 | KD007 | 文档版本冲突 |\n| 413 | KD008 | 文件过大 |\n| 429 | KD006 | 请求限流 |\n| 500 | KD010 | 服务器内部错误 |\n\n---\n\n## 15. 限流策略\n\n| 应用类型 | 每日限额 |\n|---------|---------|\n| 测试应用（创建/修改/查询） | 500 次 |\n| 测试应用（权限/文件/用户） | 500 次 |\n| 测试应用（批量下载/上传/提取） | 500 次 |\n| 测试应用（内容编撰类） | 10000 次 |\n| 测试应用（批量任务） | 50-100 次 |\n| 正式应用（创建/修改/查询） | 100,000 次 |\n| 正式应用（批量下载/上传） | 100,000 次 |\n| 正式应用（内容编撰） | 10,000,000 次 |\n\n建议：尽早申请正式应用以获得充足限额。\n\n---\n\n*最后更新：2026-07-02*\n\nFile v4.0.0:references/dbt_references.md\n\n# 多维表格 API 参考\n\n> 轻维表（dbt）完整操作 API，对标腾讯文档智能表格。\n\n---\n\n## 1. 创建多维表格\n\n```\nPOST /dbt/tables\n\nBody:\n{\n \"name\": \"项目管理\",\n \"description\": \"团队项目跟踪\",\n \"folder_id\": \"可选\"\n}\n```\n\n**响应**：\n\n```json\n{\n \"code\": 0,\n \"data\": {\n \"table_id\": \"dbt_abc123\",\n \"name\": \"项目管理\"\n }\n}\n```\n\n---\n\n## 2. 字段管理\n\n### 2.1 添加字段\n\n```\nPOST /dbt/fields\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"name\": \"优先级\",\n \"type\": \"select\",\n \"options\": [\"P0\", \"P1\", \"P2\"],\n \"required\": true\n}\n```\n\n### 2.2 修改字段\n\n```\nPUT /dbt/fields/:field_id\n```\n\n### 2.3 删除字段\n\n```\nDELETE /dbt/fields/:field_id\n```\n\n### 2.4 列出字段\n\n```\nGET /dbt/fields/:table_id\n```\n\n---\n\n## 3. 视图管理\n\n### 3.1 添加视图\n\n```\nPOST /dbt/views\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"name\": \"按优先级分组\",\n \"type\": \"group\",\n \"config\": {\n \"field\": \"优先级\",\n \"order\": [\"P0\", \"P1\", \"P2\"]\n }\n}\n```\n\n---\n\n## 4. 记录操作\n\n### 4.1 新增记录\n\n```\nPOST /dbt/records\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"fields\": {\n \"项目名称\": \"知识库建设\",\n \"负责人\": \"张三\",\n \"优先级\": \"P1\"\n }\n}\n```\n\n### 4.2 批量新增（推荐）\n\n```\nPOST /dbt/records/batch\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"records\": [\n {\"fields\": {...}},\n {\"fields\": {...}},\n ...\n ]\n}\n```\n\n### 4.3 更新记录\n\n```\nPUT /dbt/records/:record_id\n```\n\n### 4.4 删除记录\n\n```\nDELETE /dbt/records/:record_id\n```\n\n### 4.5 查询记录\n\n```\nGET /dbt/records/:table_id?filter={...}&offset=0&limit=100\n```\n\n---\n\n## 5. Webhook\n\n### 5.1 设置 Webhook\n\n```\nPOST /dbt/webhooks\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"callback_url\": \"https://your-app.com/webhook\",\n \"events\": [\"record.add\", \"record.update\", \"record.delete\"],\n \"secret\": \"可选，用于签名验证\"\n}\n```\n\n### 5.2 列出 Webhook\n\n```\nGET /dbt/webhooks/:table_id\n```\n\n---\n\n## 6. 错误码\n\n| 错误码 | 含义 |\n|--------|------|\n| 字段已存在 | 尝试添加重复名称的字段 |\n| 字段被视图依赖 | 删除字段前需先删除依赖的视图 |\n| 记录不存在 | record_id 不存在 |\n| 表格不存在 | table_id 不存在 |\n| Webhook 回调失败 | 回调 URL 返回非 2xx 状态码 |\n\nFile v4.0.0:references/error_codes.md\n\n# KingDoc 完整错误码\n\n| 错误码 | 类型 | 含义 | 解决方案 |\n|--------|------|------|---------|\n| KD001 | AuthError | Token 鉴权失败 | 重新执行 setup 授权 |\n| KD002 | PermissionError | 权限不足 | 升级应用权限或联系管理员 |\n| KD003 | QuotaError | API 配额不足 | 申请提额或购买配额 |\n| KD004 | DocTypeError | 文档类型不匹配 | 执行 file.info 确认品类 |\n| KD005 | DocNotFoundError | 文档不存在 | 检查 file_id 是否正确 |\n| KD006 | RateLimitError | 请求限流（429） | 自动指数退避重试 |\n| KD007 | VersionConflictError | 文档版本冲突 | 获取最新版本后重新写入 |\n| KD008 | FileTooLargeError | 文件过大 | 走异步上传或压缩 |\n| KD009 | FileTypeBlockedError | 文件类型被拦截 | 检查 MIME 类型 |\n| KD010 | ServiceUnavailableError | 服务暂时不可用 | 稍后重试 |\n| KD011 | ParamError | 请求参数错误 | 检查必填参数 |\n| KD012 | FolderNotFoundError | 文件夹不存在 | 检查 folder_id |\n| KD013 | FormClosedError | 收集表已截止 | 收集表已过截止日期 |\n| KD014 | WebhookError | Webhook 回调失败 | 检查回调 URL |\n| KD015 | ConvertError | 格式转换失败 | 格式不支持或文件损坏 |\n\nFile v4.0.0:references/et_references.md\n\n# 电子表格 API 参考（kdoc.et.*）\n\n> 金山文档电子表格基于 WPS 开放平台 et API，支持**单元格级精细编辑**，是本技能区别于「整文件替换」品类的核心能力。\n\n## 基础约定\n\n- Base URL：`https://developer.kdocs.cn/api/v1/openapi`\n- 鉴权：`Authorization: Bearer `（由 `engine/auth.py` 自动注入并刷新）\n- 限流：429 自动指数退避（见 `references/rate_limit.md`）\n- 连续 3 次及以上写入**必须**使用批量接口（铁律 #2）\n\n## 工具清单\n\n### kdoc.et.create\n创建在线电子表格。\n\n```json\nPOST /et/sheets\n{ \"name\": \"销售数据\" }\n```\n返回：`{ \"file_id\": \"...\", \"url\": \"https://docs.wps.cn/sheet/...\" }`\n\n### kdoc.et.range.write\n批量写入单元格区域（**推荐，性能最佳**）。\n\n```json\nPUT /et/ranges/{sheet_id}\n{\n \"range\": \"A1:C10\",\n \"values\": [[\"产品\",\"销量\",\"金额\"],[\"A\",100,2000], ...]\n}\n```\n\n### kdoc.et.formula.set\n设置单元格公式。\n\n```json\nPOST /et/formula/set\n{ \"sheet_id\": \"\", \"cell\": \"D1\", \"formula\": \"=SUM(C1:C10)\" }\n```\n\n## 性能建议（硬件自适应）\n\n批量写入大小由 `engine/hardware.py` 自动决定（见 `references/rate_limit.md`），\n低端机默认 50 行/批，高端机 500 行/批，避免把内存撑爆。\n\n## 常见错误\n\n| 现象 | 原因 | 处理 |\n|------|------|------|\n| KD004 | sheet_id 与品类不符 | 先用 `kdoc.file.info` 确认是 sheet |\n| KD007 | 版本冲突 | 重新拉取最新版本后写入 |\n| KD011 | range 格式错误 | 使用 `A1:C10` 标准格式 |\n| KD006 | 限流 | 自动退避，无需人工干预 |\n\n*最后更新：2026-07-12 | v3.0.0*\n\nFile v4.0.0:references/format_spec.md\n\n# 企业文档格式规范\n\n## 字体规范\n- 正文：宋体，12pt\n- 一级标题：黑体，18pt，加粗\n- 二级标题：黑体，15pt，加粗\n- 三级标题：宋体，13pt，加粗\n- 英文/数字：Times New Roman\n\n## 段落规范\n- 行距：1.5倍行距\n- 段前：0行\n- 段后：0行\n- 首行缩进：2字符\n\n## 页边距\n- 上：2.54cm\n- 下：2.54cm\n- 左：3.17cm\n- 右：3.17cm\n\n## 标题层级\n- 一、（一级标题）\n- （一）（二级标题）\n- 1.（三级标题）\n- （1）（四级标题）\n\n## 其他\n- 正文每行不超过80字符\n- 长文档必须有 H1 标题\n- 图表必须有编号和标题\n\nFile v4.0.0:references/office_references.md\n\n# 文本提取 / 格式转换 API 参考（kdoc.office.*）\n\n> 金山文档独有增强能力，对标腾讯文档**无此功能**。\n\n## kdoc.office.convert — 格式转换\n\n```json\nPOST /office/convert\n{ \"file_id\": \"\", \"target_format\": \"pdf\" }\n```\n\n| 源 \\ 目标 | pdf | docx | xlsx | pptx |\n|-----------|-----|------|------|------|\n| 智能文档/文字 | ✅ | ✅ | — | — |\n| 电子表格 | ✅ | — | ✅ | — |\n| 演示文稿 | ✅ | — | — | ✅ |\n\n> 大文件（>阈值）自动转异步任务，`kdoc.batch.query` 轮询结果。\n\n## kdoc.office.extract — 纯文本提取\n\n```json\nPOST /office/extract\n{ \"file_id\": \"\" }\n```\n返回文档纯文本，便于检索、摘要、二次处理。\n\n## 本地 OCR（免密钥）\n\n见 `engine/local/ocr.py`：优先调用本机 Tesseract（免费、离线、零密钥），\n未安装则降级云端 OCR（需 App Key），都不可用给出安装指引。\n\n```python\nfrom engine.local.ocr import extract_text\nprint(extract_text(\"invoice.png\")) # 无需任何 key\n```\n\n## 常见错误\n\n| 错误码 | 含义 | 处理 |\n|--------|------|------|\n| KD015 | 转换失败 | 格式不支持或文件损坏，换源格式 |\n| KD008 | 文件过大 | 走异步上传 + 轮询 |\n| KD009 | 类型被拦截 | 见 `references/security.md` |\n\n*最后更新：2026-07-12 | v3.0.0*\n\nFile v4.0.0:references/rate_limit.md\n\n# 限流 / 性能 / 硬件自适应策略\n\n> 设计红线：**再快也不能拖累用户电脑**。所有并发与批量参数均由本机硬件自动决定。\n\n## 1. API 限流（429）退避\n\n`engine/rate_limiter.py` 实现指数退避 + 随机抖动：\n\n```\ndelay = min(2^retry + random(0,1), 300s) # 最多重试 5 次\n```\n\n`engine/client.py` 读取 `Retry-After` 头，结合退避，避免雪崩。\n\n## 2. 硬件自适应并发（v3.0.0 新增）\n\n`engine/hardware.py` 在首次运行时采集本机 CPU/内存，并缓存到\n`.kingdoc_hardware_profile.json`（30 分钟内复用），计算出：\n\n| 参数 | 低端机 (≤2核/<4GB) | 普通机 | 高端机 (≥8核/≥16GB) |\n|------|-------------------|--------|---------------------|\n| 并发子进程数 `workers` | 1 | min(核数,4) | min(核数,8) |\n| 批量写入分块 `batch_chunk` | 50 | 200 | 500 |\n| 大文件阈值 | 50MB | 100MB | 100MB |\n| 本地渲染并行 | 否 | 视核数 | 是 |\n\n调用方式：\n\n```python\nfrom engine.hardware import get_recommended_settings\ns = get_recommended_settings()\nprint(s[\"workers\"], s[\"batch_chunk\"], s[\"note\"])\n```\n\nAI 在批量生成思维导图/流程图、批量写表时，应读取该参数控制并行度，\n**绝不**超过 `workers`，保证用户电脑不卡顿。\n\n## 3. 会话级配额保护\n\n| 限制项 | 阈值 | 说明 |\n|--------|------|------|\n| 写入次数 | 100 次/会话 | 防止 AI 失控循环 |\n| 文件总大小 | 1GB/会话 | 防止批量大文件撑爆配额 |\n| API 调用 | 1000 次/会话 | 综合限制 |\n\n## 4. 批量合并\n\n50ms 窗口内连续写入自动合并为一次请求，进一步降低 API 压力。\n\n*最后更新：2026-07-12 | v3.0.0*\n\nFile v4.0.0:references/security.md\n\n# KingDoc 安全设计\n\n> 本文档定义 KingDoc Skill 的多层安全防御模型。\n\n---\n\n## 1. 安全架构总览\n\n```\n┌──────────────────────────────────────────────────┐\n│ 第 1 层：用户确认层 │\n│ - 删除/覆盖/批量操作必须用户显式确认 │\n│ - 可配置安全模式：始终确认 / 仅危险操作确认 │\n└──────────────────────────────────────────────────┘\n ↓\n┌──────────────────────────────────────────────────┐\n│ 第 2 层：权限前置校验层 │\n│ - 所有写入操作前自动检查用户权限 │\n│ - 无权限直接拒绝执行 │\n└──────────────────────────────────────────────────┘\n ↓\n┌──────────────────────────────────────────────────┐\n│ 第 3 层：输入校验层 │\n│ - file_id 格式正则校验 │\n│ - 路径遍历攻击过滤 │\n│ - 可执行文件 MIME 类型拦截 │\n│ - 大小限制（单文件 <500MB） │\n└──────────────────────────────────────────────────┘\n ↓\n┌──────────────────────────────────────────────────┐\n│ 第 4 层：操作保护层 │\n│ - 品类隔离（禁止跨品类操作） │\n│ - 版本冲突检测（写入带 version） │\n│ - 软删除（回收站 API，不物理删除） │\n│ - 审计日志（所有写操作记录） │\n└──────────────────────────────────────────────────┘\n ↓\n┌──────────────────────────────────────────────────┐\n│ 第 5 层：限流/配额层 │\n│ - 单次会话写入配额（防失控循环） │\n│ - API 级别限流（429 → 指数退避） │\n│ - 存储配额检查（写入前确认空间） │\n└──────────────────────────────────────────────────┘\n```\n\n---\n\n## 2. 用户确认层（Layer 1）\n\n### 2.1 确认触发条件\n\n以下操作**必须**经过用户显式确认：\n\n| 操作类型 | 确认内容 | 示例 |\n|---------|---------|------|\n| 删除文件 | 显示文件名 + 大小 | \"确认删除《2026年报告.doc》(2.3MB)？\" |\n| 覆盖文件 | 显示原文件版本 | \"确认覆盖当前文档？此操作不可撤销。\" |\n| 批量操作 | 显示数量 + 文件列表 | \"确认批量移动 50 个文件？\" |\n| 权限变更 | 显示目标用户 + 权限 | \"确认授予张三编辑权限？\" |\n| 回收站清空 | 显示数量 + 影响 | \"确认清空回收站？此操作不可恢复。\" |\n\n### 2.2 确认模式配置\n\n```json\n{\n \"safety\": {\n \"confirm_mode\": \"dangerous\", // \"always\" 或 \"dangerous\"\n \"dry_run\": false, // true 时只显示操作但不执行\n \"audit_enabled\": true\n }\n}\n```\n\n---\n\n## 3. 权限前置校验层（Layer 2）\n\n### 3.1 校验规则\n\n所有写入操作（create/update/delete/move/copy/permission change）执行**前**必须：\n\n1. 调用 `kdoc.file.permission.check` 检查当前用户权限\n2. 无权限直接终止，返回 `KD002` 错误\n3. 不发出任何修改请求\n\n### 3.2 权限类型\n\n| 权限 | 说明 | 可执行操作 |\n|------|------|-----------|\n| `owner` | 文档所有者 | 全部操作（含删除、权限变更） |\n| `editor` | 编辑者 | 编辑内容、移动、复制 |\n| `viewer` | 查看者 | 查看、下载、创建副本 |\n| `none` | 无权限 | 无 |\n\n---\n\n## 4. 输入校验层（Layer 3）\n\n### 4.1 file_id 校验\n\n```python\nimport re\n\nFILE_ID_PATTERN = re.compile(r'^[a-zA-Z0-9_-]{8,64}$')\n\ndef validate_file_id(file_id: str):\n if not FILE_ID_PATTERN.match(file_id):\n raise ParamError(f\"非法 file_id 格式: {file_id}\")\n```\n\n### 4.2 文件类型拦截（v3.0.0 强化）\n\n依据产品安全规范，用户「上传附件」默认拦截以下全部类型：\n\n```python\nBLOCKED_EXTENSIONS = {\n # 1. Windows 可执行 / 批处理脚本\n '.bat', '.cmd', '.ps1', '.vbs', '.exe', '.dll', '.lnk', '.msi',\n # 2. Office 二进制文档（默认拦截用户上传）\n '.docx', '.xlsx', '.pptx', '.doc', '.xls', '.ppt',\n '.xlsm', '.docm', '.pptm',\n # 3. 二进制镜像 / 安装包\n '.iso', '.dmg', '.zip', '.rar', '.7z', '.tar', '.gz', '.apk', '.jar',\n # 4. 系统缓存 / 隐藏文件\n '.ds_store', '.env', '.log', '.tmp',\n # 5. 其他风险脚本\n '.sh', '.com', '.scr', '.hta', '.reg',\n}\nBLOCKED_DIR_NAMES = {'.git', '.svn', '.hg', '.idea', '__pycache__'}\n```\n\n**内部豁免白名单**：技能「本地生成→上传覆盖」产物（docx/pptx/xlsx/pdf/svg/png\n/jpg/txt/md/csv/json/html）可经 `internal=True` 通道上传，**仅限技能自身生成**，\n用户无法借道上传任意同类文件，从源头杜绝可执行/脚本/归档流入云端。\n\n**禁止上传的 MIME 类型**（兜底）：\n\n```python\nBLOCKED_MIME_TYPES = {\n 'application/x-msdownload', 'application/x-executable', 'application/x-dosexec',\n 'application/x-msdos-program', 'application/x-powershell', 'text/javascript',\n 'application/javascript', 'application/x-vbs', 'application/x-bat',\n 'application/x-ms-installer', 'application/java-archive',\n 'application/vnd.microsoft.portable-executable'\n}\n```\n\n上传前统一调用 `engine.security.assert_upload_safe(filename, internal=...)` 校验。\n\n### 4.3 大小限制\n\n| 文件类型 | 大小限制 |\n|---------|---------|\n| 文字文档 | 100MB |\n| 电子表格 | 100MB |\n| 演示文稿 | 100MB |\n| 图片 | 20MB |\n| 附件 | 500MB |\n\n---\n\n## 5. 操作保护层（Layer 4）\n\n### 5.1 品类隔离\n\n- 通过 `kdoc.file.info` 识别文档品类\n- 使用场景路由表选择对应工具集\n- 严禁用 A 品类工具操作 B 品类文档\n\n### 5.2 版本冲突检测\n\n```\n读取文档 → 获取当前版本号 V1\n编辑准备 → 用户修改内容\n写入文档 → 携带版本号 V1\n如果服务端版本 != V1 → 返回 KD007 版本冲突\n提示用户：获取最新版本 → 合并 → 重新写入\n```\n\n### 5.3 软删除\n\n- 所有删除操作调用 `kdoc.file.delete`（→ 回收站）\n- **绝不调用** `kdoc.file.delete(permanent=true)`（除非用户显式要求）\n\n### 5.4 审计日志\n\n所有写操作记录以下信息：\n\n```json\n{\n \"timestamp\": \"2026-07-02T14:00:00+08:00\",\n \"operation\": \"file.create\",\n \"file_id\": \"file_abc123\",\n \"user_id\": \"user_xyz\",\n \"ip\": \"192.168.1.1\",\n \"success\": true,\n \"details\": {\"name\": \"会议纪要\", \"type\": \"doc\"}\n}\n```\n\n日志存储：本地文件 `kingdoc.log`\n\n---\n\n## 6. 限流/配额层（Layer 5）\n\n### 6.1 限流策略\n\n**收到 429 时的处理**：\n\n```python\nimport time\nimport random\n\ndef exponential_backoff(retry_count: int, max_retries: int = 5):\n if retry_count >= max_retries:\n raise RateLimitError(\"超过最大重试次数\")\n \n delay = min(2 ** retry_count + random.uniform(0, 1), 300)\n time.sleep(delay)\n return retry_count + 1\n```\n\n### 6.2 单次会话配额\n\n| 限制项 | 阈值 | 说明 |\n|--------|------|------|\n| 写入次数 | 100 次/会话 | 防止 AI 失控循环 |\n| 文件总大小 | 1GB/会话 | 防止批量大文件撑爆配额 |\n| API 调用 | 1000 次/会话 | 综合限制 |\n\n### 6.3 存储配额检查\n\n写入前检查用户空间剩余容量：\n\n```python\nquota = kdoc.space.quota()\nif quota[\"data\"][\"remaining\"] < file_size:\n raise QuotaError(\"空间不足，请先清理文件或扩容\")\n```\n\n---\n\n## 7. Token 安全\n\n| 规则 | 说明 |\n|------|------|\n| **不落盘** | Token 仅存在于内存中的 `KingDocAuth` 实例 |\n| **不输出** | 任何日志、消息中不包含完整 Token |\n| **有效期** | 2 小时，提前 5 分钟自动刷新 |\n| **范围最小化** | 默认只申请 `user:file:read` + `user:file:write` |\n\n---\n\n## 8. 文件上传安全\n\n### 8.1 上传前检查\n\n1. 文件扩展名是否在黑名单\n2. MIME 类型是否在黑名单\n3. 文件大小是否超限\n4. 目标文件夹是否可写\n\n### 8.2 上传后处理\n\n1. 服务端返回文件 ID\n2. 记录上传日志\n3. 可选：病毒扫描（如金山提供）\n\n---\n\n*最后更新：2026-07-02*\n\nFile v4.0.0:references/sensitive_words.txt\n\n# 敏感词库（适配中国监管要求）\n# 格式：每行一个词，# 开头为注释\n# 支持定期更新，支持用户自定义黑名单/白名单\n\n# 政治敏感\n反动\n分裂国家\n颠覆国家政权\n煽动颠覆\n煽动分裂\n暴乱\n恐怖主义\n极端主义\n民族仇恨\n民族歧视\n\n# 违法违规\n毒品\n枪支弹药\n爆炸物\n走私\n洗钱\n非法集资\n传销\n赌博\n色情\n淫秽\n嫖娼\n诈骗\n伪造\n假冒\n侵权\n\n# 商业违规\n虚假宣传\n虚假广告\n商业贿赂\n不正当竞争\n垄断\n侵犯商业秘密\n侵犯著作权\n侵犯商标\n\n# 社会敏感\n歧视\n侮辱\n诽谤\n造谣\n传谣\n诽谤他人\n人身攻击\n恶意中伤\n诽谤罪\n侮辱罪\n寻衅滋事\n聚众斗殴\n扰乱公共秩序\n\n# 隐私相关\n个人信息泄露\n非法收集\n非法买卖\n非法提供\n窃取个人信息\n\nArchive v3.9.0: 73 files, 156349 bytes\n\nFiles: engine/__init__.py (57b), engine/api/__init__.py (26b), engine/api/mcp_server.py (58728b), engine/api/tools.py (11767b), engine/auth.py (2767b), engine/blocks.py (14798b), engine/categories.py (9428b), engine/client.py (2956b), engine/compliance_check.py (20605b), engine/conflict_resolver.py (14007b), engine/content_search/__init__.py (186b), engine/content_search/searcher.py (3879b), engine/doc_comparator.py (9904b), engine/element_engine/__init__.py (489b), engine/element_engine/editor.py (8867b), engine/exceptions.py (2469b), engine/format_converter.py (29772b), engine/hardware.py (9144b), engine/history/__init__.py (258b), engine/history/manager.py (4177b), engine/history/trash.py (1889b), engine/history/version.py (1946b), engine/local/__init__.py (58b), engine/local/generators.py (7739b), engine/local/ocr.py (5128b), engine/ocr/__init__.py (563b), engine/ocr/education.py (3111b), engine/ocr/formula_recognizer.py (4429b), engine/ocr/local_ocr.py (4424b), engine/page_swap.py (14585b), engine/quota_manager.py (18021b), engine/rate_limiter.py (1137b), engine/realtime_collab.py (12651b), engine/security.py (5383b), engine/space_tree/__init__.py (181b), engine/space_tree/manager.py (4291b), engine/template_marketplace.py (9203b), engine/update_check.py (6083b), engine/views/__init__.py (999b), engine/views/base.py (1224b), engine/views/calendar.py (5336b), engine/views/gantt.py (4831b), engine/views/kanban.py (3237b), engine/wps_ai/__init__.py (75b), engine/wps_ai/adapter.py (3672b), engine/wps_ai/backends/__init__.py (49b), engine/wps_ai/backends/base.py (1601b), engine/wps_ai/backends/local_fallback.py (13830b), engine/wps_ai/capabilities.py (2293b), engine/wps_ai/research_notes.md (1830b), output/test_doc_r3.md (34b), output/test_doc.md (40b), output/test_doc2.md (22b), README.md (7882b), references/auth.md (6713b), references/dbt_references.md (2265b), references/error_codes.md (1247b), references/et_references.md (1646b), references/format_spec.md (627b), references/office_references.md (1335b), references/rate_limit.md (1693b), references/security.md (9332b), references/sensitive_words.txt (806b), references/user_blacklist.txt (123b), references/user_whitelist.txt (123b), references/workflows.md (7668b), scripts/env_check.sh (1542b), scripts/tests/test_file.py (2632b), setup.ps1 (2883b), setup.sh (3211b), skill-card.md (2881b), SKILL.md (56779b), _meta.json (126b)\n\nFile v3.9.0:SKILL.md\n\n---\nname: kingdoc\nversion: 3.9.0\ndescription: >\n 金山文档 AI 协作助手 — 9 品类在线文档全生命周期管理\n （文档/智能画布/电子表格/演示文稿/多维表格/收集表/可视化/历史管理/全文搜索/附件），\n 深度直连金山文档（WPS）开放平台原生 API，覆盖腾讯文档全部能力 + 金山独有 18 项增强\n （回收站、版本历史、格式转换（全格式覆盖 jpg/png/txt）、纯文本提取、本地 Tesseract OCR（强制本地，数据不出域）、\n 通知推送、Webhook、批量任务、政企合规、硬件自适应性能、WPS AI 能力、协同冲突解决、\n 文档合规检查、实时协同编辑、文档对比、WPS AI 深度集成、模板市场、多维表格视图增强、\n 手写/公式识别、历史管理、智能画布元素级编辑、全文搜索、块级编辑、演示页替换、配额管理器）。\n 文字/演示/可视化采用\"本地生成→上传覆盖\"，电子表格/多维表格采用 API 精细编辑。\n 智能画布支持元素级 CRUD + Markdown 增量追加。块级编辑实现段落级在线编辑替代整文件替换。\n 本地生成、OCR、硬件画像、WPS AI、全文搜索、块级编辑、配额管理等能力零密钥可用。\n---\n\n# KingDoc — 金山文档 AI 协作助手 v3.0.0\n\n> 对标腾讯文档 TENCENT DOCS，功能 1:1 覆盖 + 差异化增强。\n> **v3.0.0 重点：深度直连在线文档原生 API、危险操作强制确认、硬件自适应性能、免密钥本地能力。**\n\n---\n\n## 📣 评测反馈与本轮（v3.0.0）优化说明\n\n本版本针对第三方评测（综合 4.5/5「优秀」）的降分项做了**逐项闭环**：\n\n| 评测降分点 | v3.0.0 优化 |\n|-----------|------------|\n| 某些危险操作缺强制确认，可能误操作 | 新增「危险操作强制确认」铁律与确认清单（见第 6、12 节） |\n| 高级功能需额外装 Tesseract | 本地 OCR **免密钥**优先；未装 Tesseract 时降级云端，都无则给安装指引 |\n| 首次配置需 App Key，对新手复杂 | 明确「本地生成/OCR/硬件画像零配置可用」；云端仅上传/协作需 Key |\n| 能力边界说明少（大文件/失败场景） | 新增「能力边界与失败场景」专章（第 13 节） |\n| 触发方式不清晰（高级功能怎么说） | 新增「自然语言触发示例」专章（第 5 节） |\n| FAQ 不丰富、找不到答案 | 新增 FAQ 专章（第 25 节），安全/错误集中可查 |\n| 缺完整场景案例 | 新增「完整场景案例」专章（第 11 节） |\n| 创造性/增值不足 | 新增硬件自适应性能调度、网页剪藏、批量任务、Webhook 等增值能力 |\n| 性能可能拖累电脑 | 新增硬件自动采集 + 自动分配并发子进程数（第 17 节） |\n\n---\n\n## ⚠️ 首次使用必读\n\n### 1. 申请金山开放平台 App（免费，仅云端协作需要）\n\n**只影响「上传到云端 / 多人协作 / 回收站 / 版本」等联网能力。**\n本地生成文档、本地 OCR、硬件画像**完全不需要 Key，开箱即用**。\n\n申请步骤：\n1. 访问 [金山开放平台](https://developer.kdocs.cn) 并登录金山文档账号\n2. 进入「应用管理」→「创建应用」，获取 **`App ID`** 和 **`App Secret`**\n3. 勾选权限（OAuth Scope）：\n - 必须：`user:file:write`、`user:file:read`、`team:file:write`、`team:file:read`\n - 建议：`user:team:read`、`user:notification:write`\n4. 测试阶段限速 500 次/天，正式版 10 万次/天\n\n### 2. （可选）安装本地 Tesseract OCR\n\n仅「图片文字提取」需要；未装则自动降级云端 OCR 或给指引，**不影响其他功能**。\n\n```bash\n# Windows\nwinget install UB-Mannheim.TesseractOCR\n# macOS\nbrew install tesseract tesseract-lang\n# Linux\nsudo apt-get install tesseract-ocr tesseract-ocr-chi-sim\n```\n\n### 3. 配置并加载\n\n```bash\n# Linux/macOS\nbash setup.sh\n# Windows (PowerShell)\npowershell -ExecutionPolicy Bypass -File setup.ps1\n```\n脚本引导输入 App ID/Secret，自动生成 `config.json`、`mcp-config.json`、模板与图标，并采集本机硬件画像。\n\n---\n\n## 快速开始\n\n| 你想做什么 | 直接对 AI 说 |\n|-----------|-------------|\n| 新建会议纪要 | `\"帮我写一份会议纪要\"` |\n| 创建数据表 | `\"建一个销售数据表格，含产品/销量/金额\"` |\n| 生成 PPT | `\"帮我做一份产品发布 PPT\"` |\n| 生成思维导图 | `\"画一个项目计划的思维导图\"` |\n| 生成流程图 | `\"画一个用户下单流程图\"` |\n| 看文档内容 | `\"看看这个文档说了什么\"` |\n| 搜文件 | `\"搜一下上个月的合同\"` |\n| 上传本地文件 | `\"把这个 PDF 上传到云端\"` |\n| 识别图片文字 | `\"把这张发票的文字提取出来\"` |\n| 恢复误删 | `\"回收站里有没有昨天删的 Word？\"` |\n| 回滚版本 | `\"这份文档改坏了，回退到上周版本\"` |\n| 分享权限 | `\"给张三发个可编辑的链接\"` |\n| 归档文件夹 | `\"把文件移到 2026 项目文件夹\"` |\n| 格式转换 | `\"把这份文档转成 PDF\"` |\n\n---\n\n## 5. 自然语言触发示例（高级功能怎么表达）\n\n为避免「不知道怎么开口」，以下给可直接说的话：\n\n- **批量建表**：`\"新建客户管理多维表格，字段：客户名(文本)、签约金额(数字)、状态(单选)，并一次写入 20 条记录\"`\n- **格式转换**：`\"把《Q2 报告》导出成 PDF\"` / `\"转成 Word 发我\"`\n- **OCR 转文档**：`\"识别这张发票图片，生成一份 Word 报销单\"` / `\"把这张表格图片转成在线电子表格\"`\n- **网页剪藏**：`\"把这个网页 https://... 收藏成金山文档\"` \n- **通知推送**：`\"导入完成后用企微机器人通知我\"` \n- **版本回滚**：`\"列出这份文档的历史版本，回退到 7 月 1 日那版\"` \n- **权限管理**：`\"给团队文件夹『2026 项目』里的文档设置只读\"` \n- **本地免密钥生成**：`\"本地生成一份周报 DOCX，不用上传\"`（无需 App Key）\n\n---\n\n## 安全声明\n\n| 保护项 | 方式 |\n|--------|------|\n| 🔒 删除确认 | 删除走回收站 API，不物理删除 |\n| 🗑️ 软删除+恢复 | `trash.list → trash.recover` |\n| 📝 版本冲突检测 | 写入前获取最新版本号，冲突时提示用户合并 |\n| 🔐 权限前置校验 | 所有写入操作前自动检查权限，无权限拒绝 |\n| ⚡ 限流保护 | 429 自动指数退避重试（最多 5 次） |\n| 🛡️ 文件类型拦截 | 默认禁止上传 .exe/.bat/.ps1/.zip 等（见第 18 节） |\n| 🔑 Token 安全 | Token 仅存在于内存，不落盘 |\n| 📋 审计日志 | 所有写操作记录到本地日志 |\n| 🔀 批量合并 | 50ms 窗口内连续写入自动合并为一次请求 |\n| 🧠 硬件自适应 | 自动按本机 CPU/内存分配并发，不拖累电脑（第 17 节） |\n\n---\n\n## 6. 🚨 危险操作强制确认（v3.0.0 新增铁律）\n\n> 评测指出「部分危险操作缺少强制确认」。以下操作**执行前必须向用户显式确认**，\n> 列出具体影响，待用户明确同意后方可进行；**绝不**静默执行。\n\n| 危险操作 | 确认内容（必须展示给用户） |\n|---------|--------------------------|\n| 删除文件 `kdoc.file.delete` | 文件名 + 大小 + 「将进入回收站，可恢复」 |\n| **彻底删除** `kdoc.trash.destroy` | 文件名 + 「**不可逆**，将永久丢失」⚠️ 二次确认 |\n| 覆盖文件 `kdoc.file.upload` | 原文件版本 + 「覆盖后旧内容进入版本历史」 |\n| 批量操作 `kdoc.batch.*` | 操作类型 + 文件数量 + 文件清单预览 |\n| 权限变更 `kdoc.file.permission` | 目标成员 + 授予/收回的权限 |\n| 清空回收站 | 数量 + 「**不可恢复**」⚠️ |\n| 回滚版本 `kdoc.version.restore` | 目标版本 + 「当前内容将被历史版本替换」 |\n| Webhook 设置 | 回调 URL + 监听事件清单 |\n\n**确认模式**（config.json 可配）：\n```json\n{ \"safety\": { \"confirm_mode\": \"dangerous\", \"dry_run\": false, \"audit_enabled\": true } }\n```\n- `dangerous`（默认）：仅上表危险操作需确认\n- `always`：所有写操作均确认\n- `dry_run: true`：只展示将要执行的操作，不真正调用\n\n---\n\n## 支持的文档类型（9 品类）\n\n| 类型 | doc_type | 推荐度 | 创建 | 编辑 | 对标腾讯 | 实现方式 |\n|------|----------|--------|------|------|---------|---------|\n| 智能文档 | smart_note | ⭐⭐⭐ | ✅ 自动 | ✅ 本地生成+上传 | smartcanvas | Markdown→DOCX→上传覆盖 |\n| 文字文档 | doc | ⭐⭐⭐ | ✅ 自动 | ✅ 本地生成+上传 | doc | python-docx→上传覆盖 |\n| 智能画布 | smart_canvas | ⭐⭐⭐ | ✅ 自动 | ✅ 元素级 CRUD+增量追加 | 智能画布 | element_api + Markdown 追加 |\n| 电子表格 | sheet | ⭐⭐⭐ | ✅ 自动 | ✅ API 精细编辑 | sheet | 金山 et API（单元格/公式） |\n| 演示文稿 | ppt | ⭐⭐⭐ | ✅ 自动 | ✅ 本地生成+上传 | slide | python-pptx→上传覆盖 |\n| 多维表格 | smartsheet | ⭐⭐⭐ | ✅ 自动 | ✅ API 精细编辑 | smartsheet | 金山 dbt API（记录/字段/视图） |\n| 收集表 | form | ⭐⭐⭐ | ✅ 自动 | ✅ API 配置 | form | 金山 form API |\n| 可视化 | visualization | ⭐⭐⭐ | ✅ 自动 | ✅ 本地渲染+上传 | — | mermaid→SVG→上传 |\n| 历史管理 | history_mgmt | ⭐⭐⭐ | — | ✅ 统一管理 | — | 回收站+版本历史统一入口 |\n| 全文搜索 | content_search | ⭐⭐⭐ | — | ✅ 全文搜索 | — | 内容搜索 API（超越腾讯） |\n| 附件 | attachment | ⭐⭐⭐ | ✅ 自动 | — | — | 本地文件直接上传 |\n\n---\n\n## 核心能力矩阵\n\n### 1️⃣ 文档创建（9 品类全覆盖）\n\n| 用户意图 | 品类 | 创建方法 | 编辑方法 |\n|---------|------|---------|---------|\n| 报告/笔记/文章/纪要/markdown | smart_note / doc | `kdoc.file.create` | `kdoc.local.docx.generate` → 上传覆盖 |\n| PPT/幻灯片 | ppt | `kdoc.file.create` | `kdoc.local.pptx.generate` → 上传覆盖 |\n| 数据表格/Excel | sheet | `kdoc.et.create` | `kdoc.et.*` 精细编辑 |\n| 多维表格 | smartsheet | `kdoc.dbt.create` | `kdoc.dbt.*` 精细编辑 |\n| 表单/问卷 | form | `kdoc.form.create` | `kdoc.form.*` 配置 |\n| 思维导图 | mindmap | `kdoc.local.mindmap.generate` → 上传 | 生成 SVG→上传覆盖 |\n| 流程图 | flowchart | `kdoc.local.flowchart.generate` → 上传 | 生成 SVG→上传覆盖 |\n| 上传文件/图片/pdf | attachment | `kdoc.file.upload` | — |\n\n### 2️⃣ 文档编辑（改内容）\n\n先 `kdoc.file.info` 确定品类，再路由对应工具集。**严禁跨品类操作。**\n\n| 原始文档类型 | 编辑工具集 | 编辑粒度 |\n|------------|-----------|---------|\n| 智能文档/文字 | `kdoc.local.docx.generate` → 上传覆盖 | 整文件替换（自动重排） |\n| 演示文稿 | `kdoc.local.pptx.generate` → 上传覆盖 | 整文件替换 |\n| 电子表格 | `kdoc.et.cell.write` / `kdoc.et.range.write` | **单元格级** ✅ |\n| 多维表格 | `kdoc.dbt.record.*` / `kdoc.dbt.field.*` | **记录级** ✅ |\n| 收集表 | `kdoc.form.*` 配置 | 表单配置级 |\n| 思维导图/流程图 | `kdoc.local.mmd.generate` → 上传覆盖 | 整文件替换 |\n\n### 3️⃣ 文件管理\n\n| 动作 | 工具 |\n|------|------|\n| 重命名/移动/删除/复制 | `kdoc.file.*` |\n| 导入（本地→云端） | `kdoc.file.upload` |\n| 导出（云端→本地） | `kdoc.file.download` |\n| 权限/分享链接 | `kdoc.file.permission` / `kdoc.share.*` |\n| 回收站查询/恢复 | `kdoc.trash.list` / `kdoc.trash.recover` |\n| 版本历史/回滚 | `kdoc.version.list` / `kdoc.version.restore` |\n| 批量操作 | `kdoc.batch.create` → `kdoc.batch.query` |\n| 空间管理 | `kdoc.space.*` / `kdoc.folder.*` |\n\n### 4️⃣ 格式转换与 OCR\n\n| 场景 | 工具 | 实现方式 |\n|------|------|---------|\n| 文档→PDF/Word/Excel/PPT | `kdoc.office.convert` | 金山 API |\n| 纯文本提取 | `kdoc.office.extract` | 金山 API |\n| 图片 OCR 文字提取 | `kdoc.local.ocr.extract` | **本地 Tesseract（免密钥）/ 云端降级** |\n| 图片→Word | `kdoc.local.docx.generate(image_ocr=true)` | OCR→生成 DOCX→上传 |\n| 图片→Excel | `kdoc.et.create(data=ocr_table)` | OCR→解析表格→写入 |\n| 网页剪藏 | `kdoc.scrape.url` → `kdoc.file.create` | 抓取→创建文档 |\n| HTML 一键上云 | `kdoc.scrape.html` → `kdoc.file.upload` | 读取本地 HTML→上传 |\n\n### 5️⃣ 扩展能力（金山独有）\n\n| 能力 | 工具 | 说明 |\n|------|------|------|\n| 通知推送 | `kdoc.notification.send` | 企微/钉钉/金山协作机器人 |\n| 多维表格 Webhook | `kdoc.dbt.webhook.set` | 事件驱动监听表格变更 |\n| 空间额度用量 | `kdoc.space.quota` | 企业级管理视角 |\n| 用户信息 | `kdoc.user.info` | 获取用户/团队信息 |\n\n### 6️⃣ 本地免密钥工具（无需 App Key）\n\n| 工具 | 说明 |\n|------|------|\n| `kdoc.local.docx.generate` | 本地生成 DOCX（会议纪要/周报/合同） |\n| `kdoc.local.pptx.generate` | 本地生成 PPTX |\n| `kdoc.local.mindmap.generate` | 本地渲染思维导图 SVG |\n| `kdoc.local.flowchart.generate` | 本地渲染流程图 SVG |\n| `kdoc.local.ocr.extract` | 本地 OCR 提取图片文字 |\n| `kdoc.local.hardware.profile` | 采集本机硬件 + 推荐并发数 |\n\n### 7️⃣ WPS AI 能力（v3.2.0 新增，本地降级优先）\n\n> WPS AI 目前无公开开发者 API，本模块采用**本地降级 + 自研逻辑**实现，零密钥可用。\n> 未来如 WPS AI 开放 API，只需新增后端即可升级，无需改动上层。\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.wps_ai.write` | AI 写作辅助 | polish(润色) / expand(扩写) / shorten(缩写) / continue_write(续写) / rewrite(改写) |\n| `kdoc.wps_ai.analyze` | AI 数据分析 | 自然语言提问 → 基础统计 + 公式建议 |\n| `kdoc.wps_ai.ppt` | AI PPT 生成 | Markdown 大纲 → 自动生成 PPT |\n| `kdoc.wps_ai.read` | AI 阅读助手 | summarize(总结) / qa(问答) / mindmap(思维导图) |\n| `kdoc.wps_ai.detect_intent` | 意图检测 | 识别用户输入匹配的 WPS AI 能力 |\n\n**后端策略**：本地降级优先 → 未来可扩展 WPS Open API / COM 自动化 / Web API\n\n---\n\n## 10. 协同编辑冲突解决（v3.3.0 新增，自研 difflib 实现）\n\n> 多人同时编辑同一文档时经常出现冲突（A 修改了第 3 段，B 也修改了第 3 段）。\n> 本模块提供**冲突检测 + 智能合并 + 可视化 diff + 解决模板**，零外部依赖。\n\n### 10.1 冲突检测\n\n| 用户意图 | 直接对 AI 说 |\n|---------|-------------|\n| 检测冲突 | `「检测这两人修改的冲突」` |\n| 查看差异 | `「对比这两个版本的差异」` |\n| 自动合并 | `「帮我合并这两个版本」` |\n| 保留某版本 | `「保留 A 的版本」` / `「保留 B 的版本」` |\n\n### 10.2 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.conflict.detect` | 冲突检测 | 输入基准版+A版+B版 → 返回冲突块列表+统计 |\n| `kdoc.conflict.merge` | 智能合并 | 无冲突段自动合并，冲突段标注 `<<<<<<< VERSION_A` |\n| `kdoc.conflict.diff` | 冲突可视化 | 生成 Git diff 风格结构化数据 + 可选 HTML |\n| `kdoc.conflict.resolve` | 冲突解决 | keep_a / keep_b / manual / auto_merge |\n\n### 10.3 工作流程\n\n```\n① 检测：kdoc.version.list → 取最近 2-3 个版本 → conflict.detect() → 冲突块列表\n② 合并：conflict.merge() → 自动合并无冲突段 + 标注冲突段 → 合并建议\n③ 可视化：conflict.diff() → Git 风格并排 diff（可导出 HTML）\n④ 解决：用户选模板 → conflict.resolve() → ⚠️ 强制确认 → kdoc.file.upload 覆盖回云端\n```\n\n### 10.4 解决模板\n\n| 策略 | 说明 |\n|------|------|\n| `keep_a` | 保留用户 A 的版本 |\n| `keep_b` | 保留用户 B 的版本 |\n| `manual` | 手动编辑合并版本（需传 `manual_text`） |\n| `auto_merge` | 自动合并（仅无冲突段，冲突段保留标记） |\n\n### 10.5 安全约束\n\n- 合并结果覆盖回云端属于「覆盖文件」危险操作，**必须走强制确认铁律**（见第 6 节）\n- 冲突段**绝不自动覆盖**，必须用户明确选择\n- 大文档 diff 自动分块处理，不拖累电脑（硬件自适应）\n\n---\n\n## 11. 文档内容合规检查（v3.4.0 新增，自研正则+规则引擎）\n\n> 政企客户对文档内容有严格合规要求，手动检查耗时易遗漏。\n> 本模块提供**敏感词扫描 + 数据泄露检测 + 格式规范检查 + 密级标注**，零外部依赖。\n\n### 11.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.compliance.sensitive` | 敏感词扫描 | 输入全文 → 返回命中词+位置+上下文+风险等级 |\n| `kdoc.compliance.leak` | 数据泄露检测 | 扫描手机号/身份证号/银行卡号/邮箱 → 风险等级+脱敏显示 |\n| `kdoc.compliance.format` | 格式规范检查 | 输入文件路径 → 返回不合规清单（支持 DOCX/PPTX/TXT/MD） |\n| `kdoc.compliance.classify` | 密级自动标注 | 输入全文 → 建议密级（公开/内部/秘密/机密） |\n\n### 11.2 工作流程\n\n```\n① 敏感词扫描：kdoc.file.content → 取全文 → compliance.sensitive() → 命中列表+位置\n② 泄露检测：compliance.leak() → 正则匹配手机/身份证/银行卡/邮箱 → 风险等级\n③ 格式检查：kdoc.local.docx 解析 → compliance.format() → 不合规清单\n④ 密级标注：compliance.classify() → 关键词+规则 → 建议密级\n```\n\n### 11.3 敏感词库管理\n\n- **内置词库**：`references/sensitive_words.txt`（适配中国监管要求）\n- **用户黑名单**：`references/user_blacklist.txt`（追加自定义敏感词）\n- **用户白名单**：`references/user_whitelist.txt`（跳过误判词）\n- **定期更新**：替换 `sensitive_words.txt` 即可，无需改代码\n\n### 11.4 数据泄露检测能力\n\n| 类型 | 正则匹配 | 额外校验 | 风险等级 |\n|------|---------|---------|---------|\n| 手机号 | 1[3-9]\\d{9} | — | high |\n| 身份证号 | 18位 | 校验码验证 | critical |\n| 银行卡号 | 16-19位 | Luhn 算法 | critical |\n| 邮箱地址 | 标准邮箱正则 | — | medium |\n| IP地址 | IPv4 | — | low |\n\n### 11.5 格式规范检查\n\n| 检查项 | 规范 | 严重度 |\n|--------|------|--------|\n| 字体 | 宋体 | warning |\n| 字号 | 10-14pt | warning |\n| 行距 | 1.5倍行距 | info |\n| 页边距 | 2.54cm/3.17cm | info |\n| 行长度 | ≤80字符 | info |\n| 标题层级 | 长文档必须有 H1 | warning |\n\n### 11.6 密级标注规则\n\n| 密级 | 关键词示例 |\n|------|-----------|\n| 机密 | 绝密、核心机密、国家安全、军事机密、情报来源 |\n| 秘密 | 商业机密、技术机密、客户名单、未公开财报 |\n| 内部 | 内部资料、内部通知、仅限内部、不得外传 |\n| 公开 | 无匹配关键词 |\n\n---\n\n## 12. 实时协同编辑（v3.5.0 新增，序列 CRDT 自研实现）\n\n> 多人同时编辑同一文档时经常出现冲突（A 修改了第 3 段，B 也修改了第 3 段）。\n> v3.3 冲突解决是事后 difflib 合并，本模块升级为**实时 CRDT 协同**，多人同时编辑无冲突。\n\n### 12.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.realtime.create` | 创建协同文档 | 输入 client_id → 返回文档状态 |\n| `kdoc.realtime.insert` | 插入文本 | 输入位置+文本 → 返回操作列表 |\n| `kdoc.realtime.delete` | 删除文本 | 输入位置+长度 → 返回操作列表 |\n| `kdoc.realtime.get_text` | 获取当前文本 | 输入 client_id → 返回可见文本 |\n| `kdoc.realtime.stats` | 获取统计信息 | 输入 client_id → 返回字符数/操作数 |\n\n### 12.2 核心算法：序列 CRDT\n\n- 每个字符带唯一因果 ID（lamport timestamp + client_id + 序列号）\n- 插入/删除操作满足交换律，顺序无关\n- 删除标记 tombstone（保留因果关系，不真正移除）\n- 最终一致性：所有客户端收敛到相同状态\n- 无需中央服务器协调（P2P 友好）\n\n### 12.3 工作流程\n\n```\n1) kdoc.realtime.create(client_id) → 创建协同文档\n2) 用户 A 插入：kdoc.realtime.insert(\"alice\", 0, \"Hello\")\n3) 用户 B 同时插入：kdoc.realtime.insert(\"bob\", 5, \" World\")\n4) 操作自动广播给所有客户端\n5) kdoc.realtime.get_text(client_id) → 获取一致文本\n```\n\n---\n\n## 13. 文档对比（v3.5.0 新增，复用 difflib 引擎）\n\n> 对应 TOP50「文档对比检测器」，两版文档差异高亮。\n> 复用 conflict_resolver.py 的 difflib 引擎，提供面向用户的对比能力。\n\n### 13.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.compare.diff` | 差异高亮 | 输入两版文本 → 返回差异行+统计+相似度 |\n| `kdoc.compare.summary` | 变更摘要 | 输入两版文本 → 返回增删改统计+关键变化 |\n| `kdoc.compare.export` | 导出报告 | 输入两版文本 → 返回 Markdown/HTML 报告 |\n\n### 13.2 工作流程\n\n```\n1) kdoc.file.content(file_id) → 获取当前版本\n2) kdoc.version.list(file_id) → 获取历史版本\n3) kdoc.compare.diff(current, history) → 差异高亮\n4) kdoc.compare.summary(current, history) → 变更摘要\n5) kdoc.compare.export(current, history, format=\"html\") → 导出报告\n```\n\n---\n\n## 14. 可视化品类合并（v3.5.0 精简 9→8 品类，v3.6.0 进一步精简为 7 品类）\n\n> 为降低认知门槛、统一渲染管线，v3.6.0 将思维导图和流程图合并为「可视化」品类。\n\n### 14.1 合并前后对比\n\n| 合并前（v3.5.0 8 品类） | 合并后（v3.6.0 7 品类） |\n|-------------------------|-------------------------|\n| 文档 / 电子表格 / 演示文稿 / 多维表格 / 收集表 / **思维导图** / **流程图** / 附件 | 文档 / 电子表格 / 演示文稿 / 多维表格 / 收集表 / **可视化** / 附件 |\n\n### 14.2 子命令路由\n\n合并后用户仍可用原有表达方式，引擎自动识别子命令：\n\n| 用户表达 | 品类 | 子命令 |\n|---------|------|--------|\n| \"画一个思维导图\" | visualization | mindmap |\n| \"画一个流程图\" | visualization | flowchart |\n| \"画个脑图\" | visualization | mindmap |\n\n### 14.3 共享渲染管线\n\n```\n用户意图 → 品类路由 → visualization\n ↓\n 子命令识别：mindmap 或 flowchart\n ↓\n 共享 mermaid→SVG 渲染管线\n ↓\n 上传为在线文档\n```\n\n### 14.4 引擎逻辑不变\n\n- 底层仍调用 `engine/local/generators.py` 的 `MindmapGenerator` / `FlowchartGenerator`\n- 渲染方式仍为 mermaid→SVG→上传覆盖\n- 仅改品类元数据（`engine/categories.py`）+ 路由表\n\n---\n\n## 15. WPS AI 深度集成（v3.2 本地降级 → v3.6 段落级 AI 操作）\n\n> v3.2 已实现全文级 AI 写作辅助（polish/expand/shorten），v3.6 升级为**段落级 AI 深度集成**。\n\n### 15.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.wps_ai.rewrite` | AI 段落改写 | formal/casual/concise/elaborate |\n| `kdoc.wps_ai.summarize` | AI 段落总结 | 提取核心要点 |\n| `kdoc.wps_ai.continue` | AI 段落续写 | 根据方向继续写作 |\n\n### 15.2 工作流程\n\n```\n1) 用户在编辑器中选中段落\n2) 触发 AI 操作（改写/总结/续写）\n3) 适配器路由到本地降级后端\n4) 返回处理结果 → 用户确认 → 替换原段落\n5) 未来 WPS AI API 开放后，切换为原生后端，无需改上层代码\n```\n\n### 15.3 后端策略\n\n```\n当前（v3.6）：本地降级占位（返回原文+提示）\n未来：WPS AI 开放 API → 升级为原生后端（实现 WpsAiDeepBackend 接口即可）\n```\n\n---\n\n## 16. 文档模板市场（v3.6.0 新增，行业模板库一键复用）\n\n> 降低文档创建门槛，提供行业模板库 + 变量替换 + 一键生成。\n\n### 16.1 工具列表\n\n| 工具 | 说明 | 操作 |\n|------|------|------|\n| `kdoc.template.list` | 列出所有可用模板 | 可按类别筛选 |\n| `kdoc.template.search` | 搜索模板 | 按关键词搜索 |\n| `kdoc.template.use` | 使用模板 | 变量替换生成文档 |\n| `kdoc.template.refresh` | 刷新模板仓库 | git pull |\n\n### 16.2 模板仓库结构\n\n```\ntemplates/\n├── meeting.md # 会议纪要模板\n├── weekly-report.md # 周报模板\n├── project-plan.md # 项目计划模板\n├── contract.md # 合同模板\n├── pitch-deck.md # 融资路演模板\n└── ...\n```\n\n### 16.3 变量替换\n\n模板使用 `{{变量名}}` 语法，使用时传入变量字典：\n\n```yaml\n---\nname: weekly-report\ncategory: 工作汇报\ndescription: 标准周报模板\n---\n\n# {{title}}\n> 作者：{{author}} | 日期：{{date}}\n\n## 本周完成\n{{completed}}\n\n## 下周计划\n{{plan}}\n\n## 风险与风险\n{{risks}}\n```\n\n调用：`kdoc.template.use(\"weekly-report\", {\"title\": \"周报\", \"author\": \"张三\", ...})`\n\n##\n\nArchive v3.8.0: 69 files, 135189 bytes\n\nFiles: engine/__init__.py (57b), engine/api/__init__.py (26b), engine/api/mcp_server.py (51467b), engine/api/tools.py (11767b), engine/auth.py (2767b), engine/categories.py (9428b), engine/client.py (2956b), engine/compliance_check.py (20605b), engine/conflict_resolver.py (14007b), engine/content_search/__init__.py (186b), engine/content_search/searcher.py (3879b), engine/doc_comparator.py (9904b), engine/element_engine/__init__.py (489b), engine/element_engine/editor.py (8867b), engine/exceptions.py (2469b), engine/hardware.py (9144b), engine/history/__init__.py (258b), engine/history/manager.py (4177b), engine/history/trash.py (1889b), engine/history/version.py (1946b), engine/local/__init__.py (58b), engine/local/generators.py (7739b), engine/local/ocr.py (5128b), engine/ocr/__init__.py (563b), engine/ocr/education.py (3111b), engine/ocr/formula_recognizer.py (4429b), engine/ocr/local_ocr.py (4424b), engine/rate_limiter.py (1137b), engine/realtime_collab.py (12651b), engine/security.py (5383b), engine/space_tree/__init__.py (181b), engine/space_tree/manager.py (4291b), engine/template_marketplace.py (9203b), engine/update_check.py (6083b), engine/views/__init__.py (999b), engine/views/base.py (1224b), engine/views/calendar.py (5336b), engine/views/gantt.py (4831b), engine/views/kanban.py (3237b), engine/wps_ai/__init__.py (75b), engine/wps_ai/adapter.py (3672b), engine/wps_ai/backends/__init__.py (49b), engine/wps_ai/backends/base.py (1601b), engine/wps_ai/backends/local_fallback.py (13830b), engine/wps_ai/capabilities.py (2293b), engine/wps_ai/research_notes.md (1830b), output/test_doc_r3.md (34b), output/test_doc.md (40b), output/test_doc2.md (22b), README.md (7587b), references/auth.md (6713b), references/dbt_references.md (2265b), references/error_codes.md (1247b), references/et_references.md (1646b), references/format_spec.md (627b), references/office_references.md (1335b), references/rate_limit.md (1693b), references/security.md (9332b), references/sensitive_words.txt (806b), references/user_blacklist.txt (123b), references/user_whitelist.txt (123b), references/workflows.md (7668b), scripts/env_check.sh (1542b), scripts/tests/test_file.py (2632b), setup.ps1 (2883b), setup.sh (3211b), skill-card.md (3262b), SKILL.md (50455b), _meta.json (126b)\n\nArchive v3.7.0: 60 files, 107307 bytes\n\nFiles: engine/__init__.py (57b), engine/api/__init__.py (26b), engine/api/mcp_server.py (42456b), engine/api/tools.py (11767b), engine/auth.py (2767b), engine/categories.py (8460b), engine/client.py (2956b), engine/compliance_check.py (20605b), engine/conflict_resolver.py (14007b), engine/doc_comparator.py (9904b), engine/exceptions.py (2469b), engine/hardware.py (9144b), engine/history/__init__.py (258b), engine/history/manager.py (2434b), engine/history/trash.py (1889b), engine/history/version.py (1946b), engine/local/__init__.py (58b), engine/local/generators.py (7739b), engine/local/ocr.py (5128b), engine/ocr/__init__.py (563b), engine/ocr/education.py (3111b), engine/ocr/formula_recognizer.py (4429b), engine/ocr/local_ocr.py (4424b), engine/rate_limiter.py (1137b), engine/realtime_collab.py (12651b), engine/security.py (5383b), engine/template_marketplace.py (9203b), engine/update_check.py (6083b), engine/views/__init__.py (999b), engine/views/base.py (1224b), engine/views/calendar.py (5336b), engine/views/gantt.py (4831b), engine/views/kanban.py (3237b), engine/wps_ai/__init__.py (75b), engine/wps_ai/adapter.py (3672b), engine/wps_ai/backends/__init__.py (49b), engine/wps_ai/backends/base.py (1601b), engine/wps_ai/backends/local_fallback.py (13830b), engine/wps_ai/capabilities.py (2293b), engine/wps_ai/research_notes.md (1830b), README.md (7047b), references/auth.md (6713b...","readmeExcerpt":"Skill: kingdoc Owner: fyniujin Summary: 金山文档 AI 协作助手 — 9 品类在线文档全生命周期管理 （文档/智能画布/电子表格/演示文稿/多维表格/收集表/可视化/历史管理/全文搜索/附件）， 深度直连金山文档（WPS）开放平台原生 API，覆盖腾讯文档全部能力 + 金山独有 18 项增强 （回收站、版本历史、格式转换（全格式覆盖 jpg/png/t... Tags: latest:4.2.0 Version history: v4.2.0 | 2026-09-19T02:32:24.592Z | auto Kingdoc 4.2.0 introduces major enhancements and internal refactoring. - Added 10 new modules, including airscript, knowledge_hub, webhook_cent","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# Windows\nwinget install UB-Mannheim.TesseractOCR\n# macOS\nbrew install tesseract tesseract-lang\n# Linux\nsudo apt-get install tesseract-ocr tesseract-ocr-chi-sim"},{"language":"bash","snippet":"# Linux/macOS\nbash setup.sh\n# Windows (PowerShell)\npowershell -ExecutionPolicy Bypass -File setup.ps1"},{"language":"json","snippet":"{ \"safety\": { \"confirm_mode\": \"dangerous\", \"dry_run\": false, \"audit_enabled\": true } }"},{"language":"text","snippet":"① 检测：kdoc.version.list → 取最近 2-3 个版本 → conflict.detect() → 冲突块列表\n② 合并：conflict.merge() → 自动合并无冲突段 + 标注冲突段 → 合并建议\n③ 可视化：conflict.diff() → Git 风格并排 diff（可导出 HTML）\n④ 解决：用户选模板 → conflict.resolve() → ⚠️ 强制确认 → kdoc.file.upload 覆盖回云端"},{"language":"text","snippet":"① 敏感词扫描：kdoc.file.content → 取全文 → compliance.sensitive() → 命中列表+位置\n② 泄露检测：compliance.leak() → 正则匹配手机/身份证/银行卡/邮箱 → 风险等级\n③ 格式检查：kdoc.local.docx 解析 → compliance.format() → 不合规清单\n④ 密级标注：compliance.classify() → 关键词+规则 → 建议密级"},{"language":"text","snippet":"1) kdoc.realtime.create(client_id) → 创建协同文档\n2) 用户 A 插入：kdoc.realtime.insert(\"alice\", 0, \"Hello\")\n3) 用户 B 同时插入：kdoc.realtime.insert(\"bob\", 5, \" World\")\n4) 操作自动广播给所有客户端\n5) kdoc.realtime.get_text(client_id) → 获取一致文本"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: kingdoc\nversion: 4.2.0\ndescription: >\n---\n\n\n# KingDoc — 金山文档 AI 协作助手 v3.0.0\n\n> 对标腾讯文档 TENCENT DOCS，功能 1:1 覆盖 + 差异化增强。\n> **v3.0.0 重点：深度直连在线文档原生 API、危险操作强制确认、硬件自适应性能、免密钥本地能力。**\n\n---\n\n## 📣 评测反馈与本轮（v3.0.0）优化说明\n\n本版本针对第三方评测（综合 4.5/5「优秀」）的降分项做了**逐项闭环**：\n\n| 评测降分点 | v3.0.0 优化 |\n|-----------|------------|\n| 某些危险操作缺强制确认，可能误操作 | 新增「危险操作强制确认」铁律与确认清单（见第 6、12 节） |\n| 高级功能需额外装 Tesseract | 本地 OCR **免密钥**优先；未装 Tesseract 时降级云端，都无则给安装指引 |\n| 首次配置需 App Key，对新手复杂 | 明确「本地生成/OCR/硬件画像零配置可用」；云端仅上传/协作需 Key |\n| 能力边界说明少（大文件/失败场景） | 新增「能力边界与失败场景」专章（第 13 节） |\n| 触发方式不清晰（高级功能怎么说） | 新增「自然语言触发示例」专章（第 5 节） |\n| FAQ 不丰富、找不到答案 | 新增 FAQ 专章（第 25 节），安全/错误集中可查 |\n| 缺完整场景案例 | 新增「完整场景案例」专章（第 11 节） |\n| 创造性/增值不足 | 新增硬件自适应性能调度、网页剪藏、批量任务、Webhook 等增值能力 |\n| 性能可能拖累电脑 | 新增硬件自动采集 + 自动分配并发子进程数（第 17 节） |\n\n---\n\n## ⚠️ 首次使用必读\n\n### 1. 申请金山开放平台 App（免费，仅云端协作需要）\n\n**只影响「上传到云端 / 多人协作 / 回收站 / 版本」等联网能力。**\n本地生成文档、本地 OCR、硬件画像**完全不需要 Key，开箱即用**。\n\n申请步骤：\n1. 访问 [金山开放平台](https://developer.kdocs.cn) 并登录金山文档账号\n2. 进入「应用管理」→「创建应用」，获取 **`App ID`** 和 **`App Secret`**\n3. 勾选权限（OAuth Scope）：\n - 必须：`user:file:write`、`user:file:read`、`team:file:write`、`team:file:read`\n - 建议：`user:team:read`、`user:notification:write`\n4. 测试阶段限速 500 次/天，正式版 10 万次/天\n\n### 2. （可选）安装本地 Tesseract OCR\n\n仅「图片文字提取」需要；未装则自动降级云端 OCR 或给指引，**不影响其他功能**。\n\n```bash\n# Windows\nwinget install UB-Mannheim.TesseractOCR\n# macOS\nbrew install tesseract tesseract-lang\n# Linux\nsudo apt-get install tesseract-ocr tesseract-ocr-chi-sim\n```\n\n### 3. 配置并加载\n\n```bash\n# Linux/macOS\nbash setup.sh\n# Windows (PowerShell)\npowershell -ExecutionPolicy Bypass -File setup.ps1\n```\n脚本引导输入 App ID/Secret，自动生成 `config.json`、`mcp-config.json`、模板与图标，并采集本机硬件画像。\n\n---\n\n## 快速开始\n\n| 你想做什么 | 直接对 AI 说 |\n|-----------|-------------|\n| 新建会议纪要 | `\"帮我写一份会议纪要\"` |\n| 创建数据表 | `\"建一个销售数据表格，含产品/销量/金额\"` |\n| 生成 PPT | `\"帮我做一份产品发布 PPT\"` |\n| 生成思维导图 | `\"画一个项目计划的思维导图\"` |\n| 生成流程图 | `\"画一个用户下单流程图\"` |\n| 看文档内容 | `\"看看这个文档说了什么\"` |\n| 搜文件 | `\"搜一下上个月的合同\"` |\n| 上传本地文件 | `\"把这个 PDF 上传到云端\"` |\n| 识别图片文字 | `\"把这张发票的文字提取出来\"` |\n| 恢复误删 | `\"回收站里有没有昨天删的 Word？\"` |\n| 回滚版本 | `\"这份文档改坏了，回退到上周版本\"` |\n| 分享权限 | `\"给张三发个可编辑的链接\"` |\n| 归档文件夹 | `\"把文件移到 2026 项目文件夹\"` |\n| 格式转换 | `\"把这份文档转成 PDF\"` |\n\n---\n\n## 5. 自然语言触发示例（高级功能怎么表达）\n\n为避免「不知道怎么开口」，以下给可直接说的话：\n\n- **批量建表**：`\"新建客户管理多维表格，字段：客户名(文本)、签约金额(数字)、状态(单选)，并一次写入 20 条记录\"`\n- **格式转换**：`\"把《Q2 报告》导出成 PDF\"` / `\"转成 Word 发我\"`\n- **OCR 转文档**：`\"识别这张发票图片，生成一份 Word 报销单\"` / `\"把这张表格图片转成在线电子表格\"`\n- **网页剪藏**：`\"把这个网页 https://... 收藏成金山文档\"` \n- **通知推送**：`\"导入完成后用企微机器人通知我\"` \n- **版本回滚**：`\"列出这份文档的历史版本，回退到 7 月 1 日那版\"` \n- **权限管理**：`\"给团队文件夹『2026 项目』里的文档设置只读\"` \n- **本地免密钥生成**：`\"本地生成一份周报 DOCX，不用上传\"`（无需 App Key）\n\n---\n\n## 安全声明\n\n| 保护项 | 方式 |\n|--------|------|\n| 🔒 删除确认 | 删除走回收站 API，不物理删除 |\n| 🗑️ 软删除+恢复 | `trash.list → trash.recover` |\n| 📝 版本冲突检测 | 写入前获取最新版本号，冲突时提示用户合并 |\n| 🔐 权限前置校验 | 所有写入操作前自动检查权限，无权限拒绝 |\n| ⚡ 限流保护 | 429 自动指数退避重试（最多 5 次） |\n| 🛡️ 文件类型拦截 | 默认禁止上传 .exe/.bat/.ps1/.zip 等（见第 18 节） |\n| 🔑 Token 安全 | Token 仅存在于内存，不落盘 |\n| 📋 审计日志 | 所有写操作记录到本地日志 |\n| 🔀 批量合并 | 50ms 窗口内连续写入自动合并为一次请求 |\n| 🧠 硬件自适应 | 自动按本机 CPU/内存分配并发，不拖累电脑（第 17 节） |\n\n---\n\n##"},{"path":"README.md","content":"# KingDoc — 金山文档 AI 协作助手\n\n> 让 AI 直接操作你的金山在线文档，创建、编辑、管理一站搞定。\n> **v4.2**：知识中枢与政企合规 · 团队知识库模式（空间级倒排检索 + 权限矩阵先鉴权后检索，可选 jieba 中文分词）· 政企合规中心（密级标注公开/内部/秘密/机密落库 + 敏感词/数据泄露全量扫描报告 + 数据不出域声明）· 主题一键生成（WPS AI 适配层 generate：大纲→智能文档/PPT/表格初稿，本地降级可切真源）· 跨品类对比与时间线（版本历史轮询→who/when/what 时间线 + 表格单元格级 diff）· OCR 收敛（唯一入口，优先桥接 wps-office-suite，未装则 Tesseract 最小兜底，数据不出域）· 多维表格深化与在线自动化 · AirScript 脚本引擎（自然语言→脚本→预检→确认→在线执行）· 多维表格字段自动化（公式/关联/汇总字段批量填充）· 视图渲染（matplotlib 看板柱图 + mermaid 甘特时间线）· CRDT 表格扩展（单元格级操作日志 + 向量时钟冲突标记）· Excel/CSV 双向导入导出（date/link/select/person 四类字段序列化）· Webhook 通知中心（新增/修改/删除事件订阅 + 金山协作/企微/钉钉三通道）· 生态互通（wps-office-suite 双向桥接 + zwjh 记忆库打通）· 表单答卷收集统计 · 块级编辑 · 演示页替换 · 配额管理器 · 格式转换全格式覆盖 · 智能画布元素级编辑 · 全文搜索 · 多维表格视图增强 · 手写/公式识别 OCR · 历史管理 · 文档模板市场 · WPS AI 深度集成 · 实时协同编辑 · 文档对比 · 文档合规检查 · 协同冲突解决 · 硬件自适应性能 · 免密钥本地能力。\n\n## ✨ 特性\n\n- 📝 **9 品类全覆盖** — 文档/智能画布/表格/演示/多维表格/收集表/可视化/历史管理/全文搜索/附件\n- 🎨 **智能画布元素级编辑** — 对标腾讯文档·智能画布，元素 CRUD + Markdown 增量追加\n- 🔍 **全文搜索** — 超越腾讯：搜文档内容+结果定位高亮\n- 📊 **多维表格视图增强** — 看板/日历/甘特图，对标 Airtable，本地渲染\n- 🗂️ **空间节点管理** — 目录树/链接节点/递归删除/目录可视化\n- ✍️ **手写/公式识别** — 教育场景，LaTeX/MathML 输出，强制本地 Tesseract\n- 🕐 **历史管理** — 回收站+版本历史统一入口（list/restore/destroy/delete --force）\n- 🔗 **全生命周期** — 创建/编辑/删除/移动/复制/权限/版本历史/回收站\n- 🆚 **对标腾讯文档** — 腾讯有的全有，腾讯没有的也有（回收站/版本/转换/OCR/通知）\n- 🤖 **WPS AI 深度集成** — 写作辅助/数据分析/PPT 生成/阅读助手/段落改写/段落总结/段落续写，本地降级优先、零密钥可用\n- 🔄 **实时协同编辑** — 序列 CRDT 算法，多人同时编辑无冲突\n- 📊 **文档对比** — 差异高亮/变更摘要/导出报告，复用 difflib 引擎\n- 🔄 **协同冲突解决** — 冲突检测/智能合并/Git diff 可视化/解决模板，自研 difflib 实现\n- 📋 **文档合规检查** — 敏感词扫描/数据泄露检测/格式规范检查/密级标注，自研规则引擎\n- 🏢 **团队知识库模式** — 空间级全文检索 + 权限矩阵先鉴权后检索，无权限文档不进结果\n- 🔐 **政企合规中心** — 密级标注落库（公开/内部/秘密/机密）+ 全量扫描报告 + 数据不出域声明\n- 💡 **主题一键生成** — WPS AI 适配层 generate：大纲→智能文档/PPT/表格初稿，本地降级可切真源\n- 🔭 **跨品类对比与时间线** — 版本历史轮询→who/when/what 时间线 + 表格单元格级 diff（腾讯没有的差异化）\n- 🔧 **OCR 收敛** — 唯一入口，优先桥接 wps-office-suite OCR，未装则 Tesseract 最小兜底，数据不出域\n- 🧠 **硬件自适应** — 自动按本机 CPU/内存分配并发，绝不拖累电脑\n- 📁 **文档模板市场** — 行业模板库一键复用，变量替换快速创建文档\n- 🔓 **免密钥本地能力** — 本地生成 DOCX/PPTX/脑图/流程图、本地 OCR、硬件画像、WPS AI，零配置\n- 🛡️ **安全优先** — 软删除/权限前置/限流退避/审计日志/危险操作强制确认/文件类型拦截\n\n## 🚀 快速开始\n\n### 1. 安装\n\n```bash\n# Linux / macOS\nbash D:\\skill\\kingdoc\\setup.sh\n# Windows (PowerShell)\npowershell -ExecutionPolicy Bypass -File D:\\skill\\kingdoc\\setup.ps1\n```\n\n### 2. 配置 App Key（仅云端协作需要）\n\n从 [金山开放平台](https://developer.kdocs.cn) 获取 AppID + AppSecret，安装脚本引导输入。\n**本地生成/OCR/硬件画像/WPS AI 无需 Key。**\n\n### 3. 直接使用\n\n对 WorkBuddy 说：\n- \"帮我写一份会议纪要\" → 本地生成并上传\n- \"把这个 PDF 传到云端\" → 上传（自动拦截禁止类型）\n- \"这份文档改坏了，回退到上周\" → 版本回滚\n- \"识别这张发票的文字\" → 本地 OCR（免密钥）\n- \"帮我润色这段文字\" → WPS AI 写作辅助（免密钥）\n- \"分析这列数据的趋势\" → WPS AI 数据分析（免密钥）\n- \"根据大纲生成 PPT\" → WPS AI PPT 生成（免密钥）\n- \"总结这份文档\" → WPS AI 阅读助手（免密钥）\n- \"把多维表格显示为看板\" → 多维表格视图增强（免密钥）\n- \"识别这个数学公式\" → 公式识别 OCR（免密钥）\n- \"恢复回收站里的文件\" → 历史管理（需 App Key）\n\n## 📖 支持的文档类型（8 品类）\n\n| 类型 | 创建 | 编辑 |\n|------|------|------|\n| 文字/智能文档 | ✅ 自动排版 | ✅ 本地生成+上传覆盖 |\n| 电子表格 | ✅ 自动创建 | ✅ 单元格/公式精细编辑 |\n| 演示文稿 | ✅ 自动排版 | ✅ 本地生成+上传覆盖 |\n| 多维表格 | ✅ 自动创建 | ✅ 记录/字段/视图精细编辑 |\n| 收集表 | ✅ 自动创建 | ✅ 配置+答卷管理 |\n| 可视化（思维导图/流程图） | ✅ 本地渲染 SVG | ✅ 上传覆盖 |\n| 历史管理（回收站+版本） | — |"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n \"slug\": \"kingdoc\",\n \"version\": \"4.2.0\",\n \"publishedAt\": 1789785144592\n}"},{"path":"references/auth.md","content":"# 金山开放平台 API 参考\n\n> 本文档定义 KingDoc 与金山开放平台 API 的对接方式，包括鉴权、请求格式、错误处理和核心接口。\n\n---\n\n## 1. 鉴权概述\n\n### 1.1 获取 AppID / AppSecret\n\n1. 访问 [金山开放平台](https://developer.kdocs.cn)\n2. 创建一个新应用\n3. 获取 `App ID` 和 `App Secret`\n4. 在本地配置：`config.json`\n\n### 1.2 OAuth 2.0 Client Credentials\n\n```\nPOST https://open.kdocs.cn/oauth/token\n\nBody:\n grant_type = client_credentials\n client_id = \n client_secret = \n scope = user:file:write user:file:read team:file:write team:file:read\n```\n\n**响应**：\n\n```json\n{\n \"access_token\": \"eyJhbGciOiJIUzI1NiIs...\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 7200,\n \"scope\": \"user:file:write user:file:read\"\n}\n```\n\n### 1.3 使用 Token\n\n在请求 Header 中传递：\n\n```\nAuthorization: Bearer \n```\n\n---\n\n## 2. 基础 URL\n\n| 环境 | 基础 URL |\n|------|---------|\n| 生产环境 | `https://developer.kdocs.cn/api/v1/openapi` |\n| 沙箱环境 | `https://sandbox.kdocs.cn/api/v1/openapi` |\n\n---\n\n## 3. 统一响应格式\n\n所有 API 返回：\n\n```json\n{\n \"code\": 0,\n \"message\": \"OK\",\n \"data\": { ... },\n \"trace_id\": \"trace_abc123\"\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| code | int | 0 = 成功，非 0 = 错误 |\n| message | string | 状态信息 |\n| data | object | 业务数据（仅成功时存在） |\n| trace_id | string | 追踪 ID，排查问题用 |\n\n---\n\n## 4. 个人文档 API\n\n### 4.1 创建文档\n\n```\nPOST /personal/files\n\nBody:\n{\n \"name\": \"文档标题\",\n \"type\": \"doc\",\n \"folder_id\": \"可选，父文件夹 ID\",\n \"content\": \"可选，初始内容\"\n}\n```\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| name | string | ✅ | 文档标题 |\n| type | string | ✅ | 文档类型：doc / sheet / ppt / dbt / form |\n| folder_id | string | ❌ | 父文件夹 ID（不填为根目录） |\n| content | string | ❌ | 初始内容（Markdown） |\n\n**成功响应**：\n\n```json\n{\n \"code\": 0,\n \"message\": \"OK\",\n \"data\": {\n \"file_id\": \"file_abc123\",\n \"name\": \"文档标题\",\n \"type\": \"doc\",\n \"url\": \"https://docs.wps.cn/doc/file_abc123\",\n \"created_at\": 1719849600\n }\n}\n```\n\n### 4.2 获取文档内容\n\n```\nGET /personal/files/:file_id/content\n```\n\n**响应**：\n\n```json\n{\n \"code\": 0,\n \"data\": {\n \"file_id\": \"file_abc123\",\n \"content\": \"文档正文...\",\n \"version\": 3\n }\n}\n```\n\n### 4.3 更新文档内容\n\n```\nPUT /personal/files/:file_id/content\n\nBody:\n{\n \"content\": \"更新的内容\",\n \"version\": 3\n}\n```\n\n> ⚠️ `version` 必须与当前版本一致，否则返回版本冲突错误。\n\n### 4.4 删除文档（软删除）\n\n```\nDELETE /personal/files/:file_id\n```\n\n> ⚠️ 删除后文档进入回收站，可恢复。\n\n### 4.5 彻底删除\n\n```\nDELETE /personal/files/:file_id/permanent\n```\n\n---\n\n## 5. 空间/文件夹 API\n\n### 5.1 创建文件夹\n\n```\nPOST /personal/folders\n\nBody:\n{\n \"name\": \"文件夹名称\",\n \"parent_id\": \"可选，父文件夹 ID\"\n}\n```\n\n### 5.2 查询目录树\n\n```\nGET /personal/folders/children?folder_id=:id\n```\n\n### 5.3 查询面包屑路径\n\n```\nGET /personal/folders/breadcrumb?folder_id=:id\n```\n\n---\n\n## 6. 回收站 API\n\n### 6.1 查询回收站\n\n```\nGET /personal/trash/list?offset=0&limit=20\n```\n\n### 6.2 恢复文件\n\n```\nPOST /personal/trash/recover\n\nBody:\n{\n \"file_id\": \"file_abc123\"\n}\n```\n\n### 6.3 彻底删除\n\n```\nPOST /personal/trash/destroy\n\nBody:\n{\n \"file_id\": \"file_abc123\"\n}\n```\n\n---\n\n## 7. 版本历史 API\n\n### 7.1 查询版本\n\n```\nGET /appspace/versions?file_id=:file_id\n```\n\n### 7.2 回滚到某版本\n\n```\nPOST /appspace/versions/:version_id/restore\n\nBody:\n{\n \""},{"path":"references/dbt_references.md","content":"# 多维表格 API 参考\n\n> 轻维表（dbt）完整操作 API，对标腾讯文档智能表格。\n\n---\n\n## 1. 创建多维表格\n\n```\nPOST /dbt/tables\n\nBody:\n{\n \"name\": \"项目管理\",\n \"description\": \"团队项目跟踪\",\n \"folder_id\": \"可选\"\n}\n```\n\n**响应**：\n\n```json\n{\n \"code\": 0,\n \"data\": {\n \"table_id\": \"dbt_abc123\",\n \"name\": \"项目管理\"\n }\n}\n```\n\n---\n\n## 2. 字段管理\n\n### 2.1 添加字段\n\n```\nPOST /dbt/fields\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"name\": \"优先级\",\n \"type\": \"select\",\n \"options\": [\"P0\", \"P1\", \"P2\"],\n \"required\": true\n}\n```\n\n### 2.2 修改字段\n\n```\nPUT /dbt/fields/:field_id\n```\n\n### 2.3 删除字段\n\n```\nDELETE /dbt/fields/:field_id\n```\n\n### 2.4 列出字段\n\n```\nGET /dbt/fields/:table_id\n```\n\n---\n\n## 3. 视图管理\n\n### 3.1 添加视图\n\n```\nPOST /dbt/views\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"name\": \"按优先级分组\",\n \"type\": \"group\",\n \"config\": {\n \"field\": \"优先级\",\n \"order\": [\"P0\", \"P1\", \"P2\"]\n }\n}\n```\n\n---\n\n## 4. 记录操作\n\n### 4.1 新增记录\n\n```\nPOST /dbt/records\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"fields\": {\n \"项目名称\": \"知识库建设\",\n \"负责人\": \"张三\",\n \"优先级\": \"P1\"\n }\n}\n```\n\n### 4.2 批量新增（推荐）\n\n```\nPOST /dbt/records/batch\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"records\": [\n {\"fields\": {...}},\n {\"fields\": {...}},\n ...\n ]\n}\n```\n\n### 4.3 更新记录\n\n```\nPUT /dbt/records/:record_id\n```\n\n### 4.4 删除记录\n\n```\nDELETE /dbt/records/:record_id\n```\n\n### 4.5 查询记录\n\n```\nGET /dbt/records/:table_id?filter={...}&offset=0&limit=100\n```\n\n---\n\n## 5. Webhook\n\n### 5.1 设置 Webhook\n\n```\nPOST /dbt/webhooks\n\nBody:\n{\n \"table_id\": \"dbt_abc123\",\n \"callback_url\": \"https://your-app.com/webhook\",\n \"events\": [\"record.add\", \"record.update\", \"record.delete\"],\n \"secret\": \"可选，用于签名验证\"\n}\n```\n\n### 5.2 列出 Webhook\n\n```\nGET /dbt/webhooks/:table_id\n```\n\n---\n\n## 6. 错误码\n\n| 错误码 | 含义 |\n|--------|------|\n| 字段已存在 | 尝试添加重复名称的字段 |\n| 字段被视图依赖 | 删除字段前需先删除依赖的视图 |\n| 记录不存在 | record_id 不存在 |\n| 表格不存在 | table_id 不存在 |\n| Webhook 回调失败 | 回调 URL 返回非 2xx 状态码 |"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"金山文档 AI 协作助手 — 9 品类在线文档全生命周期管理 （文档/智能画布/电子表格/演示文稿/多维表格/收集表/可视化/历史管理/全文搜索/附件）， 深度直连金山文档（WPS）开放平台原生 API，覆盖腾讯文档全部能力 + 金山独有 18 项增强 （回收站、版本历史、格式转换（全格式覆盖 jpg/png/t... Skill: kingdoc Owner: fyniujin Summary: 金山文档 AI 协作助手 — 9 品类在线文档全生命周期管理 （文档/智能画布/电子表格/演示文稿/多维表格/收集表/可视化/历史管理/全文搜索/附件）， 深度直连金山文档（WPS）开放平台原生 API，覆盖腾讯文档全部能力 + 金山独有 18 项增强 （回收站、版本历史、格式转换（全格式覆盖 jpg/png/t... Tags: latest:4.2.0 Version history: v4.2.0 | 2026-09-19T02:32:24.592Z | auto Kingdoc 4.2.0 introduces major enhancements and internal refactoring. - Added 10 new modules, including airscript, knowledge_hub, webhook_cent","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1181,"uniquenessScore":50,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T05:49:54.203Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T05:49:54.203Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T10:43:54.421Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}