{"id":"3d390d1a-19a1-4b47-8725-21c8611634e0","entityType":"agent","slug":"clawhub-yuchangxu1989-openclaw-kivo","name":"KIVO","canonicalUrl":"https://www.xpersona.co/agent/clawhub-yuchangxu1989-openclaw-kivo","canonicalPath":"/agent/clawhub-yuchangxu1989-openclaw-kivo","generatedAt":"2026-10-11T01:49:47.953Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T22:46:14.361Z","emptyReason":null},"description":"Agent 知识平台 — 覆盖知识提取、存储、检索、迭代、调研闭环的完整生命周期 Skill: KIVO Owner: yuchangxu1989-openclaw Summary: Agent 知识平台 — 覆盖知识提取、存储、检索、迭代、调研闭环的完整生命周期 Tags: latest:1.11.0 Version history: v1.11.0 | 2026-05-04T05:40:51.087Z | auto - Bumped version to 1.11.0 in SKILL.md. v1.10.0 | 2026-05-04T05:25:22.451Z | auto - 更新了描述，强调了知识平台覆盖的全生命周期闭环 - 版本号从 1.9.0 升级至 1.10.0 - 文档大幅精简，仅保留名称和一句简要介绍 v1.9.0 | 2026-05-04T04:02:47.244Z | auto - Major simplification: removed legacy components and","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.2K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17a59yf9b9zefwe0avdmbspmh852jzp:kivo","sourceUrl":"https://clawhub.ai/yuchangxu1989-openclaw/kivo","homepage":"https://clawhub.ai/yuchangxu1989-openclaw/skills/kivo","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/yuchangxu1989-openclaw/kivo","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/yuchangxu1989-openclaw/skills/kivo","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":62,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Agent 知识平台 — 覆盖知识提取、存储、检索、迭代、调研闭环的完整生命周期 Skill: KIVO Owner: yuchangxu1989-openclaw Summary: Agent 知识平台 — 覆盖知识提取、存储、检索、迭代、调研闭环的完整生命周期 Tags: latest:1.11.0 Version"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:46:14.361Z","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-10T22:46:14.361Z","emptyReason":null},"stars":null,"forks":null,"downloads":1239,"packageName":null,"latestVersion":"1.11.0","tractionLabel":"1.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:46:14.346Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T22:46:14.361Z","lastCrawledAt":"2026-10-10T22:46:14.346Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T22:46:14.346Z","lastVerifiedAt":null,"highlights":[{"version":"1.11.0","createdAt":"2026-05-04T05:40:51.087Z","changelog":"- Bumped version to 1.11.0 in SKILL.md.","fileCount":3,"zipByteSize":1563},{"version":"1.10.0","createdAt":"2026-05-04T05:25:22.451Z","changelog":"- 更新了描述，强调了知识平台覆盖的全生命周期闭环 - 版本号从 1.9.0 升级至 1.10.0 - 文档大幅精简，仅保留名称和一句简要介绍","fileCount":2,"zipByteSize":516},{"version":"1.9.0","createdAt":"2026-05-04T04:02:47.244Z","changelog":"- Major simplification: removed legacy components and modules for ingest, inject, query, and resolve. - SKILL.md updated to focus on core Chinese-language description, streamlined installation, and core feature list. - Now emphasizes multi-source extraction, vector/FTS5 retrieval, automated knowledge governance, and intent injection. - Only the main documentation file remains; supporting scripts and config files have been removed.","fileCount":2,"zipByteSize":836},{"version":"1.8.0","createdAt":"2026-05-04T01:29:52.971Z","changelog":"Sync with npm 1.8.0: full knowledge platform with extraction, storage, search, conflict resolution, distribution, workbench, and graph capabilities","fileCount":12,"zipByteSize":9109},{"version":"1.2.3","createdAt":"2026-05-02T12:00:32.522Z","changelog":"1.2.1 完整发布: 61FR全覆盖 + 全UX差异化标准 + 审计扣分项清零","fileCount":220,"zipByteSize":394432},{"version":"1.2.2","createdAt":"2026-05-02T11:59:03.766Z","changelog":"1.2.1 full release","fileCount":3,"zipByteSize":1692},{"version":"1.2.1","createdAt":"2026-05-02T11:34:48.485Z","changelog":"1.2.1: 全量P2/P3修复清零 + 时间轴回放 + 认知负荷管理 + 61FR全覆盖","fileCount":220,"zipByteSize":394435},{"version":"0.5.4","createdAt":"2026-05-01T05:54:00.225Z","changelog":"商用就绪，685测试全绿","fileCount":2,"zipByteSize":596}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17a59yf9b9zefwe0avdmbspmh852jzp:kivo","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-yuchangxu1989-openclaw-kivo/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-kivo/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-kivo/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-kivo/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-kivo/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-kivo/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-11T01:49:47.948Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-kivo/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-kivo/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-kivo/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yuchangxu1989-openclaw-kivo/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-10T22:46:14.361Z","emptyReason":null},"readme":"Skill: KIVO\n\nOwner: yuchangxu1989-openclaw\n\nSummary: Agent 知识平台 — 覆盖知识提取、存储、检索、迭代、调研闭环的完整生命周期\n\nTags: latest:1.11.0\n\nVersion history:\n\nv1.11.0 | 2026-05-04T05:40:51.087Z | auto\n\n- Bumped version to 1.11.0 in SKILL.md.\n\nv1.10.0 | 2026-05-04T05:25:22.451Z | auto\n\n- 更新了描述，强调了知识平台覆盖的全生命周期闭环\n- 版本号从 1.9.0 升级至 1.10.0\n- 文档大幅精简，仅保留名称和一句简要介绍\n\nv1.9.0 | 2026-05-04T04:02:47.244Z | auto\n\n- Major simplification: removed legacy components and modules for ingest, inject, query, and resolve.\n- SKILL.md updated to focus on core Chinese-language description, streamlined installation, and core feature list.\n- Now emphasizes multi-source extraction, vector/FTS5 retrieval, automated knowledge governance, and intent injection.\n- Only the main documentation file remains; supporting scripts and config files have been removed.\n\nv1.8.0 | 2026-05-04T01:29:52.971Z | user\n\nSync with npm 1.8.0: full knowledge platform with extraction, storage, search, conflict resolution, distribution, workbench, and graph capabilities\n\nv1.2.3 | 2026-05-02T12:00:32.522Z | user\n\n1.2.1 完整发布: 61FR全覆盖 + 全UX差异化标准 + 审计扣分项清零\n\nv1.2.2 | 2026-05-02T11:59:03.766Z | user\n\n1.2.1 full release\n\nv1.2.1 | 2026-05-02T11:34:48.485Z | user\n\n1.2.1: 全量P2/P3修复清零 + 时间轴回放 + 认知负荷管理 + 61FR全覆盖\n\nv0.5.4 | 2026-05-01T05:54:00.225Z | user\n\n商用就绪，685测试全绿\n\nv0.4.0 | 2026-04-29T03:08:59.624Z | user\n\n15域后端编码完成，645测试全绿，tsc 0 error\n\nv0.3.1 | 2026-04-26T14:37:37.504Z | user\n\nP3修复: CLI --help退出码0 + uuid升级14.0.0消除漏洞; P0密码哈希安全缺陷修复bcrypt替换\n\nv0.3.0 | 2026-04-26T13:09:56.413Z | user\n\n域Z全部10FR完成，325/325测试通过，文档齐全\n\nv1.0.0 | 2026-04-20T08:52:34.335Z | user\n\nv1.0.0: Full release with six knowledge types, conflict resolution, gap detection, research scheduling, context injection, multi-format parsing, and relationship mapping\n\nv0.1.0 | 2026-04-20T05:53:47.780Z | user\n\nInitial release: 5 domains, 269 tests, MIT license\n\nv0.0.2 | 2026-04-19T10:08:25.043Z | user\n\n更新描述至最新项目定位\n\nv0.0.1 | 2026-04-19T04:34:31.932Z | auto\n\nInitial release of kivo — cognitive infrastructure for AI agent harnesses.\n\n- Provides domain intent understanding and intent routing\n- Enables autonomous knowledge extraction, validation, and accumulation\n- Supports versioned management and rollback of rules, knowledge, and configurations\n- Facilitates cross-module intent orchestration and execution coordination\n- Core module of the Self-Evolving Harness system\n\nArchive index:\n\nArchive v1.11.0: 3 files, 1563 bytes\n\nFiles: skill-card.md (1881b), SKILL.md (184b), _meta.json (124b)\n\nFile v1.11.0:SKILL.md\n\n---\nname: kivo\ndescription: \"Agent 知识平台 — 覆盖知识提取、存储、检索、迭代、调研闭环的完整生命周期\"\nversion: 1.11.0\n---\n# KIVO\nAgent 知识平台。\n\nFile v1.11.0:_meta.json\n\n{\n \"ownerId\": \"kn71kk78dbbgtentzcetv7d1zn8536vd\",\n \"slug\": \"kivo\",\n \"version\": \"1.11.0\",\n \"publishedAt\": 1777873251087\n}\n\nFile v1.11.0:skill-card.md\n\n## Description:\n\nKIVO is an agent knowledge platform covering knowledge extraction, storage, retrieval, iteration, and research-loop workflows.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[yuchangxu1989-openclaw](https://clawhub.ai/user/yuchangxu1989-openclaw)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use KIVO as guidance for knowledge-platform workflows across extraction, storage, retrieval, iteration, and research-loop activities.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill description is Chinese-language, which may be misunderstood by readers who cannot review Chinese text directly.\n\nMitigation: Have a Chinese-proficient reviewer confirm the intended use and wording before relying on the skill in production workflows.\n\nRisk: The artifact is minimal descriptive guidance rather than an executable integration.\n\nMitigation: Review the artifact contents and add implementation-specific documentation before treating it as an operational knowledge-platform workflow.\n\n## Reference(s):\n\n- [ClawHub KIVO skill page](https://clawhub.ai/yuchangxu1989-openclaw/skills/kivo)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, guidance]\n\n**Output Format:** [Markdown or plain text guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [The inspected artifact contains descriptive skill text only and no commands, scripts, credential handling, network calls, or persistence mechanisms.]\n\n## Skill Version(s):\n\n1.11.0 (source: SKILL.md frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.10.0: 2 files, 516 bytes\n\nFiles: SKILL.md (184b), _meta.json (124b)\n\nFile v1.10.0:SKILL.md\n\n---\nname: kivo\ndescription: \"Agent 知识平台 — 覆盖知识提取、存储、检索、迭代、调研闭环的完整生命周期\"\nversion: 1.10.0\n---\n# KIVO\nAgent 知识平台。\n\nFile v1.10.0:_meta.json\n\n{\n \"ownerId\": \"kn71kk78dbbgtentzcetv7d1zn8536vd\",\n \"slug\": \"kivo\",\n \"version\": \"1.10.0\",\n \"publishedAt\": 1777872322451\n}\n\nArchive v1.9.0: 2 files, 836 bytes\n\nFiles: SKILL.md (689b), _meta.json (123b)\n\nFile v1.9.0:SKILL.md\n\n---\nname: kivo\ndescription: \"Agent 知识平台 — 多源知识提取、语义检索、知识治理、意图注入，让 Agent 越用越聪明\"\nversion: 1.9.0\n---\n\n# KIVO\n\nAgent 知识平台。覆盖知识完整生命周期：多源提取、结构化存储、语义检索、知识迭代、自主调研、意图注入。\n\n## 安装\n```\nnpm install @self-evolving-harness/kivo\nnpx kivo init\n```\n\n## 核心能力\n- 多源知识提取（对话、文档、代码、会话日志）\n- BGE 向量检索 + FTS5 全文检索\n- 知识治理自动化（MECE 验证、badcase 转化、质量审计）\n- 意图注入 hook（kivo init 自动安装，每条消息检索知识库注入 agent 上下文）\n\nFile v1.9.0:_meta.json\n\n{\n \"ownerId\": \"kn71kk78dbbgtentzcetv7d1zn8536vd\",\n \"slug\": \"kivo\",\n \"version\": \"1.9.0\",\n \"publishedAt\": 1777867367244\n}\n\nArchive v1.8.0: 12 files, 9109 bytes\n\nFiles: SKILL.md (1259b), skill/ingest/scripts/ingest.ts (2008b), skill/ingest/SKILL.md (896b), skill/inject/scripts/inject.ts (2156b), skill/inject/SKILL.md (761b), skill/package.json (433b), skill/query/scripts/query.ts (2076b), skill/query/SKILL.md (817b), skill/resolve/scripts/resolve.ts (3133b), skill/resolve/SKILL.md (972b), skill/tsconfig.json (195b), _meta.json (123b)\n\nFile v1.8.0:SKILL.md\n\n---\nname: kivo\ndescription: \"KIVO — Agent Knowledge Iteration Engine. A knowledge management system for AI agents that provides knowledge extraction, storage, search, conflict resolution, and iterative learning capabilities. Use when building agent systems that need persistent, evolving knowledge bases.\"\nlicense: MIT\n---\n\n# KIVO — Agent Knowledge Iteration Engine\n\nAgent 知识平台。覆盖知识提取、存储、检索、迭代、调研、图谱、工作台全生命周期。\n\n## Features\n\n- Knowledge extraction and storage (SQLite-backed)\n- Semantic and keyword search\n- Conflict detection and resolution\n- Knowledge distribution and subscription\n- Multi-agent authentication and permissions\n- Bootstrap initialization and health checks\n- Document gate for doc-code consistency\n\n## Quick Start\n\n```bash\nnpm install @self-evolving-harness/kivo\n```\n\n```typescript\nimport { KnowledgeStore, ExtractionPipeline } from '@self-evolving-harness/kivo';\n\nconst store = new KnowledgeStore({ dbPath: './knowledge.db' });\nconst pipeline = new ExtractionPipeline({ store });\nawait pipeline.extract(document);\n```\n\n## CLI\n\n```bash\nnpx kivo init # Initialize knowledge base\nnpx kivo health # Health check\nnpx kivo capabilities # Show capabilities\n```\n\nFile v1.8.0:skill/ingest/SKILL.md\n\n---\nname: knowledge-ingest\ndescription: \"从对话或文档中提取并存储结构化知识。支持文件和文本输入，自动执行知识提取、冲突检测和入库。\"\n---\n\n# KnowledgeIngestSkill — 知识摄入\n\n从对话、文档、代码中自动提取结构化知识，经冲突检测后存入知识库。\n\n## 触发词\n\n学习这个、记住、摄入知识、记住这个、把这段话存下来、从这篇文档提取知识、学习这个文件、保存到知识库、ingest、learn this、save knowledge、remember this、extract knowledge\n\n## 使用方式\n\n```bash\n# 从文件摄入\ntsx scripts/ingest.ts --file ./docs/design.md --source \"design-doc\"\n\n# 从文本摄入\ntsx scripts/ingest.ts --text \"用户偏好短答，先结论后证据\" --source \"conversation\"\n```\n\n## 核心路径\n\n`src/extraction/` → `src/pipeline/engine.ts` → `src/conflict/` → `src/repository/`\n\nFile v1.8.0:skill/inject/SKILL.md\n\n---\nname: context-inject\ndescription: \"系统级 Skill：系统自动触发，非用户直接调用。为当前任务自动注入相关知识上下文。根据请求语义检索知识库，按注入策略格式化后注入 Agent 上下文窗口。\"\ntrigger-mode: system\n---\n\n# ContextInjectSkill — 上下文注入\n\n为 Agent 当前任务自动注入相关知识上下文，提升回答质量。\n\n## 触发词\n\nsystem:context-inject\n\n## 使用方式\n\n```bash\n# 为查询注入相关上下文\ntsx scripts/inject.ts --query \"当前用户请求\" [--budget ]\n\n# 指定注入格式\ntsx scripts/inject.ts --query \"设计决策\" --format markdown --budget 3000\n```\n\n## 核心路径\n\n`src/injection/context-injector.ts` → `src/injection/injection-policy.ts`\n\nFile v1.8.0:skill/query/SKILL.md\n\n---\nname: knowledge-query\ndescription: \"检索知识库并返回相关知识条目。支持语义搜索，按相关性排序，可指定 token 预算控制返回量。\"\n---\n\n# KnowledgeQuerySkill — 知识查询\n\n基于语义搜索检索知识库，返回与查询最相关的知识条目。\n\n## 触发词\n\n查知识、搜索记忆、搜索知识库、你知道关于、查一下之前的决策、有没有相关经验、你还记得、recall、query knowledge、search knowledge、what do you know about\n\n## 使用方式\n\n```bash\n# 查询相关知识（默认 budget 2000 tokens）\ntsx scripts/query.ts --query \"用户的交付偏好\"\n\n# 指定 token 预算\ntsx scripts/query.ts --query \"架构决策\" --budget 4000\n```\n\n## 核心路径\n\n`src/search/semantic-search.ts` → `src/repository/knowledge-repository.ts`\n\nFile v1.8.0:skill/resolve/SKILL.md\n\n---\nname: conflict-resolve\ndescription: \"处理知识冲突的人工裁决请求。展示冲突详情，支持用户选择保留策略（新覆旧、保留旧、合并、标记待定）。\"\n---\n\n# ConflictResolveSkill — 冲突裁决\n\n处理知识库中的冲突条目，支持人工裁决和自动解决策略。\n\n## 触发词\n\n知识冲突、矛盾了、哪个是对的、这两条知识矛盾了、用新的、保留旧的、帮我决定哪个对、resolve conflict、conflict、which one is correct\n\n## 使用方式\n\n```bash\n# 列出待裁决冲突\ntsx scripts/resolve.ts --list\n\n# 裁决指定冲突（保留新条目）\ntsx scripts/resolve.ts --id --verdict keep-incoming\n\n# 裁决指定冲突（保留旧条目）\ntsx scripts/resolve.ts --id --verdict keep-existing\n\n# 合并两条\ntsx scripts/resolve.ts --id --verdict merge\n```\n\n## 核心路径\n\n`src/conflict/conflict-resolver.ts` → `src/conflict/conflict-record.ts`\n\nFile v1.8.0:_meta.json\n\n{\n \"ownerId\": \"kn71kk78dbbgtentzcetv7d1zn8536vd\",\n \"slug\": \"kivo\",\n \"version\": \"1.8.0\",\n \"publishedAt\": 1777858192971\n}\n\nFile v1.8.0:skill/package.json\n\n{\n \"name\": \"@kivo/skills\",\n \"version\": \"0.1.0\",\n \"description\": \"KIVO AgentSkills — Wave 1: ingest, query, inject, resolve\",\n \"type\": \"module\",\n \"scripts\": {\n \"ingest\": \"tsx ingest/scripts/ingest.ts\",\n \"query\": \"tsx query/scripts/query.ts\",\n \"inject\": \"tsx inject/scripts/inject.ts\",\n \"resolve\": \"tsx resolve/scripts/resolve.ts\"\n },\n \"dependencies\": {\n \"@kivo/core\": \"workspace:*\",\n \"tsx\": \"^4.19.0\"\n }\n}\n\nFile v1.8.0:skill/tsconfig.json\n\n{\n \"extends\": \"../tsconfig.json\",\n \"compilerOptions\": {\n \"rootDir\": \"..\",\n \"outDir\": \"../dist\",\n \"noEmit\": true\n },\n \"include\": [\n \"../src/**/*\",\n \"./**/scripts/**/*.ts\"\n ]\n}\n\nArchive v1.2.3: 220 files, 394432 bytes\n\nFiles: docs/architecture/arc42-architecture-v2.md (73278b), docs/architecture/arc42-architecture.md (111505b), docs/architecture/decisions/ADR-001-pipeline-filter-architecture.md (1473b), docs/architecture/decisions/ADR-002-repository-spi-storage.md (1455b), docs/architecture/decisions/ADR-003-conflict-detection-pre-write.md (1887b), docs/architecture/decisions/ADR-004-pull-first-rule-distribution.md (1275b), docs/architecture/decisions/ADR-005-research-definition-execution-separation.md (1516b), docs/architecture/decisions/ADR-006-fixed-six-knowledge-types.md (1504b), docs/architecture/decisions/ADR-007-wave1-embedded-deployment.md (1327b), docs/architecture/decisions/ADR-008-web-api-style-rest.md (1632b), docs/architecture/decisions/ADR-009-frontend-framework-selection.md (2677b), docs/architecture/decisions/ADR-010-dictionary-as-knowledge-entry-specialization.md (3877b), docs/configuration-reference.md (8775b), docs/design/user-facing-requirements.md (10548b), docs/product-requirements.md (53378b), docs/quick-start.md (6864b), docs/spec-batch2-append.md (5367b), docs/test-cases.md (16773b), docs/troubleshooting.md (10238b), docs/upgrade-guide.md (4207b), kivo.config.json (102b), package.json (1011b), README.md (11181b), scripts/doc-consistency-check.sh (8960b), SKILL.md (1259b), skill/ingest/scripts/ingest.ts (2008b), skill/ingest/SKILL.md (896b), skill/inject/scripts/inject.ts (2156b), skill/inject/SKILL.md (761b), skill/package.json (433b), skill/query/scripts/query.ts (2076b), skill/query/SKILL.md (817b), skill/resolve/scripts/resolve.ts (3133b), skill/resolve/SKILL.md (972b), skill/tsconfig.json (195b), src/access-control/access-control-types.ts (713b), src/access-control/domain-access-checker.ts (2733b), src/access-control/index.ts (220b), src/adapter/capability-registry.ts (5433b), src/adapter/host-adapter.ts (1667b), src/adapter/index.ts (938b), src/adapter/llm-provider-manager.ts (5728b), src/adapter/llm-provider.ts (345b), src/adapter/openclaw-adapter.ts (3607b), src/adapter/standalone-adapter.ts (3362b), src/association/association-discovery.ts (8225b), src/association/association-retrieval.ts (3798b), src/association/association-store.ts (5641b), src/association/association-types.ts (398b), src/association/graph-insights.ts (13994b), src/association/index.ts (1104b), src/association/knowledge-graph.ts (12468b), src/auth/audit-logger.ts (1413b), src/auth/auth-types.ts (1550b), src/auth/index.ts (566b), src/auth/permission-checker.ts (900b), src/auth/session-manager.ts (2053b), src/auth/user-store.ts (3019b), src/bootstrap/bootstrap-runner.ts (9789b), src/bootstrap/index.ts (203b), src/bootstrap/init-detector.ts (2233b), src/bulk-export/bulk-export-types.ts (826b), src/bulk-export/bulk-exporter.ts (3101b), src/bulk-export/index.ts (217b), src/bulk-import/bulk-import-types.ts (855b), src/bulk-import/bulk-importer.ts (3973b), src/bulk-import/index.ts (264b), src/cli/capabilities.ts (2119b), src/cli/health-check.ts (6047b), src/cli/index.ts (3592b), src/cli/init.ts (6575b), src/cli/install-validator.ts (4467b), src/cli/minimal-mode.ts (2917b), src/cli/query.ts (3633b), src/config.ts (786b), src/config/config-validator.ts (2355b), src/config/env-loader.ts (2667b), src/config/index.ts (306b), src/config/secret-manager.ts (3529b), src/config/types.ts (860b)\n\nFile v1.2.3:SKILL.md\n\n---\nname: kivo\ndescription: \"KIVO — Agent Knowledge Iteration Engine. A knowledge management system for AI agents that provides knowledge extraction, storage, search, conflict resolution, and iterative learning capabilities. Use when building agent systems that need persistent, evolving knowledge bases.\"\nlicense: MIT\n---\n\n# KIVO — Agent Knowledge Iteration Engine\n\nAgent 知识平台。覆盖知识提取、存储、检索、迭代、调研、图谱、工作台全生命周期。\n\n## Features\n\n- Knowledge extraction and storage (SQLite-backed)\n- Semantic and keyword search\n- Conflict detection and resolution\n- Knowledge distribution and subscription\n- Multi-agent authentication and permissions\n- Bootstrap initialization and health checks\n- Document gate for doc-code consistency\n\n## Quick Start\n\n```bash\nnpm install @self-evolving-harness/kivo\n```\n\n```typescript\nimport { KnowledgeStore, ExtractionPipeline } from '@self-evolving-harness/kivo';\n\nconst store = new KnowledgeStore({ dbPath: './knowledge.db' });\nconst pipeline = new ExtractionPipeline({ store });\nawait pipeline.extract(document);\n```\n\n## CLI\n\n```bash\nnpx kivo init # Initialize knowledge base\nnpx kivo health # Health check\nnpx kivo capabilities # Show capabilities\n```\n\nFile v1.2.3:skill/ingest/SKILL.md\n\n---\nname: knowledge-ingest\ndescription: \"从对话或文档中提取并存储结构化知识。支持文件和文本输入，自动执行知识提取、冲突检测和入库。\"\n---\n\n# KnowledgeIngestSkill — 知识摄入\n\n从对话、文档、代码中自动提取结构化知识，经冲突检测后存入知识库。\n\n## 触发词\n\n学习这个、记住、摄入知识、记住这个、把这段话存下来、从这篇文档提取知识、学习这个文件、保存到知识库、ingest、learn this、save knowledge、remember this、extract knowledge\n\n## 使用方式\n\n```bash\n# 从文件摄入\ntsx scripts/ingest.ts --file ./docs/design.md --source \"design-doc\"\n\n# 从文本摄入\ntsx scripts/ingest.ts --text \"用户偏好短答，先结论后证据\" --source \"conversation\"\n```\n\n## 核心路径\n\n`src/extraction/` → `src/pipeline/engine.ts` → `src/conflict/` → `src/repository/`\n\nFile v1.2.3:skill/inject/SKILL.md\n\n---\nname: context-inject\ndescription: \"系统级 Skill：系统自动触发，非用户直接调用。为当前任务自动注入相关知识上下文。根据请求语义检索知识库，按注入策略格式化后注入 Agent 上下文窗口。\"\ntrigger-mode: system\n---\n\n# ContextInjectSkill — 上下文注入\n\n为 Agent 当前任务自动注入相关知识上下文，提升回答质量。\n\n## 触发词\n\nsystem:context-inject\n\n## 使用方式\n\n```bash\n# 为查询注入相关上下文\ntsx scripts/inject.ts --query \"当前用户请求\" [--budget ]\n\n# 指定注入格式\ntsx scripts/inject.ts --query \"设计决策\" --format markdown --budget 3000\n```\n\n## 核心路径\n\n`src/injection/context-injector.ts` → `src/injection/injection-policy.ts`\n\nFile v1.2.3:skill/query/SKILL.md\n\n---\nname: knowledge-query\ndescription: \"检索知识库并返回相关知识条目。支持语义搜索，按相关性排序，可指定 token 预算控制返回量。\"\n---\n\n# KnowledgeQuerySkill — 知识查询\n\n基于语义搜索检索知识库，返回与查询最相关的知识条目。\n\n## 触发词\n\n查知识、搜索记忆、搜索知识库、你知道关于、查一下之前的决策、有没有相关经验、你还记得、recall、query knowledge、search knowledge、what do you know about\n\n## 使用方式\n\n```bash\n# 查询相关知识（默认 budget 2000 tokens）\ntsx scripts/query.ts --query \"用户的交付偏好\"\n\n# 指定 token 预算\ntsx scripts/query.ts --query \"架构决策\" --budget 4000\n```\n\n## 核心路径\n\n`src/search/semantic-search.ts` → `src/repository/knowledge-repository.ts`\n\nFile v1.2.3:skill/resolve/SKILL.md\n\n---\nname: conflict-resolve\ndescription: \"处理知识冲突的人工裁决请求。展示冲突详情，支持用户选择保留策略（新覆旧、保留旧、合并、标记待定）。\"\n---\n\n# ConflictResolveSkill — 冲突裁决\n\n处理知识库中的冲突条目，支持人工裁决和自动解决策略。\n\n## 触发词\n\n知识冲突、矛盾了、哪个是对的、这两条知识矛盾了、用新的、保留旧的、帮我决定哪个对、resolve conflict、conflict、which one is correct\n\n## 使用方式\n\n```bash\n# 列出待裁决冲突\ntsx scripts/resolve.ts --list\n\n# 裁决指定冲突（保留新条目）\ntsx scripts/resolve.ts --id --verdict keep-incoming\n\n# 裁决指定冲突（保留旧条目）\ntsx scripts/resolve.ts --id --verdict keep-existing\n\n# 合并两条\ntsx scripts/resolve.ts --id --verdict merge\n```\n\n## 核心路径\n\n`src/conflict/conflict-resolver.ts` → `src/conflict/conflict-record.ts`\n\nFile v1.2.3:README.md\n\n# KIVO\n\n**让 AI Agent 拥有不会遗忘、持续进化的知识系统。**\n\n---\n\n## 你的 Agent 是不是也这样？\n\n每次新对话，Agent 都像失忆了一样。上周讨论过的决策、踩过的坑、定好的规则——全忘了。你反复投喂同样的信息，Agent 反复犯同样的错。知识散落在聊天记录、配置文件和临时笔记里，没人整理，没人维护，更没人主动去补盲区。\n\nKIVO 改变这一切。\n\n## KIVO 做了什么\n\nKIVO 覆盖知识的完整生命周期，横跨 15 个功能域。更重要的是，KIVO 的用户交互体验远超市面上现有的知识库和 AI 笔记应用（Obsidian、Notion、Mem、Reflect 等）——前端交互体验是 KIVO 作为平台的核心竞争力，不是附属品。\n\n- **交互式知识图谱**：力导向布局、节点按类型着色、缩放平移拖拽、聚焦高亮关联、洞察标记一目了然——不是静态的关系图，是可以探索和发现的知识地图。支持局部图谱（选中节点后按深度展开邻居）、图谱内搜索高亮、关系类型/节点类型过滤\n- **多视图知识浏览**：列表、表格、看板三种视图一键切换，表格视图支持类型和状态的内联编辑（点击即改，自动保存），看板按知识类型分组纵览\n- **版本 diff 对比**：知识条目的历史版本支持词级差异对比，精确到每个修改点\n- **冲突裁决工作台**：冲突双方并排对比、一键保留/合并/废弃、裁决理由留痕——知识冲突不再是被忽略的系统日志，而是用户可以直接操作的决策界面。支持差异对比和升级裁决\n- **语义搜索与后续动作**：向量检索 + 关键词检索，搜索结果支持后续动作（查看详情、跳转图谱、触发调研），高级过滤按类型/时间/域/来源精确筛选\n- **调研管理驾驶舱**：缺口报告、调研队列、任务详情、进度追踪、一键重新调研——从发现盲区到填补知识的完整闭环，全程可视可控\n- **仪表盘总览**：最近编辑的知识、解决的冲突、进行中的调研一目了然，知识健康度和过期预警实时呈现\n- **首次引导与示例数据**：新用户首次进入时自动展示 onboarding 引导，可一键加载示例数据快速体验完整功能\n- **文档导入流水线**：拖拽上传、分段提取进度、逐条确认/拒绝/编辑、原文溯源定位——不是黑盒导入，每一步都透明可控\n- **多源知识提取**：对话、文档、规则文件、URL、手动录入，统一管线自动提取结构化知识\n- **语义检索与关联**：向量检索 + 关键词检索，四种关联类型，按域目标约束排序\n- **知识迭代**：新旧知识冲突自动检测并解决，过时知识自动清理，同主题知识自动合并\n- **自主调研闭环**：发现知识缺口后自动生成调研任务，调研结果回流入库\n- **规则订阅与分发**：系统规则统一注册，按需订阅，变更自动推送\n- **意图理解增强**：Agent 执行任务时自动注入相关知识和术语，辅助意图消歧\n- **系统词典**：术语统一管理，Prompt 自动注入，确保全系统术语语义一致\n\n## 30 秒跑起来\n\n```bash\nnpm install @self-evolving-harness/kivo\nnpx kivo init --yes\nnpx kivo health\n```\n\n直接在命令行验证核心路径（复制粘贴即可运行）：\n\n```bash\nnode --input-type=module -e \"\nimport { Kivo } from '@self-evolving-harness/kivo';\n\nconst kivo = new Kivo({ dbPath: './kivo.db', mode: 'standalone' });\nawait kivo.init();\n\n// 写入一条知识\nconst result = await kivo.ingest('TypeScript 为 JavaScript 添加了静态类型系统。', 'quick-start');\nconsole.log('写入条目数:', result.entries.length);\n\n// 语义检索\nconst results = await kivo.query('TypeScript');\nconsole.log('检索结果:', results.map(r => r.entry.content));\n\nawait kivo.shutdown();\n\"\n```\n\n在项目代码中使用（TypeScript）：\n\n```ts\nimport { Kivo } from '@self-evolving-harness/kivo';\n\nconst kivo = new Kivo({ dbPath: './kivo.db', mode: 'standalone' });\nawait kivo.init();\n\n// 写入一条知识\nawait kivo.ingest('TypeScript 为 JavaScript 添加了静态类型系统。', 'quick-start');\n\n// 语义检索\nconst results = await kivo.query('TypeScript');\nconsole.log(results.map(r => r.entry.title));\n\nawait kivo.shutdown();\n```\n\n验证安装：\n\n```bash\nnpx kivo health\nnpx kivo config-check\n```\n\n## 谁在用、怎么用\n\n### 独立产品操盘者\n\n用 Agent 推进产品研发和运营。需要 Agent 记住历史决策和经验教训，不在同一个坑上反复踩；需要 Agent 能自主调研行业动态，不依赖手动投喂。\n\n### Agent 开发者\n\n构建和维护 Agent 系统。需要统一的知识管理接口，让不同 Agent 共享知识而不互相污染；需要规则分发机制，确保系统规则变更能及时传达到所有相关 Agent。\n\n### 系统管理员\n\n负责 Agent 集群的知识治理。需要知道知识库的健康状态——有多少盲区、多少过时条目、多少冲突待解决。\n\n## 三种使用方式\n\n### standalone：最短路径\n\n适合本地脚本、单机验证、测试环境。上面的「30 秒跑起来」就是这种模式。\n\n环境变量配置（可选）：\n\n```bash\nexport KIVO_DB_PATH=./kivo.db\nexport KIVO_MODE=standalone\nexport KIVO_CONFLICT_THRESHOLD=0.85\n```\n\n### host-embedded：嵌入宿主应用\n\n适合把 KIVO 接进已有 Agent、编排器或聊天系统。\n\n```bash\ngit clone https://github.com/yuchangxu1989-Openclaw/kivo.git\ncd kivo\nnpm install && npm run build\n```\n\n```ts\nimport { Kivo, OpenClawAdapter, EventBus } from '@self-evolving-harness/kivo';\n\nconst kivo = new Kivo({ dbPath: './embedded-kivo.db', mode: 'hosted' });\nawait kivo.init();\n\nconst adapter = new OpenClawAdapter({\n kivo,\n injector: kivo.createContextInjector(),\n eventBus: new EventBus(),\n});\n\n// 对话知识自动提取入库\nawait adapter.onSessionMessage(\n '状态报告应包含结论、行动项、证据和下一步计划。',\n { sessionId: 'sess-001', agentId: 'main' },\n);\n\n// 按 token 预算注入相关知识\nconst context = await adapter.injectContext('状态报告格式', 800);\n\nawait kivo.shutdown();\n```\n\n### full-stack：Core + Web 驾驶舱\n\n适合团队通过浏览器查看知识库、搜索条目、查看活动流和仪表盘指标。\n\n```bash\n# 先构建 Core（同 host-embedded）\ncd kivo\nnpm install && npm run build\n\n# 启动 Web\ncd web\nnpm install\nexport AUTH_PASSWORD='your-password'\nnpm run dev\n```\n\n打开浏览器访问 `http://localhost:3000/kivo/dashboard`。\n\n## 核心能力一览\n\n| 能力 | 说明 |\n|------|------|\n| 对话知识提取 | 从 Agent 对话中自动识别事实、方法论、决策、经验、意图、元认知 |\n| 文档知识提取 | 支持 Markdown、PDF、网页正文，保留原文溯源 |\n| 规则提取与分发 | 从治理文件中提取规则，按订阅关系推送给相关 Agent |\n| 个人知识录入 | 手动录入、文件导入、URL 抓取、对话沉淀、批量文件夹导入 |\n| 语义检索 | 基于语义相似度检索，支持按类型、时间、来源、知识域过滤 |\n| 知识关联 | 补充、替代、冲突、依赖四种关联类型，自动检测潜在关联 |\n| 知识版本管理 | 每条知识条目可追溯历史版本，状态流转清晰 |\n| 冲突检测与解决 | Embedding 粗筛 + LLM 精判，支持时间优先、来源优先、人工裁决 |\n| 知识过期清理 | 基于时间衰减和引用频率自动标记过时知识 |\n| 知识合并 | 不同来源的同主题知识自动识别并合并，按类型区分策略 |\n| 缺口检测 | 基于查询未命中、关联结构缺失和图谱信号识别知识盲区 |\n| 自主调研 | 发现缺口后自动生成调研任务，调研结果入库形成闭环 |\n| 上下文注入 | Agent 处理请求时自动注入相关知识，按 token 预算裁剪 |\n| 意图消歧 | 利用历史知识辅助消解用户意图歧义 |\n| 系统词典 | 术语统一注册、Prompt 注入、冲突检测、生命周期管理 |\n| 知识管线编排 | 提取→分析→分类→冲突→合并→入库，阶段化事件驱动 |\n| 分析中间产物 | 提取过程的结构化分析结果持久化，支持审核和回放 |\n| 知识域目标声明 | 为每个域定义目标和边界，约束提取、检索和调研行为 |\n| 知识图谱构建 | 基于关联关系自动构建，增量更新，API 暴露 |\n| 图谱洞察 | 识别孤立节点、桥接节点、稀疏社区、意外关联 |\n| 图谱可视化 | 力导向布局，节点按类型着色，支持缩放、过滤、聚焦 |\n| 网页抓取 | WebFetchAdapter 用原生 fetch 抓取 URL 提取正文，无需额外依赖 |\n| Web 工作台 | 仪表盘、知识浏览、冲突管理、调研队列、活动流、文档导入、词典、意图库 |\n| 访问控制 | 域级知识隔离，不同 Agent 访问不同知识域 |\n| 批量导入导出 | 知识库和术语的 JSON/YAML/CSV 批量导入导出 |\n| 宿主适配层 | 能力协商、LLM Provider 管理、降级策略 |\n| 开箱即用 | 安装校验、Bootstrap 引导、最小运行模式、升级迁移 |\n\n## 配置参考\n\n| 环境变量 | 说明 | 默认值 |\n|----------|------|--------|\n| `KIVO_DB_PATH` | 数据库路径 | `./kivo.db` |\n| `KIVO_MODE` | 运行模式 | `standalone` |\n| `KIVO_CONFLICT_THRESHOLD` | 冲突检测阈值 | `0.85` |\n| `KIVO_EMBEDDING_PROVIDER` | 向量化提供商 | — |\n| `KIVO_EMBEDDING_API_KEY` | 向量化 API Key | — |\n| `KIVO_EMBEDDING_MODEL` | 向量化模型 | — |\n| `AUTH_PASSWORD` | Web 登录密码 | — |\n\n不配置 embedding 也能运行，语义检索会退化为关键词检索。\n\n## 运行要求\n\n- Node.js >= 20\n- SQLite（通过 `better-sqlite3`，安装时自动编译）\n\n## 常用命令\n\n```bash\nnpx kivo health # 健康检查\nnpx kivo init --yes # 初始化配置\nnpx kivo config-check # 验证配置\nnpx kivo env # 查看环境变量\nnpx kivo capabilities # 查看可用能力\nnpx kivo query # 命令行检索知识\nnpx kivo doc-gate # 文档-代码一致性检查\n```\n\n## 文档\n\n- [快速开始](./docs/quick-start.md)\n- [配置参考](./docs/configuration-reference.md)\n- [故障排查](./docs/troubleshooting.md)\n- [升级指南](./docs/upgrade-guide.md)\n- [产品规格](./docs/product-requirements.md)\n- [架构文档](./docs/architecture/arc42-architecture.md)\n\n## 已知依赖漏洞\n\nWeb 驾驶舱使用 `next@14.2.35`（14.x 最新 patch），存在以下已知漏洞：\n\n| 依赖 | 严重程度 | 说明 |\n|------|----------|------|\n| `next` ≥9.3.4 | **high** | DoS（Image Optimizer）、HTTP 请求走私（rewrites）、磁盘缓存无限增长、Server Components DoS |\n| `postcss` <8.5.10 | moderate | CSS Stringify 输出中的 XSS |\n\n修复需升级到 `next@16`（breaking change），当前暂不升级。生产部署建议：\n- 禁用或限制 `next/image` 远程模式\n- 在反向代理层过滤异常请求\n- 限制磁盘缓存目录大小\n\n## 许可证\n\nMIT License。商业使用和衍生作品须保留原作者署名（yuchangxu1989@gmail.com）。\n\n详见 [LICENSE](./LICENSE)。\n\nFile v1.2.3:_meta.json\n\n{\n \"ownerId\": \"kn71kk78dbbgtentzcetv7d1zn8536vd\",\n \"slug\": \"kivo\",\n \"version\": \"1.2.3\",\n \"publishedAt\": 1777723232522\n}\n\nFile v1.2.3:docs/architecture/arc42-architecture-v2.md\n\n# KIVO — arc42 架构文档\nOpenClaw（dev-01 子Agent）| 2026-04-29\n\n---\n\n## 目录\n1. 引言与目标（Introduction and Goals）\n2. 约束（Architecture Constraints）\n3. 上下文与范围（System Scope and Context）\n4. 解决方案策略（Solution Strategy）\n\n---\n\n## 1. 引言与目标（Introduction and Goals）\n\n### 1.1 问题陈述\nKIVO（Knowledge Iteration & Vibe Orchestration）处理的是 Agent 知识管理问题。\n当前知识散落在对话、记忆文件、规则文件、调研报告、网页摘录和临时笔记中。\n这些内容有价值，但大多还停留在原始记录层，没有进入结构化、可检索、可迭代、可治理的状态。\n由此带来的后果很直接：\n- Agent 记住片段，记不住稳定结论。\n- 新知识入库后，旧知识可能继续生效。\n- 用户纠偏发生过多次，系统仍会重复同类错误。\n- 规则、事实、方法、经验混在一起，调用边界不清。\n- 用户想看知识全貌时，只能翻文件，无法从系统层获得统一视图。\nKIVO 的目标，是把分散知识转成可运营的知识资产，并让 Agent 与用户都能稳定消费这套资产。\n\n### 1.2 系统目标\nKIVO 有两个直接消费面：\n- 面向 Agent：提供知识提取、结构化存储、语义检索、冲突解决、上下文注入、规则分发和缺口驱动调研。\n- 面向用户：提供 Knowledge Workbench，用于导入、查看、审核、探索、调研和治理知识库。\n围绕这两个消费面，系统需要达成以下结果：\n- 知识条目结构统一，能稳定存取和追溯。\n- 知识变更走版本与冲突流程，不发生静默覆盖。\n- 检索支持语义、类型、时间、来源、知识域与目标声明约束。\n- 系统能主动发现知识缺口，并把缺口转成可执行调研任务。\n- 规则分发与知识检索分开建模，治理信息和内容信息分别处理。\n- 核心逻辑与宿主环境解耦，不绑死某个运行时或工具链。\n- 外部陌生用户能在最小依赖下跑通首次知识旅程。\n\n### 1.3 架构驱动因素\n本架构由以下因素主导：\n- 知识生命周期长于单次会话，需要跨对话、跨任务、跨 Agent 持续存在。\n- 知识同时服务机器消费和人工审阅，结构与可读性都要成立。\n- 宿主能力并不恒定，网络访问、Provider、文件权限和工具能力都可能变化。\n- 系统初期要能单机运行，后续还要支持更复杂的嵌入式部署。\n- 研发资源有限，架构要先保证主干闭环，再开放扩展点。\n\n### 1.4 最重要的质量目标\n#### QG-1 一致性（Consistency）\n知识写入必须经过分类、冲突检测和状态管理。\n新旧结论冲突时，系统要么自动裁决，要么显式进入人工裁决流。\n衡量标准：\n- 冲突检测覆盖所有写入路径。\n- 冲突解决率达到 100%。\n- 条目状态流转可审计、可回放。\n\n#### QG-2 检索有效性（Retrieval Effectiveness）\nKIVO 的价值主要体现在取用环节。\n知识已经入库却在检索时拿不到，整套结构化工作就失去意义。\n衡量标准：\n- 检索命中率达到 spec 目标。\n- 返回结果包含来源、类型、相关度和版本语义。\n- 语义检索失败时可降级，不让系统整体失明。\n\n#### QG-3 宿主解耦（Host Decoupling）\nKIVO 需要在 OpenClaw 体系内落地，也要保留迁移到其他宿主的能力。\n衡量标准：\n- 更换宿主适配层时，核心域逻辑不改。\n- 更换底层存储或检索引擎时，上层接口行为稳定。\n- 宿主能力下降时，系统进入可解释的降级状态。\n\n#### QG-4 可治理性（Governability）\n知识系统进入真实使用后，治理成本会持续上升。\n系统必须让用户看见待确认条目、待裁决冲突、未补齐盲区和关键状态变化。\n衡量标准：\n- 关键事件进入活动流。\n- 核心指标能聚合到仪表盘。\n- 审计链路能追到来源、版本、裁决和分发记录。\n\n#### QG-5 开箱即用（Out-of-Box Readiness）\nKIVO 需要支持外部用户安装、启动、录入、检索和持续使用。\n衡量标准：\n- 最小运行模式成立。\n- 首次知识旅程可在 10 分钟内完成。\n- 安装与配置错误有清楚提示和恢复路径。\n\n### 1.5 利益相关者\n#### Solo Founder / 独立产品操盘者\n关注点：Agent 是否能持续记住决策、方法论和经验教训；知识缺口能否被主动发现并补齐；历史积累能否持续复用。\n\n#### Agent 开发者\n关注点：是否有统一知识接口供多个 Agent 共用；知识共享时是否有域边界和规则边界；宿主升级或 Provider 变化时接口是否稳定。\n\n#### 系统管理员 / 运营者\n关注点：访问控制是否可管；冲突、缺口、分发失败、待确认条目是否可观察；导入导出、升级迁移是否可控。\n\n#### 最终用户 / 知识工作者\n关注点：能否通过 Workbench 直接导入和管理知识；搜索、详情、活动流、调研入口是否清楚；空库时是否有引导。\n\n#### OpenClaw 宿主环境\n关注点：KIVO 是否遵守插件边界和运行时约束；与 Gateway、工具调用、文件系统、消息通道的集成成本是否可控；核心能力能否复用到其他项目。\n\n#### 研发相关模块（SEVO / AEO / Claw Design）\n关注点：SEVO 需要历史规格、方法论、规则和经验；AEO 需要在效果漂移时联动 KIVO 排查知识缺失；Claw Design 只消费知识，不承担知识治理职责。\n\n---\n\n## 2. 约束（Architecture Constraints）\n\n### 2.1 技术约束\n#### TC-1 OpenClaw 插件体系约束\nKIVO 当前以 OpenClaw 为主宿主。\n集成边界需要兼容 Gateway、插件、skills、共享工作区和消息调度模型。\n核心知识逻辑可以独立抽象，但运行时要接受宿主的事件方式、文件布局和工具分发方式。\n\n#### TC-2 Node.js 运行时约束\n系统主实现以 Node.js 为边界条件。\n这会影响并发模型、内存使用、I/O 方式、生态选择和部署形态。\n架构需要优先采用适合 Node.js 的异步事件驱动方案，避免依赖重型本地服务才能成立。\n\n#### TC-3 Provider 可变约束\n知识提取、冲突精判、Embedding 生成、结构化输出依赖 LLM Provider。\nProvider 可能有能力差异、配额限制、网络波动和临时不可用场景。\n系统必须支持 Provider 注册、能力声明、降级和切换。\n\n#### TC-4 宿主能力协商约束\nKIVO 不能假设每个宿主都具备完整能力。\n有的宿主没有浏览器，有的宿主没有 Embedding Provider，有的宿主网络能力受限。\n因此需要显式的 Host Adapter 与 capability negotiation 机制。\n\n#### TC-5 最小运行模式约束\nspec 明确要求 standalone 最小组合可运行。\n架构不能建立在必须有向量数据库、图数据库或外部任务系统的前提上。\n默认形态要能落在单机、本地存储、单 Provider 的组合上。\n\n#### TC-6 原始内容治理约束\n系统遵守“知识先结构化再存储”。\n原始文档、网页正文、对话片段可以作为来源引用和处理中输入，但核心库不以原文堆积作为主存储模型。\n\n#### TC-7 事件化写入约束\n知识条目写入、图谱更新、缺口检测、规则分发和活动流刷新存在天然串联关系。\n为了满足异步提取和局部失败隔离，系统需要以事件驱动推进阶段，而不是把所有处理压进单个同步请求。\n\n### 2.2 组织约束\n#### OC-1 单人开发约束\nKIVO 当前处于 solo founder + AI agents 的研发组织里。\n架构要能被少量维护者理解、调试和演进，避免把核心闭环拆成过多高耦合微服务。\n\n#### OC-2 开源发布约束\n系统目标包含对外可安装、可文档化、可升级。\n架构需要为 README、Quick Start、配置参考、故障排查和迁移脚本预留稳定入口。\n\n#### OC-3 多宿主潜力约束\n当前优先服务 OpenClaw，但产品定义要求核心逻辑与宿主环境解耦。\n架构阶段就要保留宿主适配面，避免未来迁移时整体重写。\n\n#### OC-4 审计与交付约束\n关键状态变更需要能被审计、回看和解释。\n架构从一开始就要把活动流、指标聚合、版本历史和裁决记录纳入主路径。\n\n### 2.3 惯例约束\n#### CC-1 六类知识类型固定起步\n系统首批采用 fact、methodology、decision、experience、intent、meta 六种类型。\n后续允许扩展，但当前所有提取、存储、检索和展示逻辑都围绕这六类先闭环。\n\n#### CC-2 规则与知识分离\nRule Entry 与 Knowledge Entry 职责不同。\n规则描述治理语义，知识描述事实、方法、经验和意图。\n这两类对象的生命周期、订阅机制和消费方式不同。\n\n#### CC-3 冲突必须显式处理\n系统接受知识会发生冲突，但不接受冲突悄悄留在库里继续生效。\n任何写入路径都必须进入统一冲突机制。\n\n#### CC-4 溯源与版本是基础元数据\n知识条目、调研结果、裁决结论和系统生成产物都必须有来源引用与版本语义。\n没有来源的条目可以临时保存在待确认状态，不能直接成为高置信长期知识。\n\n#### CC-5 Workbench 是独立消费层\nWorkbench 是用户使用 KIVO 的正式入口之一。\n架构上要与引擎层解耦，功能上要覆盖导入、审核、探索、调研和活动流。\n\n---\n\n## 3. 上下文与范围（System Scope and Context）\n\n### 3.1 业务边界\nKIVO 负责知识提取、分类、冲突治理、持久化、检索、图谱构建、缺口检测、调研任务定义、规则管理和用户工作台。\nKIVO 不负责：\n- 研发流水线推进与任务编排，那是 SEVO 的职责。\n- Agent 效果度量与漂移分析，那是 AEO 的职责。\n- 设计资产生成，那是 Claw Design 的职责。\n- 宿主工具的实现细节，KIVO 只通过适配层消费宿主能力。\n\n### 3.2 业务上下文\n```text\n用户 / 管理员 / Agent 开发者\n │\n │ 浏览 / 检索 / 审核 / 配置 / 调研\n ▼\nKnowledge Workbench\n │\n │ HTTP API / Event Stream\n ▼\nKIVO Core\n ├─ 知识提取与分析\n ├─ 分类与路由\n ├─ 冲突治理与版本\n ├─ 检索与上下文注入\n ├─ 规则注册与分发\n ├─ 图谱与缺口检测\n └─ 调研任务定义\n │\n ├──────── OpenClaw Gateway / Host Adapter\n ├──────── LLM Providers / Embedding Providers\n ├──────── 文件系统 / 本地存储 / 导入源\n ├──────── Web / 文档 / URL 信息源\n └──────── 飞书等外部协作系统\n```\n\n### 3.3 业务交互对象\n#### 用户\n与 KIVO 的交互：上传文档、录入知识、搜索条目、查看图谱和活动流、裁决 pending 条目与冲突条目、管理系统字典和意图库。\nKIVO 交付给用户的价值：可见的知识资产全貌、可操作的审核与调研闭环、清楚的首次知识旅程。\n\n#### Agent\n与 KIVO 的交互：发起语义检索请求、请求上下文注入与术语注入、查询订阅规则、提交对话或调研结果进入知识管线。\nKIVO 交付给 Agent 的价值：稳定的知识消费接口、具备边界的上下文增强、知识缺失后的补盲动作。\n\n#### OpenClaw Gateway / 宿主环境\n与 KIVO 的交互：提供运行时、工具分发、文件工作区、消息通道和外部系统访问能力；通过 Host Adapter 向 KIVO 注册可用能力；接收 KIVO 输出的调研任务定义或高优先级分发事件。\nKIVO 对宿主的要求：能声明能力、承载异步事件、提供基础持久化，并允许功能降级。\n\n#### LLM Provider / Embedding Provider\n与 KIVO 的交互：负责知识提取、结构化分析、冲突精判、意图增强和向量生成；以能力声明形式暴露文本生成、Embedding、结构化输出等能力。\nKIVO 对 Provider 的要求：可注册、可切换、失败可解释、输出可标准化处理。\n\n#### 文件系统与外部信息源\n与 KIVO 的交互：提供文档导入、URL 抓取结果、规则文件、报告文件和导出文件；作为 Source Reference 的承载位置之一。\n处理原则：先分析，再生成条目，再入库；结构化知识入主库，原始内容保留为来源与辅助上下文。\n\n#### 飞书等外部协作系统\n与 KIVO 的交互：承接通知、分享和协作场景，可消费调研完成、冲突待裁决、系统就绪度等外部消息。\n定位：协作出口，不承担知识主存储职责。\n\n### 3.4 技术上下文\n#### 入口接口\n- Knowledge Query API：给 Agent 和 Workbench 提供搜索能力。\n- Context Injection API：给 Agent 提供检索后上下文。\n- Extraction Input：接收对话、文档、网页、规则文件和手工录入内容。\n- Rule Query / Subscription API：给 Agent 查询和订阅规则。\n- Research Task API / Event：输出结构化调研任务定义。\n- Dashboard / Activity / Detail API：给 Workbench 提供聚合与明细数据。\n- Research Task API / Queue Adapter：给调研规划器、Workbench 和宿主执行器提供任务创建、领取、回写和取消接口。\n\n#### 调研任务执行路径\n1. D 域的 Gap Detector 或用户手工操作生成 `Research Task draft`，写入 Research Queue。\n2. Research Planner 为任务补齐目标、范围、预算、优先级和推荐信息源，并决定进入 active 还是 silent 队列。\n3. Queue Adapter 把可执行任务暴露给宿主执行器、外部检索工具或人工领取入口。\n4. 执行器完成后，把结构化结果、原始引用和失败原因回写到 Research Task，并触发新的 Extraction Input。\n5. K 管线重新接管回流结果，生成 Analysis Artifact 和正式 Knowledge Entry；若执行失败，则保留失败记录与重试建议，不污染主知识库。\n6. W 通过 Activity API 和 Task Detail API 展示任务状态、预算消耗、回流结果和下一步操作。\n\n#### 外部协议与接口风格\n- 同步查询场景以 HTTP REST 或进程内函数接口承载。\n- 异步阶段推进以事件流承载。\n- 活动流与实时状态更新采用 SSE 或等价流式机制。\n- 外部宿主能力通过 Adapter SPI 或 capability registration 暴露。\n- 规则推送可用 Webhook、消息事件或宿主内信号机制承载。\n\n#### 技术边界图\n```text\n[Browser / Workbench]\n │ HTTP + SSE\n ▼\n[Web API Layer]\n │ internal service calls\n ▼\n[KIVO Core]\n ├─ Pipeline Orchestrator\n ├─ Knowledge Store\n ├─ Retrieval Engine\n ├─ Conflict Resolver\n ├─ Graph & Insight Engine\n ├─ Rule Distribution Engine\n └─ Host Adapter Layer\n │\n ├─ Provider APIs\n ├─ Storage SPI\n ├─ File System\n └─ Host Events / Notifications\n```\n\n### 3.5 上下文中的关键边界决定\n- KIVO 不等同于某个向量数据库封装层。\n- KIVO 不等同于某个图数据库产品。\n- KIVO 不把调研执行器写死在系统内部。\n- KIVO 不把 Workbench 和 Core 混成一层。\n- KIVO 不把规则订阅逻辑塞进普通知识检索流程。\n\n---\n\n## 4. 解决方案策略（Solution Strategy）\n\n### 4.1 总体策略\nKIVO 采用”核心知识平台 + 宿主适配层 + Workbench 消费层”的分层策略。\n整体按以下结构组织：\n- 一条事件驱动的知识管线，负责从输入走到入库和回流。\n- 一套结构化知识存储与检索能力，负责长期保留与取用。\n- 一层宿主适配机制，负责承接 Gateway、Provider、文件系统和调度能力。\n- 一层 Workbench，负责面向人类用户的浏览、审核、探索和调研操作。\n这套策略服务三个目标：让知识主干闭环先成立，让宿主可替换，让用户可直接使用。\n\n### 4.2 关键架构决策\n#### D-1 以 Knowledge Entry 为统一核心对象\n所有消费面都围绕 Knowledge Entry 工作。\n规则、调研任务、分析产物、冲突记录和图谱关系围绕它形成辅助对象。\n这样可以避免每个入口各自产生一套近似但不兼容的数据语义。\n\n#### D-2 提取管线拆成“分析产物生成”与“知识条目生成”两步\n系统先产出 Analysis Artifact，再决定是否生成正式知识条目。\n这样能提升可审计性，也给人工审核、低置信度拦截和调研建议生成留出稳定中间层。\n\n#### D-3 所有写入路径统一进入冲突治理\n手工录入、文档导入、网页抓取、对话提取、调研回流和批量导入都不能绕过冲突机制。\n这样能把一致性从规则变成基础设施。\n\n#### D-4 检索与规则分发双通道并存\n知识检索解决“当前要知道什么”。\n规则分发解决“当前必须遵守什么”。\n二者消费时机、权限模型和更新频率不同，分开设计更稳。\n\n#### D-5 宿主能力通过 Host Adapter 暴露\nKIVO Core 只认抽象能力：文件读写、网络访问、LLM 调用、Embedding 生成、事件投递和通知发送。\nOpenClaw 是首个适配目标，但不是唯一合法目标。\n\n#### D-6 Workbench 与 Core 解耦\nWorkbench 通过 API 消费 Core，而不是直接操纵内部存储结构。\n这样做能统一人类用户与 Agent 的业务语义，也有利于集中处理访问控制、审计和活动流。\n\n#### D-7 图谱、缺口检测、调研形成后置增值链路\n知识入库是主路径。\n图谱、洞察、缺口报告和调研任务围绕主路径生长。\n这样能保证最小运行模式成立，同时为高阶能力保留演进空间。\n\n#### D-8 先支持单机闭环，再开放后端替换点\n默认形态优先满足本地文件系统、轻量关系存储、可插拔向量能力和单 Node.js 进程运行。\n后续如需扩展到外部存储、分布式执行器或更复杂的 Provider 编排，可在 SPI 边界后替换实现。\n\n### 4.3 技术选型理由\n#### Node.js 作为主运行时\n理由：与 OpenClaw 宿主生态一致；适合 I/O 密集、事件驱动、接口聚合型系统；便于统一 Web API、后台管线和工具集成；对外发布和最小运行模式更友好。\n\n#### OpenClaw 插件 / 适配器边界作为首发集成点\n理由：当前业务就在 OpenClaw 体系内真实发生；宿主已有 Gateway、工具路由、工作区文件系统和外部协作能力；可把架构重点放在知识语义而不是重复造运行时。\n\n#### HTTP REST + 事件流的双制式接口\n理由：检索、详情、仪表盘适合同步请求；提取、图谱更新、活动流、调研任务生成适合异步流转；双制式接口能兼顾 Workbench、Agent 和宿主三类消费者。\n\n#### 存储抽象层（Storage SPI）\n理由：允许最小模式先跑在轻量本地存储上；为后续替换向量引擎、关系存储和图关系存储保留空间；避免上层逻辑被底层供应商特性反向塑形。\n\n#### Provider Router / Capability Registry\n理由：不同 Provider 的能力差异很大；KIVO 的核心能力依赖模型，但依赖方式不同；用 capability registry 管理模型能力，能把切换、降级和容错做成显式机制。\n\n#### SSE 驱动 Workbench 活动流与实时状态\n理由：活动流、调研状态、待确认项和冲突提醒有实时更新需求；SSE 比轮询更轻，部署成本也低，足够覆盖当前场景。\n\n### 4.4 与 15 个功能域的映射关系\n- 域 A 知识提取：落在输入适配层与分析管线入口，负责对话、文档、URL、规则文件和手工录入的进入方式。\n- 域 B 知识存储与检索：落在 Knowledge Store 与 Retrieval Engine，负责条目持久化、版本管理、关系维护、Embedding 缓存和语义查询。\n- 域 C 知识迭代：落在 Conflict Resolver 与 Lifecycle Manager，负责冲突检测、裁决策略、过期清理和合并回退。\n- 域 D 自主调研：落在 Gap Detector、Research Planner 与 Host Adapter 协同边界，负责把知识缺口变成可执行调研任务并接收回流结果。\n- 域 E 意图理解增强：落在 Retrieval Engine、Context Injector 与术语注入链路，负责给 Agent 提供贴近当前请求的上下文和消歧能力。\n- 域 F 规则订阅与分发：落在 Rule Engine、Subscription Registry 与 Distribution Channel，负责规则注册、订阅匹配、推送确认和范围控制。\n- 域 G 知识图谱与洞察：落在 Graph Engine 与 Insight Analyzer，负责关系图构建、结构洞察、图谱可视化支撑数据和缺口信号生成。\n- 域 H 系统词典：落在 Terminology Registry 与 Prompt Injection Support，负责术语统一、冲突识别、生命周期管理和注入支持。\n- 域 I 宿主适配层：落在 Host Adapter、Capability Registry 与 Provider Connector，负责宿主能力协商、Provider 管理与降级控制。\n- 域 K 知识管线编排：落在 Pipeline Orchestrator，负责阶段顺序、阶段跳过、失败隔离、事件推进和扩展阶段注册。\n- 域 L 分析中间产物：落在 Analysis Artifact Store 与 Review Queue，负责保存语义中间层，支撑审计、人工审核和后续消费。\n- 域 M 知识域目标声明：落在 Domain Purpose Registry 与 Ranking / Research Constraints，负责给提取、检索、缺口检测和调研生成提供目标边界。\n- 域 W 知识工作台：落在 Workbench Frontend 与 Web API Layer，负责人类使用面的仪表盘、列表、详情、活动流、调研、导入、字典和意图库。\n- 域 X 访问控制与可观测性：横切整个系统，负责域访问控制、操作审计、指标采集、导入导出和聚合观察视图。\n- 域 Z 开箱即用与商用就绪：横切安装、配置、Bootstrap、最小运行模式、文档交付和升级迁移，决定系统能否被外部用户直接使用。\n\n### 4.5 策略收束\nKIVO 用统一知识对象、事件驱动管线、宿主适配抽象和独立 Workbench，把分散的 Agent 知识转成可持续运营的知识系统。\n\n---\n\n## 5. 构建块视图（Building Block View）\n\n### 5.1 Level 1：顶层模块分解\n\nKIVO 的顶层构建块按 15 个功能域展开，但实现上按四层组织：输入与消费层、核心知识层、横切治理层、外部适配层。\n\n```text\nKIVO\n├─ 输入与消费层\n│ ├─ A 知识提取\n│ ├─ W 知识工作台\n│ └─ E 意图理解增强\n├─ 核心知识层\n│ ├─ B 知识存储与检索\n│ ├─ C 知识迭代\n│ ├─ D 自主调研\n│ ├─ F 规则订阅与分发\n│ ├─ G 知识图谱与洞察\n│ ├─ H 系统词典\n│ ├─ K 知识管线编排\n│ ├─ L 分析中间产物\n│ └─ M 知识域目标声明\n├─ 横切治理层\n│ ├─ X 访问控制与可观测性\n│ └─ Z 开箱即用与商用就绪\n└─ 外部适配层\n └─ I 宿主适配层\n```\n\n#### A. 知识提取（Knowledge Extraction）\n- 职责：接收对话、文档、URL、规则文件和手工录入内容，归一化为 Extraction Input，并产出可追溯的 Source Reference。\n- 接口：`submitConversation()`、`submitDocument()`、`submitUrl()`、`submitManualEntry()`。\n- 依赖：K 管线编排、L 分析中间产物、I 宿主适配层、X 审计日志。\n\n#### B. 知识存储与检索（Knowledge Store & Retrieval）\n- 职责：管理 Knowledge Entry、版本、状态、向量、关联与查询计划，是所有知识消费路径的主存储中心。\n- 接口：`saveEntry()`、`updateEntry()`、`queryKnowledge()`、`getEntryHistory()`、`findRelatedEntries()`。\n- 依赖：C 知识迭代、G 图谱、H 系统词典、I Provider 管理、X 访问控制。\n\n#### C. 知识迭代（Knowledge Iteration）\n- 职责：检测冲突、处理合并、执行过期清理、管理 superseded 与 deprecated 状态。\n- 接口：`detectConflicts()`、`resolveConflict()`、`mergeEntries()`、`deprecateEntry()`、`archiveEntry()`。\n- 依赖：B 存储与检索、L 分析中间产物、I Provider 管理、X 审计与指标。\n\n#### D. 自主调研（Autonomous Research）\n- 职责：根据缺口报告生成调研任务、控制预算、接收回流结果，并把结果送回知识管线。\n- 接口：`createResearchTask()`、`reprioritizeTask()`、`cancelTask()`、`ingestResearchResult()`。\n- 依赖：G 图谱洞察、M 域目标声明、I 宿主适配层、W 调研管理界面。\n\n#### E. 意图理解增强（Intent Enhancement）\n- 职责：对 Agent 查询做语义解释、上下文筛选、术语注入与歧义提示，形成面向执行时的增强上下文。\n- 接口：`prepareContext()`、`rankContextEntries()`、`injectTerminology()`、`suggestClarification()`。\n- 依赖：B 检索、H 术语、M 域目标声明、X 权限裁剪。\n\n#### F. 规则订阅与分发（Rule Subscription & Distribution）\n- 职责：管理 Rule Entry、订阅关系、分发记录和确认状态，保证治理信息以独立通道传播。\n- 接口：`registerRule()`、`subscribeRules()`、`pullRules()`、`pushRuleChange()`、`ackDistribution()`。\n- 依赖：I 宿主事件能力、X 权限模型、W 规则相关配置页。\n\n#### G. 知识图谱与洞察（Knowledge Graph & Insights）\n- 职责：根据条目与关系维护图谱，识别孤立节点、桥接节点、稀疏社区和跨主题异常连接。\n- 接口：`updateGraph()`、`listGraphNeighbors()`、`generateInsights()`、`exportGraphView()`。\n- 依赖：B 关联关系、C 生命周期状态、D 调研任务生成、W 图谱可视化。\n\n#### H. 系统词典（System Dictionary）\n- 职责：统一术语名、定义、约束、正负例和别名，给意图增强和内容生成提供术语语义底座。\n- 接口：`upsertTerm()`、`searchTerm()`、`injectTerms()`、`mergeTerms()`。\n- 依赖：B 存储、C 冲突检测、E 上下文注入、W 系统字典管理。\n\n#### I. 宿主适配层（Host Adapter）\n- 职责：把 OpenClaw 或其他宿主暴露的文件、网络、Provider、事件、通知能力转成稳定 SPI。\n- 接口：`registerHostCapabilities()`、`callProvider()`、`emitHostEvent()`、`readSource()`、`writeExport()`。\n- 依赖：宿主环境本身；被 A、D、F、K、Z 多个域调用。\n\n#### K. 知识管线编排（Knowledge Pipeline Orchestration）\n- 职责：编排提取、分析、分类、冲突检测、合并、入库、图谱更新和缺口检测阶段。\n- 接口：`startPipeline()`、`resumeStage()`、`registerStage()`、`recordStageFailure()`。\n- 依赖：A、L、C、B、G、D、X。\n\n#### L. 分析中间产物（Analysis Artifacts）\n- 职责：保存提取过程中的断言候选、实体候选、冲突候选、缺口候选与审核候选，作为审计与人工介入入口。\n- 接口：`saveArtifact()`、`loadArtifact()`、`approveCandidate()`、`rejectCandidate()`。\n- 依赖：A 输入、K 管线、W 审核界面、X 审计日志。\n\n#### M. 知识域目标声明（Domain Purpose）\n- 职责：定义每个知识域的目标、关键问题、非目标和研究边界，约束提取、检索和调研方向。\n- 接口：`getDomainPurpose()`、`rankAgainstPurpose()`、`validateResearchBoundary()`。\n- 依赖：E 意图增强、D 调研、A 提取路由、W 意图库与域配置界面。\n\n#### W. 知识工作台（Knowledge Workbench）\n- 职责：向用户提供仪表盘、列表、详情、活动流、冲突裁决、调研管理、文档导入、系统字典与意图库。\n- 接口：HTTP API、SSE 事件流、文件上传入口、管理操作入口。\n- 依赖：B、C、D、G、H、L、X、Z。\n\n#### X. 访问控制与可观测性（Access Control & Observability）\n- 职责：统一处理 callerRole、域级权限、操作审计、指标采集、导入导出和故障可观测性。\n- 接口：`authorizeDomainAccess()`、`recordMetric()`、`appendAuditLog()`、`exportKnowledgeSet()`。\n- 依赖：横切所有域；底层依赖 I 提供的持久化和事件能力。\n\n#### Z. 开箱即用与商用就绪（Out-of-Box & Commercial Readiness）\n- 职责：管理安装校验、初始化引导、最小运行模式、配置检查、升级迁移和首次知识旅程。\n- 接口：`runBootstrap()`、`runHealthCheck()`、`loadSeedData()`、`runMigration()`。\n- 依赖：I 宿主适配、W 界面、X 审计、B 数据导入导出。\n\n### 5.2 Level 2：核心模块内部结构\n\n#### 5.2.1 Knowledge Entry Management\n\n```text\nKnowledge Entry Management\n├─ Entry Factory\n├─ Schema Validator\n├─ Version Manager\n├─ Lifecycle Manager\n└─ Link Maintainer\n```\n\n##### Entry Factory\n- 职责：把 Analysis Artifact、手工录入或调研结果转换为统一的 Knowledge Entry 草稿。\n- 接口：`buildDraftFromArtifact()`、`buildDraftFromManualInput()`。\n- 依赖：L 分析中间产物、M 域目标声明。\n\n##### Schema Validator\n- 职责：校验类型、状态、来源引用、metadata 扩展和领域约束，阻止脏数据进入主库。\n- 接口：`validateEntry()`、`validateMetadataExtension()`。\n- 依赖：B 存储模型、H 术语约束、X 访问控制规则。\n\n##### Version Manager\n- 职责：维护版本号、变更摘要、supersedes 关系和乐观锁字段 `expectedVersion`。\n- 接口：`createNextVersion()`、`diffVersions()`、`checkOptimisticLock()`。\n- 依赖：B 持久化、C 冲突治理。\n\n##### Lifecycle Manager\n- 职责：驱动 pending、active、superseded、deprecated、archived 的状态流转。\n- 接口：`activateEntry()`、`supersedeEntry()`、`deprecateEntry()`、`archiveEntry()`。\n- 依赖：C 过期清理、W 条目操作、X 审计日志。\n\n##### Link Maintainer\n- 职责：维护 supplements、supersedes、conflicts、depends_on 等关系，并把关系同步给图谱。\n- 接口：`linkEntries()`、`unlinkEntries()`、`syncGraphEdges()`。\n- 依赖：G 图谱、C 合并策略、B 检索索引。\n\n#### 5.2.2 Intent Routing & Context Injection\n\n这里的“意图路由”指用户请求进入 KIVO 后，系统决定该请求落入哪个知识域、调用哪种检索策略、是否触发澄清。\n\n```text\nIntent Routing & Context Injection\n├─ Query Analyzer\n├─ Domain Selector\n├─ Retrieval Planner\n├─ Context Packager\n└─ Clarification Advisor\n```\n\n##### Query Analyzer\n- 职责：解析查询文本、识别任务类型、抽取时间/来源/知识类型过滤条件。\n- 接口：`analyzeQuery()`。\n- 依赖：H 术语注册表、M 域目标声明。\n\n##### Domain Selector\n- 职责：根据 query、callerRole 与 domain purpose 选择优先知识域，并执行域外裁剪。\n- 接口：`selectDomains()`、`pruneOutOfScopeEntries()`。\n- 依赖：M 域目标声明、X 访问控制。\n\n##### Retrieval Planner\n- 职责：决定走语义检索、元数据检索还是混合检索；在 Provider 不可用时切到降级路径。\n- 接口：`buildQueryPlan()`、`fallbackToKeywordMode()`。\n- 依赖：B 检索引擎、I Provider Registry。\n\n##### Context Packager\n- 职责：把返回条目压缩成 token 预算内的上下文包，优先保留术语、近期决策和高置信事实。\n- 接口：`packageContext()`、`rankByBudget()`。\n- 依赖：B 检索结果、H 术语注入、C 生命周期状态。\n\n##### Clarification Advisor\n- 职责：在高歧义查询下返回澄清建议，避免系统强行猜测。\n- 接口：`suggestClarification()`、`explainWhyAmbiguous()`。\n- 依赖：E 历史偏好、B 检索结果、M 关键问题集。\n\n#### 5.2.3 Rule Subscription & Distribution\n\n```text\nRule Subscription & Distribution\n├─ Rule Registry\n├─ Subscription Matcher\n├─ Delivery Coordinator\n└─ Distribution Ledger\n```\n\n##### Rule Registry\n- 职责：保存 Rule Entry 正文、适用范围、优先级、生效条件和失效条件。\n- 接口：`createRule()`、`updateRule()`、`listRulesByScope()`。\n- 依赖：B 持久化、C 规则冲突检测。\n\n##### Subscription Matcher\n- 职责：根据 agent、角色、域和场景，计算某次规则变更影响的订阅者集合。\n- 接口：`matchSubscribers()`、`refreshSubscriptions()`。\n- 依赖：X 权限模型、I 宿主 Agent 元数据。\n\n##### Delivery Coordinator\n- 职责：执行拉取优先、推送补充的分发策略；对高优先级规则触发主动通知。\n- 接口：`pushRuleChange()`、`prepareRulePullSnapshot()`。\n- 依赖：I 宿主事件能力、W 管理界面。\n\n##### Distribution Ledger\n- 职责：记录送达目标、目标版本、确认状态、失败原因和重试次数。\n- 接口：`recordDelivery()`、`recordAck()`、`listUndeliveredRules()`。\n- 依赖：X 审计和指标、F 重试策略。\n\n#### 5.2.4 Pipeline Orchestrator\n\n```text\nPipeline Orchestrator\n├─ Stage Registry\n├─ Event Router\n├─ Failure Isolator\n└─ Progress Tracker\n```\n\n##### Stage Registry\n- 职责：注册提取、审核、冲突检测、入库、图谱更新、缺口检测、调研回流等阶段，并声明前后置依赖与可跳过条件。\n- 接口：`registerStage()`、`resolveStagePlan()`、`listEnabledStages()`。\n- 依赖：Z 最小运行模式配置、I 宿主能力、X 审计日志。\n\n##### Event Router\n- 职责：在阶段之间传递 `pipelineId`、事件载荷和上下文状态，保证同一条知识管线按确定顺序推进。\n- 接口：`dispatchStageEvent()`、`resumeFromCheckpoint()`、`fanOutPostCommitEvents()`。\n- 依赖：A 输入层、L 分析中间产物、B 主存储、G 图谱、D 调研。\n\n##### Failure Isolator\n- 职责：把局部失败限制在当前阶段或当前条目，防止一条低质量输入拖垮整批导入或其他并发任务。\n- 接口：`quarantineFailedStage()`、`markRetryableFailure()`、`openManualReviewPath()`。\n- 依赖：X 指标与告警、W 审核界面、I 宿主任务能力。\n\n##### Progress Tracker\n- 职责：记录阶段开始、结束、耗时、重试次数和当前状态，为活动流、审计和恢复执行提供统一真相源。\n- 接口：`startStage()`、`completeStage()`、`snapshotPipeline()`。\n- 依赖：X 审计日志、W 活动流、Z 首次知识旅程引导。\n\n#### 5.2.5 Conflict Resolver\n\n```text\nConflict Resolver\n├─ Candidate Screener\n├─ Semantic Judge\n├─ Strategy Selector\n└─ Rollback Guard\n```\n\n##### Candidate Screener\n- 职责：对新条目做 embedding 粗筛、主题聚类和元数据预过滤，缩小需要精判的候选冲突集合。\n- 接口：`screenCandidates()`、`scoreTopicOverlap()`、`dropIrrelevantPairs()`。\n- 依赖：B 检索索引、H 术语约束、I Embedding Provider。\n\n##### Semantic Judge\n- 职责：对候选冲突对执行语义精判，区分互斥、补充、改写、时间先后和表述差异。\n- 接口：`judgeConflict()`、`classifyContradictionType()`、`explainDecision()`。\n- 依赖：I LLM Provider、L Analysis Artifact、B 历史版本。\n\n##### Strategy Selector\n- 职责：根据冲突类型、来源权重、时间新鲜度和 callerRole 选择自动合并、保留并存、人工裁决或延迟处理策略。\n- 接口：`selectResolutionStrategy()`、`rankSourceAuthority()`、`decideAutoMerge()`。\n- 依赖：M 域目标声明、X 权限与审计、W 冲突裁决界面。\n\n##### Rollback Guard\n- 职责：在自动裁决或合并后保留可恢复快照，发现误判时能回退到上一个稳定版本。\n- 接口：`createResolutionCheckpoint()`、`rollbackResolution()`、`replayConflictFlow()`。\n- 依赖：B Version Manager、X 审计日志、G 图谱关系同步。\n\n### 5.3 构建块之间的主依赖关系\n\n- A 只负责把来源送进 K，不直接写主库。\n- K 是主干调度器，驱动 A → L → C → B → G → D 的事件链。\n- B 是知识资产中心，E、G、H、W 都通过 B 消费知识，而不是直接读原始来源。\n- C 管状态和冲突，所有写入路径都要经过它。\n- F 与 E 分离：F 管必须遵守的规则，E 管当前需要知道的知识。\n- I 提供能力边界，避免 Core 直接粘在 OpenClaw 运行时细节上。\n- X 和 Z 横切所有层，分别管治理质量与可交付性。\n\n---\n\n## 6. 运行时视图（Runtime View）\n\n### 6.1 场景一：知识条目的完整生命周期\n\n#### 触发\n用户上传文档、标记对话片段、提交 URL，或调研任务回流结果。\n\n#### 运行时交互\n1. 输入先进入 A 域，生成统一的 Source Reference。\n2. K 启动新的 pipeline instance，写入 `pipelineId` 和阶段状态。\n3. L 生成 Analysis Artifact，提取断言、实体、概念、候选关联、候选冲突和候选缺口。\n4. 若分析置信度过低，artifact 进入审核队列，条目暂不生成。\n5. Entry Factory 从 artifact 生成 Knowledge Entry draft。\n6. Schema Validator 校验类型、来源、domain、metadata 扩展。\n7. C 的 Conflict Resolver 做粗筛：按 embedding 相似度或元数据主题找候选冲突对。\n8. 若 Provider 可用，进入语义精判；若不可用，保留候选冲突并标记待补判。\n9. 无冲突时，B 保存新条目并生成版本号；有冲突时，按时间优先、来源优先或人工裁决流继续。\n10. Link Maintainer 建立 supplements、supersedes、depends_on、conflicts 等关系。\n11. G 基于新条目和关系更新图谱局部子图。\n12. D 读取新增条目后的图谱与查询未命中信号，判断是否形成新缺口。\n13. X 记录整条链路的审计日志、指标和耗时。\n14. W 的活动流收到事件，用户可在界面里看到“导入完成”“待确认”“冲突待裁决”等状态。\n15. 后续若条目长时间未被引用或被外部验证为过时，C 把它从 active 转为 deprecated，再在清理周期后归档。\n\n#### 结果\n- 正常路径：条目进入 active，可检索、可关联、可注入。\n- 低置信路径：条目进入 pending，等待人工确认。\n- 冲突路径：生成 Conflict Record，并暂停到裁决完成。\n- 过时路径：条目退出主检索结果，但历史版本仍可追踪。\n\n### 6.2 场景二：意图路由的请求处理流程\n\n#### 触发\nAgent 在处理用户请求前调用 `prepareContext()` 或直接发起 `queryKnowledge()`。\n\n#### 运行时交互\n1. E 的 Query Analyzer 解析查询文本，提取关键词、语义主题、时间限定、知识类型限定和 domain 候选。\n2. X 根据 callerRole 裁剪可访问知识域。\n3. Domain Selector 结合 M 的域目标声明，选出优先查询域与排除域。\n4. Retrieval Planner 判断当前 Provider 能力：\n - 有 embedding 能力：走混合检索。\n - 无 embedding 能力：走关键词 + 元数据过滤降级路径。\n5. B 执行检索，返回候选条目、相关度评分、来源、版本状态和图谱邻居摘要。\n6. H 查询与当前主题高度相关的术语条目，按 scope 和 token 预算裁剪。\n7. Context Packager 组装上下文包：术语 → 最新决策 → 高置信事实 → 相关经验 → 补充方法。\n8. 如果结果分散且置信度低，Clarification Advisor 返回澄清建议，例如“你要的是安装路径，还是迁移策略”。\n9. E 把最终上下文包返回给 Agent，Agent 再进入自己的任务执行流程。\n10. 若本次查询未命中或结果质量低，X 记录 miss 信号，D 后续可把它纳入缺口检测。\n\n#### 结果\n- 命中路径：Agent 获得按预算压缩后的高相关上下文。\n- 降级路径：返回结果带有 `degraded=true` 标记，便于上层知道当前依赖关键词检索。\n- 歧义路径：系统优先返回澄清建议，不直接给出高风险结论。\n\n### 6.3 场景三：规则订阅的触发与分发\n\n#### 触发\n治理文件变更、手工新增 Rule Entry，或已有规则的优先级与适用范围变化。\n\n#### 运行时交互\n1. A 的规则提取入口接收到 AGENTS.md、SOUL.md 或规则配置变更。\n2. L 产出规则类分析结果，提取规则正文、作用域、优先级、前置条件和覆盖关系候选。\n3. F 的 Rule Registry 创建新版本 Rule Entry。\n4. C 检查规则冲突：同一场景下是否出现相互矛盾的约束。\n5. Subscription Matcher 计算受影响的订阅者集合，依据包括 agentId、角色、域、场景标签。\n6. Delivery Coordinator 判断分发方式：\n - 普通规则：下一次拉取时获取。\n - 高优先级规则：立即推送通知。\n7. I 通过宿主事件能力把变更送到目标 Agent 或共享快照存储。\n8. Distribution Ledger 记录本次分发的目标版本、成功数、失败数、未确认数。\n9. 目标 Agent 启动时或收到事件后执行 `pullRules()`，并回写确认状态。\n10. 若超过重试阈值仍未确认，X 触发告警并在 Workbench 活动流中显示异常。\n\n#### 结果\n- 规则可追溯地送达到订阅者。\n- 失败分发不会污染普通知识检索路径。\n- 用户能在 Workbench 里看到哪些 Agent 还未拿到新规则版本。\n\n### 6.4 场景四：知识质量审计流程\n\n#### 触发\n定时审计、用户主动发起审计、升级前自检，或某个域连续出现检索未命中与冲突堆积。\n\n#### 运行时交互\n1. W 发起“运行知识审计”操作，或系统按计划触发 Audit Job。\n2. X 聚合近一段时间的核心信号：检索命中率、pending 数量、冲突积压、分发失败、图谱孤立节点占比。\n3. 审计器按域扫描 B 中的条目状态，检查是否存在：\n - 无来源引用的 active 条目。\n - 长期 pending 未处理条目。\n - superseded 关系断裂。\n - deprecated 但仍频繁被注入的条目。\n4. G 输出结构洞察，识别近期新增但未形成关联的知识簇。\n5. D 根据审计缺口生成候选调研任务，但默认先进入建议态，不直接抢占资源执行。\n6. 审计结果汇总成 Audit Report，按问题类型分级：P0 数据一致性、P1 检索有效性、P2 可观测性、P3 体验问题。\n7. W 展示可操作清单，用户可直接进入冲突裁决、条目清理、调研创建或规则修复。\n8. X 把审计结论写入审计日志，用于后续趋势分析。\n\n#### 结果\n- 系统知道知识库“有没有东西”，也知道“这些东西好不好用”。\n- 审计输出直接联动修复动作，不停留在静态报告。\n\n### 6.5 场景五：首次知识旅程\n\n#### 触发\n外部陌生用户首次打开空库环境，系统已经完成安装与基础配置校验。\n\n#### 运行时交互\n1. Z 的 `runBootstrap()` 检查 workspace 可写、存储 schema 就绪、文本 LLM 可用、Workbench basePath 正常。\n2. W 渲染空库首页，展示“上传文档”“导入示例数据”“手动新建知识”三个入口和系统就绪度清单。\n3. 用户选择任一入口后，A 把输入转换成统一的 Extraction Input，并为这次首次旅程打上 `journey=first-run` 标记。\n4. K 创建新的 pipeline instance，Progress Tracker 把当前进度同步到 Activity Stream。\n5. L 生成首批 Analysis Artifact，若结果置信度过低，则把候选项送入 Pending Queue，并在界面提示用户先确认一条示例知识。\n6. C 执行最小冲突检查，避免示例数据或首次导入内容和已存在种子数据重复冲突。\n7. B 保存首批 active 条目，并在必要时为缺失 embedding 的条目标记待补建索引。\n8. G 为首批条目建立基础关系，生成可浏览的最小知识子图。\n9. W 自动跳转到知识列表或刚导入条目的详情页，给出一次预填的搜索建议。\n10. 用户执行第一次检索，E 调用 Query Analyzer、Domain Selector 和 Retrieval Planner 生成查询计划。\n11. B 返回命中结果后，W 在结果页展示来源、类型、状态和关联摘要；若未命中，则 Z 提供下一步动作建议，而不是空白页。\n12. X 记录首次知识旅程耗时、卡点阶段和成功率，供后续引导优化使用。\n\n#### 结果\n- 成功路径：用户在 10 分钟内完成首次导入、看到结果并完成第一次检索命中。\n- 待确认路径：系统仍能给出明确下一步动作，用户不会卡在空库状态。\n- 降级路径：当 embedding 或实时能力缺失时，系统显式提示当前运行在最小模式，但核心旅程仍可完成。\n\n---\n\n## 7. 部署视图（Deployment View）\n\n### 7.1 OpenClaw 插件部署拓扑\n\n```text\n┌────────────────────────────────────────────┐\n│ Browser / Workbench Client │\n│ - Dashboard / Search / Graph / Review │\n└────────────────────┬──────────────────────┘\n │ HTTP + SSE\n┌────────────────────▼──────────────────────┐\n│ OpenClaw Gateway │\n│ - Plugin host │\n│ - API routing │\n│ - Session / tool mediation │\n└────────────────────┬──────────────────────┘\n │ in-process calls / plugin events\n┌────────────────────▼──────────────────────┐\n│ KIVO Plugin Runtime │\n│ - Web API layer │\n│ - Pipeline orchestrator │\n│ - Knowledge store │\n│ - Retrieval / Rule / Graph / Research │\n└───────────────┬───────────────┬────────────┘\n │ │\n file I/O │ │ provider calls\n │ │\n┌───────────────▼───────┐ ┌───▼────────────────┐\n│ Workspace Storage │ │ LLM / Embedding │\n│ - knowledge data │ │ Providers │\n│ - artifacts │ │ - text generation │\n│ - audit logs │ │ - structured output│\n│ - exports / imports │ │ - embeddings │\n└───────────────┬───────┘ └────────────────────┘\n │\n optional host events / notifications\n │\n Feishu / Webhook / task executor\n```\n\n### 7.2 运行时节点说明\n\n#### 节点 1：Workbench Client\n- 形态：浏览器中的单页或多页 Web 应用。\n- 职责：展示仪表盘、搜索、图谱、审核、调研、系统字典和活动流。\n- 约束：只通过 HTTP API 和 SSE 与后端通信，不直接触碰底层知识文件。\n\n#### 节点 2：OpenClaw Gateway\n- 形态：宿主守护进程或服务进程。\n- 职责：承载插件生命周期、路由 API、暴露宿主能力、连接消息与工具体系。\n- 约束：KIVO 必须遵守插件边界，不能把宿主内部状态结构硬编码进 Core。\n\n#### 节点 3：KIVO Plugin Runtime\n- 形态：Node.js 进程内插件模块，首发以单进程部署。\n- 职责：承载 Web API、核心知识服务、事件管线、规则分发、调研任务定义与图谱更新。\n- 约束：需要在单机资源下跑通最小闭环，避免强依赖外部重型服务。\n\n#### 节点 4：Workspace Storage\n- 形态：本地文件系统 + 轻量结构化存储。\n- 职责：保存知识条目、分析产物、导入导出包、图谱缓存、审计日志、迁移状态。\n- 约束：路径布局要稳定，便于备份、迁移和离线恢复。\n\n#### 节点 5：LLM / Embedding Providers\n- 形态：外部 API 或宿主接入的 Provider。\n- 职责：承担结构化提取、冲突精判、意图消歧、embedding 生成。\n- 约束：能力可能缺失或波动，KIVO 需要 capability registry 和降级逻辑。\n\n#### 节点 6：外部协作与执行节点\n- 形态：Feishu、Webhook 接收端、宿主任务执行器、外部检索工具。\n- 职责：承接通知、执行调研任务、消费导出结果。\n- 约束：这些节点不保存主知识库真相，只消费或反馈事件。\n\n### 7.3 部署变体\n\n#### 最小运行模式（standalone）\n- 一个 OpenClaw Gateway。\n- 一个 KIVO Plugin Runtime。\n- 一个本地存储目录。\n- 一个文本 LLM Provider。\n- Embedding Provider 可选；缺失时降级为关键词检索。\n\n#### 宿主嵌入模式（embedded）\n- KIVO 作为宿主插件存在。\n- 调研执行、消息通知、权限身份由宿主提供。\n- KIVO Core 通过 Host Adapter 消费这些能力。\n\n#### 扩展模式（full-stack）\n- Workbench 可独立部署在前端静态托管或 Node Web 服务中。\n- KIVO API 与 Core 仍以单逻辑边界存在。\n- 存储、检索、图谱引擎可在 SPI 后替换，但上层 API 语义不变。\n\n### 7.4 运行时依赖\n\n#### Node.js\n- 作为主运行时，承担 HTTP API、事件编排、文件 I/O 和 Provider 调用。\n- 需要稳定的异步模型和足够的内存容纳检索缓存、图谱局部更新和活动流连接。\n\n#### 文件系统\n- 承载导入源、知识数据、artifact、导出包、迁移脚本状态和审计日志。\n- 需要可写路径、备份策略和权限隔离。\n\n#### LLM Provider\n- 负责结构化提取、冲突精判、歧义判断和调研结果规整。\n- 需要支持超时、重试、失败分类与替补策略。\n\n#### Embedding Provider\n- 负责语义向量生成与缓存。\n- 缺失时系统仍可用，但检索质量下降，且需要在 UI 与 API 中显式暴露降级状态。\n\n#### OpenClaw 宿主能力\n- 提供插件生命周期、任务环境、工具转发、消息通道和共享 workspace。\n- 在嵌入模式下，调研执行与规则通知高度依赖这一层。\n\n---\n\n## 8. 横切概念（Crosscutting Concepts）\n\n### 8.1 知识条目的统一数据模型\n\nKIVO 的核心数据对象是 Knowledge Entry。所有上层功能都围绕它，而不是围绕原始文档或会话片段。\n\n#### Knowledge Entry 核心字段\n- `id`：全局唯一标识。\n- `type`：fact、methodology、decision、experience、intent、meta。\n- `domain`：知识域归属，用于权限与目标约束。\n- `title`：面向人类阅读的简短标题。\n- `content`：结构化正文或摘要正文。\n- `status`：pending、active、superseded、deprecated、archived。\n- `version`：整型或语义版本号，配合 `expectedVersion` 支持乐观锁。\n- `sources[]`：来源引用数组，可指向对话、文件、URL、规则文件、调研产物。\n- `relations[]`：与其他条目的结构化关系。\n- `embedding`：条目的语义向量引用或内联缓存。最小模式下可直接挂在条目记录中；扩展模式下也可只保存 `embeddingRef`、向量维度、模型版本和最后更新时间，把大向量内容交给独立索引区管理。\n- `metadata`：领域扩展字段，承载术语、规则、审计标签、图谱权重等专属信息。\n- `createdAt / updatedAt`：时间戳。\n- `confidence`：提取或判定置信度。\n\n#### 同族对象与差异\n- Rule Entry：治理对象，生命周期与订阅范围优先于正文内容长度。\n- Analysis Artifact：中间对象，强调可追溯和可审计，不直接参与主检索。\n- Conflict Record：关系对象，连接两个或多个条目，记录冲突类型、裁决过程与结论。\n- Research Task：执行对象，记录目标、预算、状态、回流结果。\n- Domain Purpose：约束对象，影响提取、排序和调研范围。\n\n#### 数据模型原则\n- 一个条目表达一个可独立判断的知识断言。\n- 原文放在来源引用中，知识库存结构化结果。\n- 版本变更保留历史，不做静默覆盖。\n- 领域差异走 `metadata` 扩展，不拆出彼此隔离的主表语义。\n\n### 8.2 错误处理策略\n\n#### 错误分类\n- 输入错误：文件格式错误、缺字段、非法状态流转、权限不足。\n- 管线错误：某阶段执行失败、阶段超时、上下游依赖未准备好。\n- Provider 错误：超时、限流、结构化输出不合法、能力缺失。\n- 存储错误：写入失败、版本冲突、索引补建失败、迁移失败。\n- 分发错误：规则送达失败、确认超时、事件通知失败。\n\n#### 处理原则\n- 能局部失败的地方不拖垮整条系统主路径。\n- Analysis Artifact 优先落盘，保证失败后还能复盘。\n- 写入前校验，写入后审计，避免坏数据长期留存。\n- 降级状态必须显式暴露，不能在检索质量下降时伪装成正常结果。\n- 对用户可操作的错误返回恢复动作；对系统内部错误返回诊断上下文。\n\n#### 常见恢复路径\n- Embedding 失败：条目先入库，标记待补建索引。\n- 冲突精判失败：保留候选冲突并进入待裁决或待补判队列。\n- 调研执行失败：Research Task 标记失败，不回滚已有知识库。\n- 规则推送失败：保留拉取快照路径，并持续记录未确认状态。\n- 迁移失败：停止升级并允许回滚到迁移前快照。\n\n### 8.3 日志与可观测性\n\n#### 审计日志\n- 记录条目创建、更新、状态变更、冲突裁决、规则分发、调研任务流转和管理员操作。\n- 关键字段包含 actor、target、before、after、timestamp、requestId、pipelineId。\n\n#### 指标\n- 检索命中率、检索响应时间、降级查询占比。\n- pending 条目数量、冲突积压量、冲突解决时长。\n- 规则分发成功率、未确认规则数量。\n- 图谱孤立节点比例、桥接节点数量变化。\n- 调研任务创建数、成功率、预算超支率。\n\n#### 追踪\n- 单次导入或调研回流都带 `pipelineId`。\n- 用户界面操作与后端事件共享 `requestId`。\n- Provider 调用保留 `providerId` 与能力标签，便于排查某家模型的结构化输出问题。\n\n#### 活动流\n- 活动流是面向用户的观测视图，不是底层日志的简单原样转发。\n- 同一批导入会按业务事件聚合，例如“导入完成 18 条，3 条待确认，1 条待裁决”。\n\n### 8.4 安全与隐私\n\n#### 访问控制\n- 所有查询都带 callerRole 或等价身份信息。\n- 域级权限优先于检索相关度，先裁剪可见范围，再做排序。\n- 规则分发遵循订阅范围，不能越域推送。\n\n#### 数据最小化\n- 原始文档不默认长期保存；知识提取完成后按策略清理。\n- 上下文注入只返回当前任务需要的最小知识集合。\n- 导出遵守筛选范围与权限边界。\n\n#### 来源可信度\n- 高置信 active 条目应具有可追溯来源。\n- 无来源或低置信内容保持 pending，不直接进入长期稳定知识。\n\n#### 宿主隔离\n- KIVO Core 不直接读取宿主私有状态文件格式，统一经 Host Adapter。\n- 对外 Provider 密钥与宿主身份信息不进入知识条目正文。\n\n### 8.5 版本与迁移\n\n- 文档、规则、术语、知识条目都采用可追溯版本语义。\n- 数据结构变更附带迁移脚本和格式版本号。\n- 导入导出包必须包含 schema version，防止跨版本静默损坏。\n\n---\n\n## 9. 架构决策记录（Architecture Decisions）\n\n### ADR-001：以 Knowledge Entry 作为统一核心对象\n\n#### Context\nKIVO 同时处理事实、方法、经验、意图、规则、调研结果和术语。若每类对象各自形成主存储模型，检索、权限、版本和活动流都会出现重复实现。\n\n#### Decision\n以 Knowledge Entry 作为统一知识对象；Rule Entry、术语条目等特殊对象在统一模型上扩展字段；Conflict Record、Analysis Artifact、Research Task 作为配套对象围绕它建立关系。\n\n#### Consequences\n- 检索、版本、状态机、权限裁剪可以复用一套主路径。\n- 数据模型更稳定，便于导入导出和迁移。\n- `metadata` 扩展设计会承受较高复杂度，需要严格 schema 校验。\n\n### ADR-002：采用“分析产物先行”的两段式提取\n\n#### Context\n直接从原始输入生成正式知识条目，容易把误提取、低置信候选和未解释的冲突一起写进主库，后续难以复盘。\n\n#### Decision\n提取过程拆成两步：先生成 Analysis Artifact，再从 artifact 生成 Knowledge Entry。高置信路径自动继续，低置信路径进入人工审核。\n\n#### Consequences\n- 审计能力增强，提取错误可定位到分析阶段。\n- 用户可以看到候选项，而不是只能接受最终结果。\n- 存储与界面复杂度上升，需要额外维护 artifact 生命周期。\n\n### ADR-003：通过 Host Adapter + Capability Registry 解耦宿主能力\n\n#### Context\nKIVO 首发部署在 OpenClaw 内，但产品边界要求未来可以迁移到其他宿主。宿主之间的文件、消息、工具和 Provider 接口差异很大。\n\n#### Decision\nKIVO Core 只依赖抽象能力：文件读写、网络访问、Provider 调用、事件投递、通知发送。具体宿主通过 Host Adapter 注册能力，Capability Registry 记录可用性与版本约束。\n\n#### Consequences\n- Core 可以在不同宿主间迁移，复用率高。\n- 宿主能力变化时可做显式降级。\n- 适配层需要长期维护稳定契约，早期设计必须克制，避免抽象过度。\n\n### ADR-004：检索与规则分发分成双通道\n\n#### Context\n知识检索服务“当前要知道什么”，规则分发服务“当前必须遵守什么”。二者在时效性、权限边界、失败恢复和用户预期上差异明显。\n\n#### Decision\n把 Rule Entry、订阅关系和分发记录从普通知识检索路径中拆出，形成独立规则通道；普通知识查询不承担规则送达责任。\n\n#### Consequences\n- 治理信息与内容信息边界更清楚。\n- 规则送达失败不会影响知识检索可用性。\n- 系统多了一套分发台账与确认机制，实现成本上升。\n\n### ADR-005：首发采用单进程事件驱动架构，SPI 后保留替换点\n\n#### Context\n当前研发组织是 solo founder + AI agents，运维成本要低，最小运行模式要能单机启动。过早拆成多服务会把复杂度提前释放。\n\n#### Decision\n首发使用单个 Node.js 插件运行时承载 Web API、管线编排、检索、图谱和规则分发；存储、检索和图谱引擎通过 SPI 预留替换点。\n\n#### Consequences\n- 安装与调试成本低，符合开箱即用目标。\n- 在万级条目以上可能面临单进程内存和并发压力。\n- 后续扩展仍有出路，但需要谨慎管理模块边界，防止单进程内部耦合失控。\n\n### ADR-006：图谱计算本地优先，外部图数据库作为后续替换点\n\n#### Context\nKIVO 需要知识图谱来支撑关系浏览、结构洞察和缺口检测，但首发阶段的数据规模、部署门槛和运维复杂度都不适合强绑外部图数据库。\n\n#### Decision\n首发把图谱关系、局部邻居查询和洞察计算放在本地存储与内存索引中完成；仅在规模、并发或算法复杂度超过单机边界后，再通过 Graph SPI 接入外部图数据库。\n\n#### Consequences\n- 最小运行模式更轻，外部用户安装门槛低。\n- 早期图谱语义和对象模型可以先稳定下来，不被具体产品特性绑架。\n- 高阶遍历、复杂子图分析和跨项目图谱联邦会受限，需要为后续升级预留兼容层。\n\n### ADR-007：活动流与实时状态更新使用 SSE\n\n#### Context\nWorkbench 需要把导入进度、冲突待裁决、调研状态和系统活动流实时推给用户。轮询会增加无效请求，WebSocket 在当前场景里又偏重。\n\n#### Decision\nWorkbench 实时通道默认采用 SSE。服务端按用户会话或工作台视图维度输出单向事件流，客户端在断线后自动重连，并通过最近事件游标补齐缺失事件。\n\n#### Consequences\n- 部署简单，和 HTTP 路由体系一致，适合单进程首发架构。\n- 活动流、任务进度和待处理提醒可以共享同一事件模型。\n- 长连接数量会上升，需要连接上限、心跳和回放窗口治理。\n\n### ADR-008：SQLite 作为最小模式默认存储\n\n#### Context\nKIVO 需要一个外部用户开箱即用的默认存储方案，既要支持结构化查询、事务、版本追踪和迁移，又不能要求用户先部署独立数据库。\n\n#### Decision\n最小模式默认使用 SQLite 承载 Knowledge Entry、Research Task、Rule Entry、审计日志和迁移状态；文件系统继续承载原始导入内容、导出包和大体积 artifact。后续如需升级，可通过 Storage SPI 切换到更强的关系存储。\n\n#### Consequences\n- 安装成本低，备份和迁移简单，符合 standalone 路径。\n- 单机事务和 schema migration 能力足够覆盖首发需求。\n- 高并发写入、超大数据集和多实例共享访问会受到限制，需要在扩展模式下替换实现。\n\n### ADR-009：术语条目复用 Knowledge Entry\n\n#### Context\n术语域需要定义术语、别名、正例、负例和适用域。如果单独设计一套完全不同的主模型，检索、版本、权限和活动流又会重复一遍。\n\n#### Decision\n术语条目沿用 Knowledge Entry 作为主对象，类型仍归入统一模型，通过 `domain=H` 与 `metadata.terminology` 扩展保存别名、禁用表述、正负例和注入范围。\n\n#### Consequences\n- 术语可以直接复用版本管理、冲突治理、权限裁剪和审计链路。\n- 意图增强、检索和 Prompt 注入都能共享同一条读取路径。\n- `metadata` 子 schema 需要更严格校验，避免把术语专属字段污染到其他知识域。\n\n### ADR-010：Workbench 前端采用 React + Vite + Zustand\n\n#### Context\nWorkbench 需要同时承载列表检索、活动流、图谱浏览、审核队列和调研管理，交互密度高，页面状态跨度大，还要兼顾 standalone 与嵌入模式的快速交付。\n\n#### Decision\nWorkbench 前端采用 React 作为 UI 框架，Vite 作为构建工具，Zustand 作为客户端状态管理层。路由、数据获取和可视化库保持可替换，但默认围绕这三项搭建首发工程骨架。\n\n#### Consequences\n- React 生态成熟，适合快速搭建高交互工作台和组件化审核界面。\n- Vite 冷启动快、构建简单，适合插件内开发和外部用户本地启动。\n- Zustand 适合活动流、筛选条件、当前条目、图谱视图这类局部共享状态，复杂度低于重型全局状态框架。\n- 若后续出现更强的离线协同或复杂缓存一致性需求，需要在数据层增加更稳的查询缓存与同步机制。\n\n---\n\n## 10. 质量要求（Quality Requirements）\n\n### 10.1 质量树\n\n#### 一致性（最高优先级）\n- 所有写入路径进入统一冲突治理。\n- 版本关系可追溯。\n- 条目状态流转可审计。\n\n#### 检索有效性\n- 检索命中率稳定。\n- 检索结果可解释，含来源、类型、相关度和版本语义。\n- Provider 降级时仍能返回可用结果。\n\n#### 宿主解耦\n- 核心逻辑不依赖私有宿主 API。\n- 存储与检索引擎可替换。\n- 宿主能力变化后系统进入可解释降级。\n\n#### 可治理性\n- 活动流、审计日志、指标和导出能力完整。\n- 用户能直接处理 pending、冲突、缺口和失败分发。\n\n#### 开箱即用\n- 安装、初始化、首次导入与首次检索可在短时间内跑通。\n- 最小运行模式成立。\n- 错误提示给出恢复动作。\n\n#### 安全与权限\n- 域级访问控制可靠。\n- 敏感知识不会越域泄露。\n- 调研任务遵守授权范围。\n\n### 10.2 质量场景\n\n#### QS-01：知识检索性能（对应 NFR-5.1）\n- 刺激：Agent 在 1000 条知识规模下发起语义检索。\n- 环境：正常 Provider 可用，标准单机环境。\n- 期望响应：P95 响应时间不超过 2 秒。\n- 验证点：包含检索耗时、排序阶段耗时和上下文打包耗时。\n\n#### QS-02：异步提取不阻塞主任务（对应 NFR-5.2）\n- 刺激：用户上传一份长文档，同时 Agent 继续处理对话任务。\n- 环境：文档需要分段提取。\n- 期望响应：提取在后台异步执行，前台任务不中断。\n- 验证点：上传请求快速返回任务状态，活动流持续更新进度。\n\n#### QS-03：规则分发时效（对应 NFR-5.3）\n- 刺激：管理员更新一条高优先级规则。\n- 环境：目标 Agent 已订阅相关 scope。\n- 期望响应：30 秒内目标 Agent 可通过主动拉取或被动推送获取新版本。\n- 验证点：Distribution Ledger 可看到送达与确认时间。\n\n#### QS-04：图谱增量更新（对应 NFR-5.4）\n- 刺激：一条新知识入库并建立两条关联。\n- 环境：图谱已有 1000 节点规模。\n- 期望响应：5 秒内图谱查询可见新节点和新边。\n- 验证点：Workbench 图谱与 Insight API 一致。\n\n#### QS-05：冲突检测无绕过（对应 NFR-5.7）\n- 刺激：分别从手工录入、文档导入、调研回流三条路径写入相互矛盾内容。\n- 环境：存在同一主题的 active 条目。\n- 期望响应：三条路径都生成候选冲突对，且不会直接静默覆盖旧条目。\n- 验证点：Conflict Record 与审计日志完整。\n\n#### QS-06：Provider 不可用时的降级（对应 NFR-5.19、FR-B04 AC4）\n- 刺激：Embedding Provider 故障。\n- 环境：文本 LLM 仍可用，或文本 LLM 也短暂不可用。\n- 期望响应：系统继续支持元数据过滤或关键词检索，并明确返回降级状态。\n- 验证点：API 响应带降级标记，Workbench 显示恢复提示。\n\n#### QS-07：域级权限保护（对应 NFR-5.14）\n- 刺激：低权限调用方请求一个高敏感知识域中的条目。\n- 环境：查询文本与敏感条目高度相关。\n- 期望响应：结果中不返回该域条目，也不在摘要、术语和活动流里泄露相关内容。\n- 验证点：权限裁剪发生在排序前，日志中只记录拒绝原因，不暴露正文。\n\n#### QS-08：首次知识旅程（对应 FR-Z06、NFR-5.21/5.22）\n- 刺激：外部陌生用户首次打开空库环境。\n- 环境：最小运行模式已安装完成。\n- 期望响应：用户能在 10 分钟内完成“导入一条知识 → 在列表里看到 → 再次检索命中”。\n- 验证点：引导入口清晰，空状态页有下一步动作，内部链接无 basePath 错误。\n\n#### QS-09：审计可追溯性（对应 AC-5.4）\n- 刺激：用户查看某条 active 条目的来龙去脉。\n- 环境：条目经历过提取、冲突裁决和一次 supersede。\n- 期望响应：系统能展示来源、artifact、版本、冲突记录、裁决结论和活动流事件。\n- 验证点：从详情页可以跳转到完整链路。\n\n#### QS-10：图谱可视化交互（对应 NFR-5.23、AC-5.5）\n- 刺激：用户在 1000 节点、3000 边规模下缩放、拖拽和聚焦图谱。\n- 环境：标准桌面浏览器。\n- 期望响应：交互帧率不低于 30fps，洞察标记可见，点击节点后详情卡片可在可接受延迟内出现。\n- 验证点：前端性能采样与用户感知一致。\n\n#### QS-11：Workbench 首屏加载性能（对应 NFR-5.5）\n- 刺激：用户首次或日常打开 Workbench 首页。\n- 环境：标准网络环境、冷启动浏览器缓存缺失、最小模式单机部署。\n- 期望响应：P95 首屏加载时间不超过 3 秒，首屏骨架与关键导航在可交互前稳定呈现。\n- 验证点：同时记录 HTML 首包时间、关键静态资源加载、首个可交互时间和首屏 API 聚合耗时。\n\n---\n\n## 11. 风险与技术债务（Risks and Technical Debt）\n\n### 11.1 已知风险\n\n#### 风险 1：LLM 语义判断漂移\n冲突精判、意图消歧和结构化提取高度依赖模型输出稳定性。模型升级或 Provider 切换后，知识质量可能出现隐性漂移。\n\n#### 风险 2：单进程运行时的容量上限\n首发采用单进程 Node.js 运行时，适合最小闭环，但在高并发检索、长时间活动流连接和大规模图谱计算下会逼近内存与事件循环瓶颈。\n\n#### 风险 3：来源质量参差不齐\n网页抓取、用户手工录入、对话提取和外部调研回流的可信度差异明显。若来源权重策略不够严格，active 区会积累低价值内容。\n\n#### 风险 4：权限规则与域边界复杂化\n随着知识域增多、角色变多、团队协作场景出现，域级权限映射会变得更复杂，静态配置方式可能难以持续维护。\n\n#### 风险 5：图谱洞察误报\n孤立节点、桥接节点和意外关联的算法结果具备启发价值，但不天然等于业务价值。误报会把调研资源带偏。\n\n#### 风险 6：SSE 长连接数量逼近单进程上限\nWorkbench 的活动流、导入进度和调研状态都依赖 SSE。用户数增加后，长连接、重连风暴和事件回放窗口可能挤占单进程内存与事件循环预算。\n\n### 11.2 技术债务\n\n#### 债务 1：最小模式下的本地存储扩展性有限\n本地文件系统与轻量存储足够支持早期，但在版本历史、artifact 和图谱缓存不断增长后，需要引入更清楚的冷热分层和索引治理。\n\n#### 债务 2：关键词降级路径质量偏弱\n没有 embedding 时，系统仍可运行，但复杂查询、跨术语同义表达和隐含关系识别能力会明显下降，需要后续强化混合检索策略。\n\n#### 债务 3：规则确认机制依赖宿主能力\n当前规则分发确认高度依赖宿主事件通道。若宿主缺少稳定 ACK 机制，Distribution Ledger 的准确性会受到影响。\n\n#### 债务 4：Analysis Artifact 审核体验仍需打磨\n两段式提取提升了质量，但也给用户增加了审核负担。若 Workbench 中的候选项聚合和批量确认体验不够顺手，用户会倾向跳过审核。\n\n#### 债务 5：认证生命周期目前偏轻量\nWeb 侧身份模型先支持轻量登录与操作审计，后续团队协作、会话管理、角色分配和多租户边界还需要补齐更扎实的实现。\n\n### 11.3 风险应对方向\n\n- 对提取、冲突判定和检索质量建立回归样本集，持续比较不同 Provider 的输出偏差。\n- 给单进程运行时预留分层缓存、后台作业隔离和存储 SPI 替换路径。\n- 强化来源权重策略，把“可追溯来源”作为 active 的硬门槛之一。\n- 在域级权限之上逐步引入更细粒度的角色配置与审计视图。\n- 对图谱洞察结果增加人工确认与采纳反馈闭环，减少误报对调研资源的影响。\n\n---\n\n## 12. 术语表（Glossary）\n\n### Knowledge Entry\nKIVO 管理的最小知识单元，一条条目表达一个可独立判断的知识断言。\n\n### Knowledge Type\n知识类型枚举：fact、methodology、decision、experience、intent、meta。\n\n### Source Reference\n来源引用，指向对话、文件、URL、规则文件或调研结果中的原始出处。\n\n### Analysis Artifact\n分析中间产物，保存提取阶段产生的断言候选、实体候选、冲突候选和缺口候选。\n\n### Conflict Record\n冲突记录，描述两个或多个知识条目之间的语义矛盾、裁决过程和结论。\n\n### Research Task\n调研任务，由缺口检测或人工触发产生，包含目标、范围、预算和状态。\n\n### Research Queue\n调研队列，承载待执行、执行中、待回写和失败待重试的调研任务，可区分 active 与 silent 两种运行模式。\n\n### Knowledge Graph\n知识图谱，基于 Knowledge Entry 之间的关系形成的网络结构，用于关联浏览、洞察计算、缺口检测和 Workbench 可视化探索。\n\n### Gap Report\n缺口报告，记录知识库盲区和补齐建议。\n\n### Rule Entry\n规则条目，描述 Agent 在特定范围内必须遵守的约束。\n\n### Subscription\n订阅关系，定义哪个 Agent、角色或场景需要接收哪组规则。\n\n### Distribution Record\n分发记录，记录规则被发送给谁、发送到哪个版本、是否确认成功。\n\n### Domain Purpose\n知识域目标声明，定义某个知识域的目标、关键问题、非目标和研究边界。\n\n### Intent Routing\n意图路由，指查询进入 KIVO 后，系统决定查询域、检索策略和澄清策略的过程。\n\n### Context Injection\n上下文注入，指把与当前任务相关的知识条目和术语压缩成可直接放入 Agent prompt 的上下文包。\n\n### Terminology Registry\n术语注册表，保存术语定义、约束、正例、负例、别名与适用域。\n\n### Capability Registry\n能力注册表，记录宿主或 Provider 当前可提供的能力及其版本约束。\n\n### Host Adapter\n宿主适配层，把 OpenClaw 或其他宿主的底层能力转成 KIVO Core 可消费的稳定接口。\n\n### Pending Queue\n待确认队列，承载低置信条目、低置信 artifact 或待补判冲突。\n\n### Superseded\n被新版本替代的状态。旧条目仍可追踪，但不再是默认返回结果。\n\n### Deprecated\n已废弃状态，表示条目不再建议使用，但在清理周期内仍保留历史记录。\n\n### Archived\n归档状态，表示条目退出主检索范围，只保留追溯价值。\n\nFile v1.2.3:docs/architecture/arc42-architecture.md\n\n# KIVO — arc42 架构文档\n\nOpenClaw（sa-01 子Agent）| 2026-04-19\n\n---\n\n## 目录\n\n1. Introduction and Goals\n2. Architecture Constraints\n3. System Scope and Context\n4. Solution Strategy\n5. Building Block View\n6. Runtime View\n7. Deployment View\n8. Cross-cutting Concepts\n9. Architecture Decisions\n10. Quality Requirements\n11. Risks and Technical Debt\n12. Glossary\n\n---\n\n## 1. Introduction and Goals\n\n### 1.1 系统目标\n\nKIVO（Knowledge Iteration & Vibe Orchestration）是 Agent 知识平台，Self-Evolving Harness 的认知基础设施。核心使命：让 Agent 从被动接收知识变成主动获取、结构化存储、持续迭代知识。\n\n系统解决三个根本问题：\n\n1. 知识散落——Agent 的知识分布在对话、记忆文件、配置和临时笔记中，没有统一结构。\n2. 知识静态——用户投喂什么 Agent 就知道什么，不投喂就是盲区。\n3. 知识矛盾——新旧知识共存时没有显式冲突解决机制，导致 Agent 行为不一致。\n\n### 1.2 关键质量需求\n\n| 优先级 | 质量属性 | 目标 |\n|--------|----------|------|\n| 1 | 一致性 | 知识冲突解决率 100%，不允许矛盾共存 |\n| 2 | 检索效能 | 知识检索命中率 ≥ 85%，P95 响应 ≤ 2s |\n| 3 | 自主性 | 缺口检测覆盖率 ≥ 70%，调研闭环自动化 |\n| 4 | 解耦性 | 核心逻辑与宿主环境解耦，存储/检索引擎可替换 |\n| 5 | 可扩展性 | 知识类型、信息源、规则分发机制均可扩展 |\n\n### 1.3 利益相关者\n\n| 角色 | 关注点 |\n|------|--------|\n| Solo Founder / 独立产品操盘者 | Agent 记住历史决策和经验，自主调研行业动态 |\n| Agent 开发者 | 统一知识管理接口，跨 Agent 知识共享不污染 |\n| 系统管理员 | 知识库健康状态可观测，访问控制可管理 |\n| SEVO（研发流水线） | 消费 KIVO 的知识支撑 Spec 编写和 Review |\n| AEO（效果度量） | 效果漂移时触发 KIVO 缺口检测排查知识缺失 |\n| 宿主环境 | 提供运行时、工具能力，调用 KIVO 接口 |\n\n---\n\n## 2. Architecture Constraints\n\n### 2.1 技术约束\n\n| 约束 | 原因 |\n|------|------|\n| 存储格式和检索接口与具体向量数据库解耦 | 宿主环境差异大，不能绑定特定数据库 |\n| 知识提取异步执行，不阻塞 Agent 主任务 | NFR-4.2，提取是 IO 密集操作 |\n| 规则分发采用拉取优先、推送补充策略 | 降低分发基础设施复杂度，Agent 启动时自行拉取 |\n| 调研任务由 KIVO 定义、宿主执行 | KIVO 不直接持有网络访问和工具能力 |\n| 知识条目写入必须经过冲突检测，无绕过路径 | NFR-4.5，一致性是第一优先级 |\n\n### 2.2 组织约束\n\n| 约束 | 原因 |\n|------|------|\n| 知识库规模初期控制在万级条目 | 初期验证阶段，避免过早优化 |\n| KIVO 不替代 SEVO 做流程编排 | Self-Evolving Harness 模块职责分离 |\n| KIVO 不替代 AEO 做效果度量 | 同上 |\n| 核心逻辑不写死对 OpenClaw 的依赖 | 通用知识管理语义，宿主做运行时适配 |\n\n### 2.3 惯例\n\n- 知识先结构化再存储，不存原始文本堆。\n- 所有知识条目必须有来源引用，支持溯源。\n- 冲突必须显式解决，不允许新旧矛盾共存。\n- 六类知识类型：fact、methodology、decision、experience、intent、meta。\n\n---\n\n## 3. System Scope and Context\n\n### 3.1 业务上下文\n\n```\n┌─────────────────────────────────────────────────────┐\n│ 宿主环境 │\n│ │\n│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │\n│ │ Agent A │ │ Agent B │ │ Agent C │ │\n│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │\n│ │ │ │ │\n│ └───────────────┼───────────────┘ │\n│ │ │\n│ ┌────────▼────────┐ │\n│ │ KIVO │ │\n│ │ 知识平台 │ │\n│ └────────┬────────┘ │\n│ │ │\n│ ┌───────────────┼───────────────┐ │\n│ │ │ │ │\n│ ┌────▼─────┐ ┌────▼─────┐ ┌────▼─────┐ │\n│ │ SEVO │ │ AEO │ │ Claw │ │\n│ │ 研发流水线 │ │ 效果度量 │ │ Design │ │\n│ └──────────┘ └──────────┘ └──────────┘ │\n└─────────────────────────────────────────────────────┘\n\n外部信息源：Web Search / 文档 / 论文 / 规则文件\n```\n\n业务交互：\n\n- Agent → KIVO：知识检索请求、对话记录（供提取）、规则查询。\n- KIVO → Agent：检索结果（含上下文注入）、规则推送、消歧建议。\n- KIVO → 宿主：调研任务定义（宿主负责执行并返回结果）。\n- SEVO → KIVO：查询历史规格、方法论、经验。\n- AEO → KIVO：触发缺口检测（效果漂移时排查知识缺失）。\n\n### 3.2 技术上下文\n\n```\n┌─────────────────────────────────────────────────┐\n│ KIVO 系统边界 │\n│ │\n│ ┌─────────────────────────────────────────┐ │\n│ │ KIVO Core API │ │\n│ │ (知识提取/存储/检索/冲突/调研/分发) │ │\n│ └──────────────┬──────────────────────────┘ │\n│ │ │\n│ ┌──────────────▼──────────────────────────┐ │\n│ │ Storage Abstraction Layer │ │\n│ │ (知识条目 CRUD / 版本 / 关联 / 索引) │ │\n│ └──────────────┬──────────────────────────┘ │\n│ │ │\n│ ┌──────────────▼──────────────────────────┐ │\n│ │ Storage Backend (可替换) │ │\n│ │ 本地文件 / SQLite / 向量DB / ... │ │\n│ └─────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────┘\n\n外部接口：\n ← Agent Runtime API（检索/注入/规则查询）\n ← Extraction Trigger（对话记录/文档/规则文件输入）\n → Research Task Output（调研任务定义，宿主执行）\n → Rule Distribution（规则推送/拉取）\n```\n\n### 3.3 Web 层业务上下文\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Web 层 │\n│ │\n│ ┌──────────┐ │\n│ │ 用户 │ 浏览器（桌面 1280px+） │\n│ │ (产品负责人│ │\n│ │ / 老板) │ │\n│ └────┬─────┘ │\n│ │ HTTP │\n│ ┌────▼──────────────────────────────────────────────────┐ │\n│ │ KIVO Web Frontend │ │\n│ │ 仪表盘 │ 知识列表 │ 搜索 │ 活动流 │ 调研 │ 字典 │ │\n│ └────┬──────────────────────────────────────────────────┘ │\n│ │ REST API │\n│ ┌────▼──────────────────────────────────────────────────┐ │\n│ │ KIVO Web API Layer │ │\n│ │ 聚合查询 │ 用户操作 │ 事件流 │ 字典 CRUD │ │\n│ └────┬──────────────────────────────────────────────────┘ │\n│ │ 内部调用 │\n│ ┌────▼──────────────────────────────────────────────────┐ │\n│ │ KIVO Core（引擎层） │ │\n│ │ 知识存储 │ 语义检索 │ 冲突检测 │ 调研 │ 规则分发 │ │\n│ └───────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n业务交互（Web 层新增）：\n\n- 用户 → Web Frontend：浏览知识库、搜索、查看详情、裁决冲突、触发调研、管理字典。\n- Web Frontend → Web API Layer：REST 请求（查询、操作、事件订阅）。\n- Web API Layer → KIVO Core：复用引擎已有接口（Knowledge Query API、Extraction Input、Research Task 等），不重复实现业务逻辑。\n- Web API Layer → 用户：界面内通知（调研完成、冲突待裁决等）。\n\n### 3.4 Web 层技术上下文\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Web 层系统边界 │\n│ │\n│ ┌─────────────────────────────────────────────────────┐ │\n│ │ KIVO Web Frontend (SPA) │ │\n│ │ React + Next.js App Router（ADR-009） │ │\n│ │ 页面：Dashboard / List / Search / Detail / │ │\n│ │ Activity / Conflicts / Research / Glossary │ │\n│ └──────────────────┬──────────────────────────────────┘ │\n│ │ HTTP REST (JSON) │\n│ ┌──────────────────▼──────────────────────────────────┐ │\n│ │ KIVO Web API Layer │ │\n│ │ /api/v1/knowledge/** (查询/筛选/详情) │ │\n│ │ /api/v1/search/** (语义搜索) │ │\n│ │ /api/v1/activity/** (活动流) │ │\n│ │ /api/v1/conflicts/** (冲突裁决) │ │\n│ │ /api/v1/research/** (调研任务) │ │\n│ │ /api/v1/glossary/** (系统字典) │ │\n│ │ /api/v1/dashboard/** (仪表盘聚合) │ │\n│ └──────────────────┬──────────────────────────────────┘ │\n│ │ 内部函数调用 │\n│ ┌──────────────────▼──────────────────────────────────┐ │\n│ │ KIVO Core API（引擎层，已有） │ │\n│ └─────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\nWeb 层技术接口清单：\n\n| 接口 | 方向 | 协议 | 说明 |\n|------|------|------|------|\n| Dashboard API | 入 | HTTP REST | 仪表盘聚合数据（FR-G01） |\n| Knowledge List API | 入 | HTTP REST | 知识条目列表/筛选/分页（FR-G02） |\n| Search API | 入 | HTTP REST | 语义搜索（FR-G03），代理到引擎 Knowledge Query API |\n| Knowledge Detail API | 入 | HTTP REST | 条目详情+关联+版本历史（FR-G04） |\n| Activity Feed API | 入 | HTTP REST / SSE | 活动流事件（FR-H01） |\n| Conflict Resolution API | 入 | HTTP REST | 冲突裁决操作（FR-H02） |\n| Pending Review API | 入 | HTTP REST | 待确认条目审核（FR-H02, FR-J02） |\n| Research Queue API | 入 | HTTP REST | 调研队列查看/创建/管理（FR-I01, FR-J01, FR-J03） |\n| Gap Report API | 入 | HTTP REST | 缺口报告查看（FR-I02） |\n| Knowledge Action API | 入 | HTTP REST | 知识标记/编辑操作（FR-J02） |\n| Glossary CRUD API | 入 | HTTP REST | 系统字典增删改查（FR-L01） |\n\n引擎层技术接口清单（已有，保持不变）：\n\n技术接口清单：\n\n| 接口 | 方向 | 协议 | 说明 |\n|------|------|------|------|\n| Knowledge Query API | 入 | 函数调用 / HTTP | Agent 检索知识 |\n| Context Injection API | 入 | 函数调用 | Agent 请求上下文注入 |\n| Extraction Input | 入 | 事件 / 函数调用 | 对话记录、文档、规则文件输入 |\n| Rule Query API | 入 | 函数调用 / HTTP | Agent 查询/订阅规则 |\n| Research Task Output | 出 | 事件 | 调研任务定义输出给宿主 |\n| Rule Push | 出 | 事件 / Webhook | 高优先级规则变更通知 |\n| Storage Backend SPI | 内 | 接口抽象 | 存储层可替换实现 |\n\n核心接口契约：\n\n```typescript\n// Knowledge Query API\ninterface KnowledgeQueryRequest {\n query: string; // 语义查询文本\n filters?: {\n types?: KnowledgeType[]; // 按知识类型过滤\n domain?: string; // 按域过滤\n timeRange?: { from?: Date; to?: Date };\n sources?: string[]; // 按来源过滤\n };\n topK?: number; // 返回条数，默认 10\n minScore?: number; // 最低相关度阈值，默认 0.6\n callerRole: string; // 调用方角色，用于访问控制\n}\n\ninterface KnowledgeQueryResponse {\n results: Array<{\n entry: KnowledgeEntry;\n score: number; // 语义相关度评分 0-1\n summary: string; // 内容摘要\n sourceRef: SourceReference;\n }>;\n totalMatches: number;\n degraded: boolean; // 是否降级返回（如 Embedding 不可用时回退元数据过滤）\n}\n\n// Context Injection API\ninterface ContextInjectionRequest {\n userQuery: string; // 用户原始请求\n tokenBudget: number; // 注入内容的 token 上限\n callerRole: string;\n preferredTypes?: KnowledgeType[]; // 优先注入的知识类型\n}\n\ninterface ContextInjectionResponse {\n injectedContext: string; // 拼装后的知识摘要文本\n entries: Array<{ // 注入涉及的条目明细\n entryId: string;\n type: KnowledgeType;\n summary: string;\n sourceRef: SourceReference;\n }>;\n tokensUsed: number; // 实际使用的 token 数\n truncated: boolean; // 是否因预算裁剪了结果\n}\n\n// Extraction Input\ninterface ExtractionInput {\n source: 'dialog' | 'document' | 'rule_file';\n idempotencyKey: string; // 幂等键，相同 key 重复提交跳过提取\n payload: DialogPayload | DocumentPayload | RuleFilePayload;\n}\n\ninterface DialogPayload {\n sessionId: string;\n messages: Array<{ role: string; content: string; timestamp: Date }>;\n}\n\ninterface DocumentPayload {\n path: string; // 文档路径或 URL\n format: 'markdown' | 'html' | 'text';\n content: string;\n}\n\ninterface RuleFilePayload {\n path: string;\n content: string;\n}\n\n// Extraction Output (内部事件)\ninterface ExtractionResult {\n idempotencyKey: string;\n entries: KnowledgeEntry[]; // 提取出的知识条目\n skipped: boolean; // 幂等键命中时为 true\n}\n```\n\n---\n\n## 4. Solution Strategy\n\n### 4.1 关键架构决策\n\n| 决策 | 选择 | 理由 |\n|------|------|------|\n| 知识管线架构 | 管道-过滤器（Pipeline-Filter） | 提取→冲突检测→合并→入库，每步独立可测试可替换 |\n| 存储抽象 | Repository 模式 + SPI | 上层逻辑不感知具体存储引擎，初期用本地文件/SQLite，后续可换向量 DB |\n| 冲突检测策略 | 写入前置拦截，零绕过 | 一致性是第一优先级，所有写入路径必须经过冲突检测 |\n| 检索策略 | 语义检索 + 元数据过滤 | 语义相似度为主，知识类型/时间/来源为辅助过滤维度 |\n| 规则分发 | 拉取优先 + 事件补充 | Agent 启动时拉取全量规则，变更时事件通知增量更新 |\n| 调研执行 | 任务定义与执行分离 | KIVO 定义调研任务（目标/范围/策略/预算），宿主环境负责执行 |\n| 知识类型体系 | 固定六类 + 扩展机制 | fact/methodology/decision/experience/intent/meta 覆盖核心场景，新类型通过注册扩展 |\n| 异步提取 | 事件驱动 + 队列 | 提取不阻塞 Agent 主任务，通过事件触发异步处理 |\n\n### 4.2 技术选型方向\n\n| 层次 | 选型方向 | 说明 |\n|------|----------|------|\n| 语言 | TypeScript | 静态类型系统保障大规模重构安全性，async/await 原生支持 IO 密集的提取和检索管线，npm 生态覆盖 Embedding、SQLite、JSON Schema 等核心依赖，宿主适配层可选其他语言 |\n| 存储 | SQLite（单一真相源）+ JSON 导出视图 | 万级条目规模足够，SQLite 事务保证原子性，JSON 仅作调试/审查用途 |\n| 语义检索 | Embedding API（宿主提供）+ 余弦相似度 | 检索引擎通过 SPI 抽象，不绑定特定 Embedding 模型 |\n| 事件机制 | EventEmitter / 简单消息队列 | 初期单进程内事件，后续可升级为跨进程消息 |\n| 接口协议 | TypeScript 函数调用 | 初期同进程调用，预留 HTTP API 扩展点 |\n\n---\n\n## 5. Building Block View\n\n### 5.1 Level 1：系统分解\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ KIVO Core │\n│ │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │\n│ │ Extraction │ │ Knowledge │ │ Iteration │ │\n│ │ Engine │ │ Store │ │ Engine │ │\n│ │ (域 A) │ │ (域 B) │ │ (域 C) │ │\n│ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │\n│ │ │ │ │\n│ ┌──────▼──────────────────────────────────────▼──────────┐ │\n│ │ Knowledge Pipeline Bus │ │\n│ │ (事件总线：提取→检测→解决→入库) │ │\n│ └──────┬──────────────────────────────────────┬──────────┘ │\n│ │ │ │\n│ ┌──────▼──────┐ ┌─────────────┐ ┌──────────▼──────────┐ │\n│ │ Research │ │ Intent │ │ Rule │ │\n│ │ Planner │ │ Enhancer │ │ Distributor │ │\n│ │ (域 D) │ │ (域 E) │ │ (域 F) │ │\n│ └─────────────┘ └─────────────┘ └─────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────┐│\n│ │ Storage Abstraction Layer (SPI) ││\n│ └─────────────────────────────────────────────────────────┘│\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 5.2 模块职责\n\n#### Extraction Engine（域 A）\n\n职责：从各类来源提取结构化知识条目。\n\n| 子模块 | 职责 | 对应 FR |\n|--------|------|---------|\n| DialogExtractor | 从 Agent 对话中提取六类知识 | FR-A01 |\n| DocumentExtractor | 从 Markdown/PDF/网页提取知识 | FR-A02 |\n| RuleExtractor | 从治理文件提取可分发规则 | FR-A03 |\n\n输入：原始对话记录、文档内容、规则文件。\n输出：结构化 Knowledge Entry（含类型、内容、来源、置信度）。\n约束：提取异步执行，不阻塞 Agent 主任务。低置信度结果标记 pending。\n\n#### Knowledge Store（域 B）\n\n职责：知识的持久化存储、版本管理、语义检索和关联维护。\n\n| 子模块 | 职责 | 对应 FR |\n|--------|------|---------|\n| EntryRepository | 知识条目 CRUD、版本追踪、状态管理 | FR-B01 |\n| SemanticIndex | 语义向量索引、相似度检索 | FR-B02 |\n| RelationGraph | 知识关联关系维护（supplements/supersedes/conflicts/depends_on） | FR-B03（完整实现，初期先支持 conflicts + supersedes） |\n\n输入：经过冲突检测的 Knowledge Entry。\n输出：检索结果（含相关度评分）、关联图谱。\n约束：所有写入必须经过 Iteration Engine 的冲突检测，EntryRepository 不接受直接写入。\n\n#### Iteration Engine（域 C）\n\n职责：知识更新的一致性守门人——冲突检测、冲突解决、过期清理、知识合并。\n\n| 子模块 | 职责 | 对应 FR |\n|--------|------|---------|\n| ConflictDetector | 语义冲突和规则冲突检测 | FR-C01 |\n| ConflictResolver | 冲突解决策略执行（时间优先/来源优先/人工裁决） | FR-C01 |\n| ExpiryScanner | 过时知识识别和清理 | FR-C02 |\n| MergeEngine | 同主题互补知识合并 | FR-C03 |\n\n输入：待入库的 Knowledge Entry + 已有知识库。\n输出：冲突记录、解决结论、合并结果。\n约束：冲突检测覆盖所有写入路径，零绕过。冲突解决过程和结论必须记录。\n\n#### Research Planner（域 D）\n\n职责：发现知识缺口，生成调研任务定义。\n\n| 子模块 | 职责 | 对应 FR |\n|--------|------|---------|\n| GapDetector | 基于查询未命中和关联缺失识别盲区 | FR-D01 |\n| TaskGenerator | 生成结构化调研任务（目标/范围/策略/预算） | FR-D02 |\n| PriorityScheduler | 调研优先级排序和执行节奏控制 | FR-D03 |\n\n输入：查询未命中记录、知识关联结构缺失。\n输出：Research Task 定义（交给宿主执行）。\n约束：调研不抢占用户主动任务资源，有预算上限。\n\n#### Intent Enhancer（域 E）\n\n职责：利用知识库提升 Agent 对用户意图的理解。\n\n| 子模块 | 职责 | 对应 FR |\n|--------|------|---------|\n| ContextInjector | 按 token 预算注入相关知识 | FR-E01 |\n| Disambiguator | 基于历史知识消解意图歧义 | FR-E02 |\n\n输入：Agent 的用户请求 + token 预算。\n输出：增强后的上下文（知识摘要 + 来源标注）、消歧建议。\n约束：注入不改变用户原始请求，对用户透明。\n\n#### Rule Distributor（域 F）\n\n职责：规则的注册、订阅管理和按需分发。\n\n| 子模块 | 职责 | 对应 FR |\n|--------|------|---------|\n| RuleRegistry | 规则条目注册、版本管理、优先级管理 | FR-F01 |\n| SubscriptionManager | Agent 订阅关系维护 | FR-F02 |\n| PushEngine | 规则变更推送和分发确认 | FR-F03 |\n\n输入：规则变更事件、Agent 订阅请求。\n输出：规则推送、分发记录。\n约束：拉取优先，推送补充。分发失败自动重试。\n\n#### Knowledge Pipeline Bus\n\n职责：连接各域模块的事件总线，驱动知识管线流转。\n\n核心事件链：\n\n- 提取完成事件 → 触发冲突检测。\n- 冲突解决完成事件 → 触发入库。\n- 查询未命中事件 → 累积供缺口检测分析。\n\n扩展事件链：\n\n- 冲突解决完成事件 → 触发合并检测（MergeEngine）。无冲突的同主题条目由 MergeEngine 判定是否语义互补可合并，合并完成后再触发入库。\n- 入库完成事件 → 触发缺口检测（GapDetector）。\n\n#### Storage Abstraction Layer（SPI）\n\n职责：屏蔽底层存储差异，提供统一的知识条目持久化接口。\n\n初期实现：本地 JSON 文件 + SQLite 元数据索引。\n\n一致性策略：SQLite 为单一真相源。知识条目的元数据、状态、索引和内容引用全部先落 SQLite，在同一事务内完成。JSON 文件作为可重建的导出视图，用于调试和人工审查，不作为主存储。写入流程：开启 SQLite 事务 → 写入条目元数据 + 内容 + 冲突记录 → 更新 FTS 索引 → 提交事务 → 异步写出 JSON 导出文件。事务失败时自动回滚，JSON 导出失败不影响数据一致性。\n扩展方向：向量数据库（Chroma/Qdrant/Milvus）、PostgreSQL + pgvector。\n\nSPI 接口：\n\n- `save(entry: KnowledgeEntry): Promise`\n- `findById(id: string): Promise`\n- `search(query: SemanticQuery): Promise`\n- `updateStatus(id: string, status: EntryStatus): Promise`\n- `getVersionHistory(id: string): Promise`\n\n### 5.3 Web 层模块分解\n\nWeb 层是 KIVO Core 的用户可见层，不包含业务逻辑，只做聚合查询、用户操作代理和展示。\n\n#### 5.3.1 Web API Layer\n\n职责：为前端提供 HTTP REST 接口，将用户请求转译为 KIVO Core API 调用。\n\n| 端点组 | 方法 | 路径 | 对应 UFR | 说明 |\n|--------|------|------|---------|------|\n| Dashboard | GET | /api/v1/dashboard/summary | FR-G01 | 知识库总览聚合（类型分布、状态分布、趋势、健康指标） |\n| Knowledge | GET | /api/v1/knowledge | FR-G02 | 知识条目列表，支持 ?type=&status=&source=&from=&to=&sort=&page=&pageSize= |\n| Knowledge | GET | /api/v1/knowledge/:id | FR-G04 | 条目详情（含关联、版本历史） |\n| Knowledge | PATCH | /api/v1/knowledge/:id/status | FR-J02 | 标记过时 / 确认 / 拒绝 |\n| Knowledge | PUT | /api/v1/knowledge/:id/content | FR-J02 AC3 | 编辑摘要（生成新版本，新版本必须经过 ConflictDetector 冲突检测，与新增知识走同一条检测管线） |\n| Search | GET | /api/v1/search?q=&type=&status= | FR-G03 | 语义搜索，代理到引擎 Knowledge Query API |\n| Activity | GET | /api/v1/activity?type=&page= | FR-H01 | 活动流事件列表 |\n| Activity | GET | /api/v1/activity/stream | FR-H01 | SSE 实时事件推送 |\n| Conflicts | GET | /api/v1/conflicts?status=pending | FR-H02 | 待裁决冲突列表 |\n| Conflicts | POST | /api/v1/conflicts/:id/resolve | FR-H02 AC2 | 提交裁决结果 |\n| Research | GET | /api/v1/research/tasks | FR-I01 | 调研任务列表 |\n| Research | POST | /api/v1/research/tasks | FR-J01 | 手动创建调研任务 |\n| Research | PATCH | /api/v1/research/tasks/:id | FR-J03 | 取消/调整优先级 |\n| Research | PUT | /api/v1/research/auto | FR-J03 AC3 | 全局自动调研开关 |\n| Research | GET | /api/v1/research/gaps | FR-I02 | 缺口报告列表 |\n| Glossary | GET | /api/v1/glossary | FR-L01 AC1 | 字典列表，支持 ?q=&scope= |\n| Glossary | POST | /api/v1/glossary | FR-L01 AC2 | 新增术语 |\n| Glossary | PUT | /api/v1/glossary/:id | FR-L01 AC3 | 编辑术语 |\n| Glossary | DELETE | /api/v1/glossary/:id | FR-L01 AC3 | 删除术语 |\n\nAPI 设计原则：\n- 统一响应格式：`{ data, meta: { total, page, pageSize }, error }`\n- 分页默认 pageSize=20，最大 100\n- 错误码采用 HTTP 标准状态码 + 业务错误码（`error.code`）\n- 所有写操作返回更新后的完整对象（乐观更新支撑）\n\n#### 5.3.2 Web Frontend Components\n\n前端为 SPA，按页面拆分组件，每个页面对应一个或多个 UFR。\n\n| 页面/组件 | 对应 UFR | 核心功能 |\n|------------|---------|----------|\n| DashboardPage | FR-G01 | 知识类型分布图、状态分布、趋势图、健康指标卡片 |\n| KnowledgeListPage | FR-G02 | 条目列表 + 筛选栏 + 排序 + 分页 |\n| SearchPage | FR-G03 | 搜索框 + 结果列表（高亮片段、相关度分）+ 二次筛选 |\n| KnowledgeDetailPage | FR-G04 | 完整内容 + 关联图 + 版本时间线 + 来源引用 |\n| ActivityFeedPage | FR-H01 | 时间线事件列表 + 类型筛选 + SSE 实时更新 |\n| ConflictResolutionPage | FR-H02 | 冲突双方对比视图 + 裁决按钮 + pending 条目审核 |\n| ResearchQueuePage | FR-I01, FR-J01, FR-J03 | 调研任务列表 + 创建表单 + 优先级调整 + 全局开关 |\n| GapReportPage | FR-I02 | 缺口报告列表 + 影响面指标 + 填补进度 |\n| GlossaryPage | FR-L01 | 术语列表 + 搜索 + 新增/编辑/删除表单 |\n| AppShell | 全局 | 导航栏 + 通知中心 + 全局搜索入口 |\n\n前端状态管理：\n- 服务端状态（知识条目、调研任务等）通过 API 请求获取，不在前端缓存业务数据。\n- UI 状态（筛选条件、分页位置、展开/折叠）用组件局部状态或 URL query params。\n- 乐观更新：写操作先更新 UI，后台 API 失败时回滚并提示。\n\n#### 5.3.3 Web 层数据模型\n\nWeb 层不维护独立的业务数据存储。所有知识条目、冲突记录、调研任务的数据来自引擎层 Knowledge Store。\n\nWeb 层新增的数据实体：\n\n```typescript\n// 系统字典条目（FR-L01，Web 层独有）\ninterface GlossaryEntry {\n id: string;\n term: string; // 术语名称（必填）\n definition: string; // 定义说明（必填）\n aliases?: string[]; // 别名/同义词\n scope?: string; // 适用范围\n createdAt: Date;\n updatedAt: Date;\n}\n\n// 仪表盘聚合数据（API 层计算，不持久化）\ninterface DashboardSummary {\n totalEntries: number;\n byType: Record;\n byStatus: Record;\n trend7d: { date: string; added: number; updated: number; deprecated: number }[];\n health: {\n pendingCount: number;\n unresolvedConflicts: number;\n expiredPending: number;\n };\n}\n```\n\n与引擎层 Knowledge Store 的关系：\n- Web API Layer 通过引擎的 `EntryRepository`、`SemanticIndex`、`ConflictDetector` 等接口读写数据。\n- GlossaryEntry 存储在引擎层同一 SQLite 实例中（单独的 glossary 表），通过 Storage Abstraction Layer 访问。\n- DashboardSummary 是实时聚合计算结果，不持久化。\n\n#### 5.3.4 Web 层交付边界\n\n核心交付：\n\n| 组件/接口 | 说明 |\n|------------|------|\n| DashboardPage + GET /dashboard/summary | 知识库总览 |\n| KnowledgeListPage + GET /knowledge | 条目列表、筛选、分页 |\n| SearchPage + GET /search | 语义搜索 |\n| KnowledgeDetailPage + GET /knowledge/:id | 条目详情、关联、版本历史 |\n| ConflictResolutionPage + GET/POST /conflicts | 冲突列表与裁决 |\n| PATCH /knowledge/:id/status | 标记过时/确认/拒绝 |\n| PUT /knowledge/:id/content | 编辑摘要 |\n| AppShell（导航 + 全局搜索入口） | 全局布局 |\n\n后续扩展：\n\n| 组件/接口 | 说明 |\n|------------|------|\n| ActivityFeedPage + GET /activity/stream (SSE) | 实时活动流推送 |\n| ResearchQueuePage + 调研任务 CRUD | 调研任务管理 |\n| GapReportPage + GET /research/gaps | 缺口报告 |\n| GlossaryPage + Glossary CRUD | 系统字典管理 |\n| 通知中心 | 站内消息推送 |\n\n划分原则：初期覆盖知识浏览、搜索、冲突裁决这三条核心用户路径，其余功能随引擎层后续迭代同步激活。\n\n### 5.4 Skill 接口定义\n\nKIVO 对外暴露以下独立 Skill，每个 Skill 对应一个用户意图。宿主环境通过 Skill 名称路由用户请求到对应能力。\n\n#### 内置 Skill\n\n| Skill 名称 | 职责 | 触发条件 | 核心模块/入口 |\n|------------|------|----------|---------------|\n| KnowledgeIngestSkill | 从对话或文档中提取并存储结构化知识 | 用户说\"记住这个\"\"把这段话存下来\"\"从这篇文档提取知识\"\"学习这个文件\" | `src/extraction/` → `src/pipeline/engine.ts` → `src/conflict/` → `src/repository/` |\n| KnowledgeQuerySkill | 检索知识库并返回相关知识条目 | 用户说\"你知道关于 X 的什么\"\"查一下之前的决策\"\"有没有相关经验\"\"搜索知识库\" | `src/search/semantic-search.ts` → `src/repository/knowledge-repository.ts` |\n| ContextInjectSkill | 为当前任务自动注入相关知识上下文 | Agent 处理用户请求时自动触发（非用户直接调用），或用户说\"带上相关背景\"\"结合之前的知识回答\" | `src/injection/context-injector.ts` → `src/injection/injection-policy.ts` |\n| ConflictResolveSkill | 处理知识冲突的人工裁决请求 | 用户说\"这两条知识矛盾了，用新的\"\"保留旧的\"\"帮我决定哪个对\" | `src/conflict/conflict-resolver.ts` → `src/conflict/conflict-record.ts` |\n\n#### 扩展 Skill\n\n| Skill 名称 | 职责 | 触发条件 | 核心模块/入口 |\n|------------|------|----------|---------------|\n| ResearchSkill | 基于知识缺口生成并管理调研任务 | 用户说\"调研一下 X 领域\"\"补充关于 Y 的知识\"\"知识库缺什么\" | Research Planner（域 D）：GapDetector → TaskGenerator → PriorityScheduler |\n| RuleDistributeSkill | 管理系统规则的注册、订阅和分发 | 用户说\"更新规则\"\"给 Agent A 推送新规则\"\"查看当前订阅的规则\" | Rule Distributor（域 F）：RuleRegistry → SubscriptionManager → PushEngine |\n| KnowledgeHealthSkill | 报告知识库健康状态（过期、冲突、盲区统计） | 用户说\"知识库状态怎么样\"\"有多少过期知识\"\"健康报告\" | ExpiryScanner + GapDetector + EntryRepository 聚合查询 |\n\n#### Skill 间依赖关系\n\n```\nKnowledgeIngestSkill ──→ ConflictResolveSkill（入库时检测到冲突，触发裁决）\nKnowledgeQuerySkill ──→ ContextInjectSkill（检索结果可直接用于上下文注入）\nResearchSkill ──→ KnowledgeIngestSkill（调研结果回流入库）\nRuleDistributeSkill ──→ KnowledgeIngestSkill（规则提取复用提取管线）\nKnowledgeHealthSkill ──→ ResearchSkill（发现盲区后可触发调研）\n```\n\n#### Skill 路由契约\n\n每个 Skill 通过声明式契约注册能力，宿主的 SkillRouter 基于用户意图匹配对应 Skill：\n\n```yaml\n# 示例：KnowledgeIngestSkill 契约\nname: knowledge-ingest\ndescription: 从对话或文档中提取并存储结构化知识\ntriggers:\n - \"记住|存下来|提取知识|学习这个|保存到知识库\"\n - \"ingest|extract knowledge|remember this\"\ninput: ExtractionInput（对话记录或文档内容）\noutput: ExtractionResult（提取的知识条目列表）\n```\n\n---\n\n## 6. Runtime View\n\n### 6.1 场景一：对话知识提取与入库\n\n```\nAgent Extraction Pipeline Iteration Knowledge\nRuntime Engine Bus Engine Store\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- 提取异步执行，不阻塞 Agent 主任务。\n- 冲突检测是写入前置拦截，所有路径必须经过。\n- 冲突解决结论（Conflict Record）与知识条目一起持久化。\n\n### 6.2 场景二：Agent 知识检索与上下文注入\n\n```\nAgent Intent Knowledge Storage\nRuntime Enhancer Store Backend\n │ │ │ │\n │ 用户请求 │ │ │\n │ + token 预算 │ │ │\n ├───────────────►│ │ │\n │ │ 语义检索 │ │\n │ │─────────────►│ │\n │ │ │ 向量检索 │\n │ │ │───────────►│\n │ │ │◄───────────│\n │ │ │ 元数据过滤 │\n │ │ │──┐ │\n │ │ │◄─┘ │\n │ │◄─────────────│ │\n │ │ 按 token 预算 │ │\n │ │ 裁剪注入内容 │ │\n │ │──┐ │ │\n │ │◄─┘ │ │\n │ 增强上下文 │ │ │\n │ (知识摘要+来源) │ │ │\n │◄───────────────│ │ │\n │ │ │ │\n │ 继续处理用户请求 │ │ │\n │──┐ │ │ │\n │◄─┘ │ │ │\n```\n\n关键约束：\n- 检索 P95 响应 ≤ 2s。\n- 注入内容不超过调用方指定的 token 预算。\n- 注入对用户透明，不改变原始请求。\n\n### 6.3 场景三：知识冲突的人工裁决路径\n\n```\nAgent Iteration Knowledge 用户/\nRuntime Engine Store 管理员\n │ │ │ │\n │ (提取触发) │ │ │\n │───────────────►│ │ │\n │ │ 检测到冲突 │ │\n │ │ 自动策略无法 │ │\n │ │ 决定 │ │\n │ │──┐ │ │\n │ │◄─┘ │ │\n │ │ 标记 pending │ │\n │ │─────────────►│ │\n │ │ 生成裁决请求 │ │\n │ │─────────────────────────►│\n │ │ │ │ 人工裁决\n │ │ │ │──┐\n │ │ │ │◄─┘\n │ │◄─────────────────────────│\n │ │ 执行裁决结论 │ │\n │ │─────────────►│ │\n │ │ 更新状态 │ │\n │ │─────────────►│ │\n```\n\n### 6.4 场景四：规则变更与分发\n\n```\n规则文件 Extraction Rule Agent\n变更 Engine Distributor (订阅者)\n │ │ │ │\n │ 规则文件变更 │ │ │\n ├───────────────►│ │ │\n │ │ 提取规则条目 │ │\n │ │─────────────►│ │\n │ │ │ 更新规则版本 │\n │ │ │──┐ │\n │ │ │◄─┘ │\n │ │ │ 匹配订阅关系 │\n │ │ │──┐ │\n │ │ │◄─┘ │\n │ │ │ 推送通知 │\n │ │ │───────────►│\n │ │ │ │ 拉取最新规则\n │ │ │◄───────────│\n │ │ │ 返回规则 │\n │ │ │───────────►│\n │ │ │ 记录分发确认 │\n │ │ │──┐ │\n │ │ │◄─┘ │\n```\n\n### 6.5 核心路径总结\n\n系统聚焦四条核心运行时路径：\n\n1. 对话/文档 → 提取 → 冲突检测 → 入库（域 A + C + B）\n2. Agent 查询 → 语义检索 → 上下文注入（域 B + E）\n3. 冲突发生 → 自动解决或人工裁决 → 更新知识（域 C）\n4. 知识条目状态流转：pending → active → superseded/deprecated → archived\n\n交付边界（严格收口）：\n\n- 含：对话提取、文档提取（Markdown + 网页正文）、KnowledgeEntry 存储、基础语义检索、冲突检测、时间优先 + 人工裁决两种解决策略、Context Injection、最小审计日志。\n- 不含（后续迭代）：配置热加载（初期只做启动加载 + 手动 reload）、dead-letter 管理面、复杂访问控制（初期只做基础域隔离）、HTTP / Webhook / 推送接口、自动补建 Embedding 调度。\n\n域 D（自主调研）和域 F（规则分发）后续激活。域 E 的意图消歧后续激活，初期只做上下文注入。\n\n### 6.6 场景五：用户通过 Web 搜索知识（FR-G03）\n\n```\n用户 Web Frontend Web API KIVO Core Storage\n(浏览器) Layer (SemanticIndex) Backend\n │ │ │ │ │\n │ 输入搜索词 │ │ │ │\n ├──────────────►│ │ │ │\n │ │ GET /search │ │ │\n │ │ ?q=xxx │ │ │\n │ ├─────────────►│ │ │\n │ │ │ KnowledgeQuery│ │\n │ │ ├─────────────►│ │\n │ │ │ │ 向量检索 │\n │ │ │ ├─────────────►│\n │ │ │ │◄─────────────│\n │ │ │ │ 元数据过滤 │\n │ │ │ │──┐ │\n │ │ │ │◄─┘ │\n │ │ │◄─────────────│ │\n │ │ │ 拼装响应 │ │\n │ │ │ (高亮片段 │ │\n │ │ │ +相关度分) │ │\n │ │◄─────────────│ │ │\n │ │ 渲染搜索结果 │ │ │\n │◄──────────────│ │ │ │\n```\n\n关键约束：\n- Web API Layer 不做语义检索逻辑，直接代理到引擎 Knowledge Query API。\n- 高亮片段由 API Layer 基于检索结果的 score 和内容生成，不依赖引擎。\n- 端到端响应时间 ≤ 2s（复用引擎 NFR-4.1）。\n\n### 6.7 场景六：用户查看知识条目详情（FR-G04）\n\n```\n用户 Web Frontend Web API KIVO Core Storage\n(浏览器) Layer (EntryRepo + Backend\n │ │ │ RelationGraph)\n │ 点击条目 │ │ │ │\n ├──────────────►│ │ │ │\n │ │ GET │ │ │\n │ │ /knowledge/id│ │ │\n │ ├─────────────►│ │ │\n │ │ │ findById │ │\n │ │ ├─────────────►│ │\n │ │ │ ├─────────────►│\n │ │ │ │◄─────────────│\n │ │ │ getRelations │ │\n │ │ ├─────────────►│ │\n │ │ │ ├─────────────►│\n │ │ │ │◄─────────────│\n │ │ │ getVersions │ │\n │ │ ├─────────────►│ │\n │ │ │ ├─────────────►│\n │ │ │ │◄─────────────│\n │ │◄─────────────│ │ │\n │ │ 拼装详情页 │ │ │\n │ │ (内容+关联 │ │ │\n │ │ +版本历史) │ │ │\n │◄──────────────│ │ │ │\n```\n\n关键约束：\n- API Layer 并行调用 findById、getRelations、getVersionHistory 三个引擎接口，聚合后返回。\n- 关联知识只返回摘要，不递归展开。\n\n### 6.8 场景七：规则分发状态展示（FR-K03，Future）\n\n```\n用户 Web Frontend Web API Rule\n(浏览器) Layer Distributor\n │ │ │ │\n │ 打开规则页 │ │ │\n ├──────────────►│ │ │\n │ │ GET /rules │ │\n │ ├─────────────►│ │\n │ │ │ listRules │\n │ │ ├─────────────►│\n │ │ │ │ 查询规则列表\n │ │ │ │ + 订阅者数\n │ │ │ │ + 分发记录\n │ │ │◄─────────────│\n │ │◄─────────────│ │\n │ │ 渲染规则列表 │ │\n │ │ (生效规则 │ │\n │ │ +分发失败) │ │\n │◄──────────────│ │ │\n```\n\n### 6.9 场景八：系统字典变更实时生效（FR-L01）\n\n```\n用户 Web Frontend Web API KIVO Core Intent\n(浏览器) Layer (GlossaryStore) Enhancer\n │ │ │ │ │\n │ 新增/编辑术语 │ │ │ │\n ├──────────────►│ │ │ │\n │ │ POST/PUT │ │ │\n │ │ /glossary │ │ │\n │ ├─────────────►│ │ │\n │ │ │ upsertEntry │ │\n │ │ ├─────────────►│ │\n │ │ │ │ 写入 DB │\n │ │ │ │──┐ │\n │ │ │ │◄─┘ │\n │ │ │ │ │\n │ │ │ │ emit │\n │ │ │ │ GLOSSARY_ │\n │ │ │ │ CHANGED │\n │ │ │ ├─────────────►│\n │ │ │ │ │ 刷新本地\n │ │ │ │ │ 字典缓存\n │ │ │ │ │──┐\n │ │ │ │ │◄─┘\n │ │ │◄─────────────│ │\n │ │◄─────────────│ │ │\n │◄──────────────│ │ │ │\n```\n\n字典变更实时生效机制：\n\n- GlossaryStore 写入成功后，通过 Pipeline Bus 发布 `GLOSSARY_CHANGED` 事件（携带变更的术语 ID 和操作类型）。\n- Intent Enhancer（上下文注入模块）订阅该事件，收到后立即刷新本地字典缓存。\n- 已有会话的生效边界：下一次请求时生效。Intent Enhancer 在每次构建 session context 时从缓存读取字典，缓存已刷新则自动拿到新值。\n- 新会话初始化时自动加载全量字典到 session context。\n- 初期实现：进程内事件总线（同步通知）。后续多节点场景通过 SSE/WebSocket 广播。\n\n---\n\n## 7. Deployment View\n\n### 7.1 部署拓扑（单机）\n\n```\n┌─────────────────────────────────────────────────────┐\n│ 宿主机器（单节点） │\n│ │\n│ ┌───────────────────────────────────────────────┐ │\n│ │ 宿主运行时进程 │ │\n│ │ │ │\n│ │ ┌─────────────────────────────────────────┐ │ │\n│ │ │ KIVO Core（同进程库） │ │ │\n│ │ │ │ │ │\n│ │ │ Extraction Engine │ Iteration Engine │ │ │\n│ │ │ Knowledge Store │ Intent Enhancer │ │ │\n│ │ │ Pipeline Bus │ Storage Layer │ │ │\n│ │ └─────────┬───────────────────────────────┘ │ │\n│ │ │ │ │\n│ └────────────┼───────────────────────────────────┘ │\n│ │ │\n│ ┌────────────▼───────────────────────────────────┐ │\n│ │ 本地存储 │ │\n│ │ ./kivo-data/ │ │\n│ │ ├── entries/ (JSON 知识条目导出视图) │ │\n│ │ ├── conflicts/ (冲突记录导出) │ │\n│ │ ├── kivo.sqlite (主存储：条目+元数据+FTS索引) │ │\n│ │ └── embeddings/ (向量缓存) │ │\n│ └────────────────────────────────────────────────┘ │\n│ │\n│ ┌────────────────────────────────────────────────┐ │\n│ │ Embedding API（宿主提供或远程调用） │ │\n│ └────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────┘\n```\n\n部署特征：\n\n- KIVO 作为 TypeScript 库嵌入宿主运行时进程，零独立进程。\n- 存储以 SQLite 为单一真相源：知识条目元数据、内容、冲突记录、全文检索索引均落 SQLite。JSON 文件为可重建的导出视图，用于调试和人工审查。\n- Embedding 向量通过宿主提供的 API 生成，缓存到本地 embeddings/ 目录。\n- 单机部署，无网络端口暴露，无外部数据库依赖。\n\n#### Web 层部署拓扑\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 宿主机器（单节点） │\n│ │\n│ ┌───────────────────────────────────────────────────┐ │\n│ │ Web Frontend（静态资源） │ │\n│ │ 构建产物：HTML / CSS / JS bundle │ │\n│ │ 托管方式：同进程 HTTP 服务的 /static 路由 │ │\n│ └───────────────────────┬───────────────────────────┘ │\n│ │ HTTP (localhost) │\n│ ┌───────────────────────▼───────────────────────────┐ │\n│ │ Web API Layer（同进程模块） │ │\n│ │ Express/Fastify 路由层，监听 localhost:PORT │ │\n│ │ 职责：请求校验、聚合查询、写操作代理、SSE 推送 │ │\n│ └───────────────────────┬───────────────────────────┘ │\n│ │ 进程内函数调用 │\n│ ┌───────────────────────▼───────────────────────────┐ │\n│ │ KIVO Core（同进程库） │ │\n│ └───────────────────────┬───────────────────────────┘ │\n│ │ │\n│ ┌───────────────────────▼───────────────────────────┐ │\n│ │ 本地存储（SQLite + embeddings/） │ │\n│ └───────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\nWeb 层部署关键决策：\n\n- Web API Layer 与 KIVO Core 同进程，通过函数调用通信，无 IPC 开销。\n- 前端静态资源由同一 HTTP 服务托管（`/static` 或 `/` 路由），无需独立 CDN 或 Nginx。\n- 仅监听 localhost，外部访问通过宿主环境的反向代理或端口转发。\n- 后续演进时，Web API Layer 可独立为微服务，前端静态资源可迁移至 CDN。\n\n### 7.2 分布式部署拓扑（后续演进）\n\n```\n┌──────────────┐ ┌──────────────┐ ┌──────────────┐\n│ 节点 A │ │ 节点 B │ │ 节点 C │\n│ Agent 集群 │ │ Agent 集群 │ │ 管理节点 │\n│ │ │ │ │ │\n│ KIVO Client │ │ KIVO Client │ │ KIVO Admin │\n│ (SDK) │ │ (SDK) │ │ Dashboard │\n└──────┬───────┘ └──────┬───────┘ └──────┬───────┘\n │ │ │\n └────────────┬───────┘────────────────────┘\n │\n ┌────────▼────────┐\n │ KIVO Server │\n │ (HTTP API) │\n └────────┬────────┘\n │\n ┌────────▼────────┐\n │ Storage Layer │\n │ PostgreSQL + │\n │ pgvector │\n └─────────────────┘\n```\n\n后续演进方向：\n\n- KIVO Core 从嵌入库升级为独立服务，暴露 HTTP API。\n- 存储后端从本地文件切换为 PostgreSQL + pgvector（通过 SPI 无缝替换）。\n- 多节点 Agent 通过 KIVO Client SDK 访问共享知识库。\n- 规则分发通过事件推送通道（WebSocket / SSE）实现实时通知。\n\n### 7.3 部署约束\n\n| 约束 | 初期 | 后续演进 |\n|------|--------|--------|\n| 进程模型 | 同进程库调用 | 独立服务进程 |\n| 存储依赖 | 本地文件 + SQLite | PostgreSQL + pgvector |\n| 网络要求 | 无（本地调用） | 内网 HTTP |\n| Embedding | 宿主 API 代理 | 独立 Embedding 服务 |\n| 最低资源 | 256MB RAM, 1GB 磁盘 | 1GB RAM, 10GB 磁盘 |\n\n---\n\n## 8. Cross-cutting Concepts\n\n### 8.1 日志与可观测性\n\n日志分三层：\n\n- 操作日志：知识条目的 CRUD 操作、冲突检测结果、状态流转。每条操作日志包含操作类型、目标条目 ID、时间戳、操作结果。\n- 审计日志：知识条目的完整生命周期追溯。从创建到归档的每一步状态变更都记录在案，满足 NFR AC-4.4。\n- 诊断日志：提取管线的处理耗时、检索延迟、冲突检测命中率等运行时指标。\n\n日志格式统一为结构化 JSON，支持按时间范围、操作类型、条目 ID 过滤查询。\n\n初期日志落盘到本地文件（`./kivo-data/logs/`），后续可对接外部日志系统。\n\n### 8.2 错误处理\n\n错误分类与处理策略：\n\n| 错误类别 | 示例 | 处理策略 |\n|----------|------|----------|\n| 提取失败 | LLM 调用超时、格式解析错误 | 重试 1 次，仍失败则记录原始输入到 dead-letter，不阻塞主流程 |\n| 冲突解决失败 | 自动策略无法判定 | 标记 pending + 生成人工裁决请求，知识条目不入库 |\n| 存储写入失败 | 磁盘满、文件锁冲突 | 抛出异常，上层管线中断并告警 |\n| 检索超时 | 向量检索超过 2s | 降级为元数据过滤检索，返回部分结果并标注降级 |\n| Embedding 生成失败 | API 不可用 | 跳过语义索引，仅存储条目元数据，后续补建索引 |\n\n核心原则：提取和检索的失败不能污染已有知识库数据。写入路径的失败通过 SQLite 事务保证原子性——事务内完成条目元数据、内容、冲突记录和索引的写入，任一步失败则整体回滚。\n\n### 8.3 安全\n\n访问控制模型（简化版）：\n\n- 知识条目按域（domain）划分访问范围。\n- Agent 在检索时携带自身角色标识，Knowledge Store 按角色过滤可见条目。\n- 敏感知识条目（如包含凭据、内部决策）标记 `restricted` 标签，仅限指定角色访问。\n- 规则分发严格按订阅关系，不超范围推送。\n\n初期访问控制通过配置文件定义角色-域映射，不引入独立的认证/授权服务。\n\n数据安全：\n\n- 知识条目存储不包含原始凭据或密钥，提取时自动脱敏。\n- 调研任务不访问用户未授权的信息源（由宿主环境在执行层面保证）。\n\n### 8.4 配置管理\n\nKIVO 的配置分为三层：\n\n| 层次 | 内容 | 加载方式 |\n|------|------|----------|\n| 默认配置 | 知识类型定义、冲突解决策略优先级、检索默认参数 | 内置于代码 |\n| 实例配置 | 存储后端选择、Embedding API 端点、日志级别、清理周期 | 配置文件（`kivo.config.json`） |\n| 运行时配置 | token 预算、调研频率、静默模式开关 | API 调用或环境变量 |\n\n配置加载优先级：运行时 > 实例 > 默认。\n\n配置加载策略：启动时一次性加载，运行期间通过 API 调用修改运行时配置即时生效，实例配置变更需要手动 reload。后续引入文件监听热加载，生效边界为等当前管线批次完成后再应用新配置。\n\n### 8.5 测试策略\n\n| 测试层次 | 覆盖范围 | 工具 |\n|----------|----------|------|\n| 单元测试 | 各域模块的核心逻辑（提取器、冲突检测器、检索排序） | Vitest |\n| 集成测试 | 管线端到端流转（提取→冲突检测→入库→检索） | Vitest + 测试夹具 |\n| 契约测试 | SPI 接口的存储后端实现一致性 | 接口测试套件 |\n| 性能测试 | 检索延迟（P95 ≤ 2s）、千级条目下的写入吞吐 | 基准测试脚本 |\n\n测试数据：使用预构建的知识条目夹具（fixture），覆盖六类知识类型、冲突场景、边界条件。\n\n提取器测试需要 mock LLM 调用，返回预定义的提取结果，避免测试依赖外部 API。\n\n### 8.6 Web 层前后端通信协议\n\n协议选择：HTTP REST + JSON（详见 ADR-008）。\n\n请求规范：\n- Content-Type: application/json\n- 查询参数通过 URL query string 传递\n- 写操作通过 request body 传递\n- 分页参数：`page`（从 1 开始）、`pageSize`（默认 20，最大 100）\n\n响应规范：\n\n```typescript\n// 成功响应\ninterface ApiResponse {\n data: T;\n meta?: {\n total: number;\n page: number;\n pageSize: number;\n };\n}\n\n// 错误响应\ninterface ApiError {\n error: {\n code: string; // 业务错误码，如 CONFLICT_NOT_FOUND\n message: string; // 人可读描述\n details?: unknown; // 可选详细信息\n };\n}\n```\n\nHTTP 状态码约定：\n- 200：查询成功\n- 201：创建成功\n- 400：参数错误\n- 404：资源不存在\n- 409：冲突（如字典术语重名或版本冲突）\n- 500：服务端错误\n\n并发写保护协议：\n\n所有写接口必须携带版本标识，防止后写覆盖前写。\n\n```typescript\n// 写请求必须携带\ninterface WriteRequest {\n // ...业务字段\n expectedVersion: number; // 客户端读取时获得的版本号\n requestId: string; // 幂等键，客户端生成的 UUID\n}\n\n// 成功响应携带新版本号\ninterface WriteResponse {\n data: T;\n meta: {\n version: number; // 写入后的新版本号\n requestId: string; // 回显请求 ID\n };\n}\n\n// 版本冲突响应\ninterface VersionConflictError {\n error: {\n code: 'VERSION_CONFLICT';\n message: string;\n details: {\n currentVersion: number; // 服务端当前版本\n expectedVersion: number; // 客户端提交的版本\n requestId: string;\n };\n };\n}\n```\n\n规则：\n- 服务端收到写请求时，比对 `expectedVersion` 与当前存储版本。不匹配则返回 `409 VERSION_CONFLICT`。\n- `requestId` 用于幂等性保证：相同 requestId 的重复请求不会产生副作用。\n- 前端收到 409 后展示冲突提示，引导用户重新加载最新数据后重试。\n- 适用端点：PATCH /knowledge/:id/status、PUT /knowledge/:id/content、POST/PUT/DELETE /glossary、POST/PATCH /research/tasks、POST /conflicts/:id/resolve。\n\n实时事件推送：\n- 活动流通过 SSE（Server-Sent Events）推送，端点 `/api/v1/activity/stream`。\n- 事件格式：`{ type: string, data: object, timestamp: string }`。\n- 客户端断线后自动重连，通过 `Last-Event-ID` 恢复。\n\n### 8.7 Web 层认证与权限\n\n认证策略（单用户场景）：\n- Web 层与 KIVO Core 同进程部署，仅监听 localhost。\n- 认证通过宿主环境的身份传递（如 HTTP Header `X-KIVO-User`）。\n- 无独立登录流程，依赖宿主的认证网关。\n\n权限模型：\n- 初期只有一种角色：owner（产品负责人），拥有所有操作权限。\n- 后续可扩展角色：viewer（只读）、editor（可编辑知识和字典）、admin（全部权限）。\n- 权限检查在 API Layer 的中间件中统一执行，不散落在各端点处理函数中。\n\n### 8.8 Web 层错误处理策略\n\n错误分层处理：\n\n| 层 | 错误类型 | 处理策略 |\n|------|----------|----------|\n| Frontend | 网络请求失败 | 显示重试按钮，不丢失用户输入 |\n| Frontend | API 返回 4xx | 解析 error.message 展示给用户 |\n| Frontend | API 返回 5xx | 显示通用错误提示，建议稍后重试 |\n| Frontend | 乐观更新回滚 | 回滚 UI 状态 + toast 提示操作失败 |\n| API Layer | 引擎接口调用失败 | 记录错误日志，返回结构化错误响应 |\n| API Layer | 检索超时 | 返回部分结果 + degraded: true 标记 |\n| API Layer | 参数校验失败 | 返回 400 + 具体字段错误信息 |\n\n核心原则：\n- 前端永远不展示原始技术错误信息（如堆栈、SQL 错误），只展示业务可理解的描述。\n- 写操作失败不能导致数据不一致（乐观更新回滚 + 引擎层事务保证）。\n- NFR-G4：所有用户操作 1 秒内给出界面反馈。\n\n---\n\n## 9. Architecture Decisions\n\n完整 ADR 文档见 [decisions/](decisions/) 目录：\n\n- [ADR-001：管道-过滤器作为知识管线架构](decisions/ADR-001-pipeline-filter-architecture.md)\n- [ADR-002：Repository 模式 + SPI 实现存储抽象](decisions/ADR-002-repository-spi-storage.md)\n- [ADR-003：冲突检测作为写入前置拦截](decisions/ADR-003-conflict-detection-pre-write.md)\n- [ADR-004：拉取优先的规则分发策略](decisions/ADR-004-pull-first-rule-distribution.md)\n- [ADR-005：调研任务定义与执行分离](decisions/ADR-005-research-definition-execution-separation.md)\n- [ADR-006：固定六类知识类型 + 扩展注册](decisions/ADR-006-fixed-six-knowledge-types.md)\n- [ADR-007：同进程嵌入式部署](decisions/ADR-007-wave1-embedded-deployment.md)\n- [ADR-008：Web 层 API 风格选择（REST）](decisions/ADR-008-web-api-style-rest.md)\n- [ADR-009：前端框架选择](decisions/ADR-009-frontend-framework-selection.md)\n- [ADR-010：系统词典作为 KnowledgeEntry 的特化视图](decisions/ADR-010-dictionary-as-knowledge-entry-specialization.md)\n\n以下为各决策摘要。\n\n### ADR-001：管道-过滤器作为知识管线架构\n\n状态：已采纳\n\n背景：KIVO 的核心数据流是「信息输入 → 结构化提取 → 质量把关 → 持久化」。需要选择一种架构风格来组织这条管线。\n\n决策：采用管道-过滤器（Pipeline-Filter）架构。提取、冲突检测、合并检测、入库作为独立过滤器，通过 Pipeline Bus 事件串联。每个过滤器可独立测试、独立替换。\n\n替代方案对比：\n\n| 方案 | 优势 | 劣势 | 否决理由 |\n|------|------|------|----------|\n| 事件溯源（Event Sourcing） | 完整审计追溯、时间旅行回放 | 实现复杂度高，需要事件存储基础设施，重放逻辑维护成本大 | 万级条目规模不需要事件溯源的强审计能力，审计日志已满足 NFR AC-4.4 |\n| 直接写入（无管线） | 实现简单，调用链短 | 无法在写入前拦截冲突，一致性无法保证 | 违反一致性第一优先级（NFR-4.5），冲突检测必须前置 |\n\n### ADR-002：Repository 模式 + SPI 实现存储抽象\n\n状态：已采纳\n\n背景：KIVO 需要在不同宿主环境下运行，底层存储可能是本地文件、SQLite、PostgreSQL 或向量数据库。上层业务逻辑不应感知存储差异。\n\n决策：采用 Repository 模式封装数据访问，通过 SPI（Storage Provider Interface）定义存储后端契约。初期实现 SQLite 后端，后续按需实现其他后端。\n\n替代方案对比：\n\n| 方案 | 优势 | 劣势 | 否决理由 |\n|------|------|------|----------|\n| 直接依赖 SQLite API | 无抽象层开销，代码直接 | 更换存储需要修改所有数据访问代码 | 违反解耦约束（§2.1），宿主环境差异大，绑定特定数据库不可接受 |\n| ORM 框架（如 Prisma/TypeORM） | 多数据库支持开箱即用 | 引入重量级依赖，ORM 的查询抽象不覆盖语义检索场景 | 语义检索（Embedding + 余弦相似度）超出 ORM 能力范围，仍需自定义 SPI |\n\n### ADR-003：冲突检测作为写入前置拦截\n\n状态：已采纳\n\n背景：一致性是 KIVO 的第一优先级质量属性。新知识入库时可能与已有知识语义矛盾，需要决定在什么时机执行冲突检测。\n\n决策：冲突检测作为写入前置拦截，所有知识写入路径必须经过 ConflictDetector，零绕过。检测不通过的条目不入库，标记 pending 或触发解决流程。\n\n替代方案对比：\n\n| 方案 | 优势 | 劣势 | 否决理由 |\n|------|------|------|----------|\n| 写入后异步检测 | 写入延迟低，不阻塞入库 | 矛盾知识短暂共存，Agent 可能在检测完成前读到矛盾结果 | 违反「冲突解决率 100%，无矛盾共存」的质量目标（QS-01） |\n| 定期批量扫描 | 实现简单，对写入路径零侵入 | 扫描间隔内矛盾持续存在，扫描频率与数据量成正比 | 无法满足实时一致性要求，规模增长后扫描成本不可控 |\n\n冲突检测技术方案：采用两阶段判定。第一阶段：Embedding 余弦相似度粗筛，对新条目与同类型已有条目计算向量距离，相似度 > 0.85 的候选对进入第二阶段。第二阶段：LLM 语义对比精判，将候选对提交给 LLM，prompt 要求判定「两条知识是否对同一主题给出互斥结论」，返回 conflict / compatible / unrelated 三分类结果。阈值 0.85 作为初始值，通过冲突评估集（≥ 50 组标注样本）校准，持续根据误判/漏判反馈调优。Embedding 不可用时降级为元数据匹配（同类型 + 关键词重叠度 > 60%）+ LLM 精判。\n\n### ADR-004：拉取优先的规则分发策略\n\n状态：已采纳\n\n背景：规则分发需要保证订阅者获取最新规则。需要选择推送、拉取或混合策略。\n\n决策：拉取优先 + 事件补充。Agent 启动时拉取全量规则，运行期间通过事件通知增量更新。高优先级规则变更主动推送通知，Agent 收到通知后拉取最新版本。\n\n替代方案对比：\n\n| 方案 | 优势 | 劣势 | 否决理由 |\n|------|------|------|----------|\n| 纯推送 | 实时性高，变更即达 | 需要维护长连接或 WebSocket，基础设施复杂度高，离线 Agent 需要补偿机制 | 初期单进程部署无网络端口，推送基础设施过重 |\n| 纯拉取（轮询） | 实现简单，无状态 | 轮询间隔决定延迟上限，频繁轮询浪费资源 | 无法满足 NFR-4.3（≤ 30s 延迟）除非轮询间隔极短 |\n\n### ADR-005：调研任务定义与执行分离\n\n状态：已采纳\n\n背景：KIVO 需要自主调研能力来填补知识缺口，但调研涉及网络访问、文档读取等工具能力。\n\n决策：KIVO 只负责定义调研任务（目标、范围、搜索策略、预算），宿主环境负责执行并返回结果。调研结果重新进入提取管线。\n\n替代方案对比：\n\n| 方案 | 优势 | 劣势 | 否决理由 |\n|------|------|------|----------|\n| KIVO 直接持有工具能力 | 端到端闭环，无需宿主协调 | 违反解耦约束，KIVO 需要管理网络访问、API 密钥、沙箱安全 | 增加安全攻击面，与「通用知识管理语义」定位矛盾 |\n| 宿主全权决定调研策略 | KIVO 零调研逻辑 | 宿主不了解知识缺口的优先级和填补策略 | 缺口检测的价值在于精准定义「缺什么、怎么补」，交给宿主等于放弃核心能力 |\n\n### ADR-006：固定六类知识类型 + 扩展注册\n\n状态：已采纳\n\n背景：知识条目需要分类以支撑针对性的提取、检索和冲突检测策略。需要决定类型体系的开放程度。\n\n决策：固定六类核心类型（fact / methodology / decision / experience / intent / meta），新类型通过注册机制扩展。注册时需提供类型定义、提取 prompt 模板和冲突检测规则。\n\n替代方案对比：\n\n| 方案 | 优势 | 劣势 | 否决理由 |\n|------|------|------|----------|\n| 自由标签（无固定类型） | 灵活度最高，用户自定义 | 缺乏结构约束，提取和冲突检测无法针对类型优化，标签膨胀后检索质量下降 | 冲突检测依赖类型语义（fact 的冲突判定与 decision 不同），自由标签无法支撑 |\n| 固定类型不可扩展 | 实现简单，类型语义确定 | 无法适应未预见的知识分类需求 | 可扩展性是关键质量属性（QS-05），完全封闭不可接受 |\n\n### ADR-007：同进程嵌入式部署\n\n状态：已采纳\n\n背景：KIVO 的部署形态影响集成复杂度、运维成本和性能特征。需要决定首版的部署模型。\n\n决策：将 KIVO 作为 TypeScript 库嵌入宿主运行时进程，通过函数调用交互，零独立进程、零网络端口。\n\n替代方案对比：\n\n| 方案 | 优势 | 劣势 | 否决理由 |\n|------|------|------|----------|\n| 独立微服务 | 独立扩缩容、独立部署、技术栈自由 | 引入网络通信、服务发现、健康检查等基础设施开销 | 万级条目规模不需要独立扩缩容，过早引入网络复杂度增加首版交付风险 |\n| Sidecar 进程 | 进程隔离，崩溃不影响宿主 | 需要 IPC 通信，部署和调试复杂度增加 | 同进程库调用延迟更低，稳定性风险可控 |\n\n---\n\n## 10. Quality Requirements\n\n### 10.1 质量树\n\n```\n KIVO 质量目标\n │\n ┌───────────────────┼───────────────────┐\n │ │ │\n 一致性 检索效能 解耦性\n (最高优先) (高优先) (高优先)\n │ │ │\n ┌────┴────┐ ┌────┴────┐ ┌────┴────┐\n │ │ │ │ │ │\n 冲突零 状态机 命中率 响应 存储可 宿主\n 容忍 完整性 ≥85% ≤2s(P95) 替换 无关\n │ │ │\n │ 自主性 可扩展性\n │ (中优先) (中优先)\n │ │ │\n │ 缺口检测 类型/源/\n │ ≥70% 分发可扩展\n```\n\n### 10.2 质量场景\n\n| ID | 质量属性 | 场景 | 刺激 | 响应 | 度量 | 验证方法 |\n|----|----------|------|------|------|------|---------|\n| QS-01 | 一致性 | 新知识与已有知识语义矛盾 | 提取管线产出冲突条目 | 冲突检测拦截，执行解决策略或标记人工裁决 | 冲突解决率 100%，无矛盾共存 | 构造冲突测试集（视为同主题矛盾、同场景矛盾规则各 10 组），执行提取入库流程，验证所有冲突被拦截并解决，无矛盾条目共存于 active 状态 |\n| QS-02 | 检索效能 | Agent 执行任务时查询相关知识 | 语义检索请求 | 返回按相关度排序的知识条目 | 命中率 ≥ 85%，P95 ≤ 2s | 人工标注测试集（≥ 100 条查询 + 期望结果），执行检索并计算 Recall@5；延迟通过基准测试脚本统计 P95 |\n| QS-03 | 解耦性 | 更换底层存储引擎 | 从 SQLite 切换到 Post\n\nFile v1.2.3:docs/architecture/decisions/ADR-001-pipeline-filter-architecture.md\n\n# ADR-001：管道-过滤器作为知识管线架构\n\nOpenClaw（sa-01 子Agent） | 2026-04-19\n\n## 状态\n\nAccepted\n\n## 上下文\n\nKIVO 的核心数据流是「信息输入 → 结构化提取 → 质量把关 → 持久化」。需要选择一种架构风格来组织这条管线，使其具备可测试性、可替换性和清晰的职责边界。\n\n## 决策\n\n采用管道-过滤器（Pipeline-Filter）架构。提取、冲突检测、合并检测、入库作为独立过滤器，通过 Pipeline Bus 事件串联。每个过滤器可独立测试、独立替换。\n\n## 后果\n\n- 每个过滤器职责单一，可独立开发和测试\n- 新增处理步骤只需插入新过滤器，不影响已有管线\n- Pipeline Bus 事件串联提供松耦合，过滤器之间无直接依赖\n- 调试时可在任意过滤器间插入日志/断点观察中间状态\n- 管线编排逻辑需要额外维护，过滤器顺序变更需谨慎\n\n## 替代方案\n\n| 方案 | 优势 | 劣势 | 否决理由 |\n|------|------|------|----------|\n| 事件溯源（Event Sourcing） | 完整审计追溯、时间旅行回放 | 实现复杂度高，需要事件存储基础设施，重放逻辑维护成本大 | 万级条目规模不需要事件溯源的强审计能力，审计日志已满足 NFR AC-4.4 |\n| 直接写入（无管线） | 实现简单，调用链短 | 无法在写入前拦截冲突，一致性无法保证 | 违反一致性第一优先级（NFR-4.5），冲突检测必须前置 |\n\nFile v1.2.3:docs/architecture/decisions/ADR-002-repository-spi-storage.md\n\n# ADR-002：Repository 模式 + SPI 实现存储抽象\n\nOpenClaw（sa-01 子Agent） | 2026-04-19\n\n## 状态\n\nAccepted\n\n## 上下文\n\nKIVO 需要在不同宿主环境下运行，底层存储可能是本地文件、SQLite、PostgreSQL 或向量数据库。上层业务逻辑不应感知存储差异。\n\n## 决策\n\n采用 Repository 模式封装数据访问，通过 SPI（Storage Provider Interface）定义存储后端契约。初期实现 SQLite 后端，后续按需实现其他后端。\n\n## 后果\n\n- 业务逻辑与存储实现完全解耦，更换存储后端只需实现新的 SPI Provider\n- 初期使用 SQLite 即可满足万级条目规模需求，零额外基础设施\n- SPI 契约为后续向量数据库、PostgreSQL 等后端提供清晰的接入规范\n- 需要维护 SPI 接口定义和至少一个参考实现\n- 语义检索（Embedding + 余弦相似度）场景需要 SPI 覆盖向量操作语义\n\n## 替代方案\n\n| 方案 | 优势 | 劣势 | 否决理由 |\n|------|------|------|----------|\n| 直接依赖 SQLite API | 无抽象层开销，代码直接 | 更换存储需要修改所有数据访问代码 | 违反解耦约束（§2.1），宿主环境差异大，绑定特定数据库不可接受 |\n| ORM 框架（如 Prisma/TypeORM） | 多数据库支持开箱即用 | 引入重量级依赖，ORM 的查询抽象不覆盖语义检索场景 | 语义检索（Embedding + 余弦相似度）超出 ORM 能力范围，仍需自定义 SPI |\n\nFile v1.2.3:docs/architecture/decisions/ADR-003-conflict-detection-pre-write.md\n\n# ADR-003：冲突检测作为写入前置拦截\n\nOpenClaw（sa-01 子Agent） | 2026-04-19\n\n## 状态\n\nAccepted\n\n## 上下文\n\n一致性是 KIVO 的第一优先级质量属性。新知识入库时可能与已有知识语义矛盾，需要决定在什么时机执行冲突检测。\n\n## 决策\n\n冲突检测作为写入前置拦截，所有知识写入路径必须经过 ConflictDetector，零绕过。检测不通过的条目不入库，标记 pending 或触发解决流程。\n\n冲突检测技术方案：采用两阶段判定。\n\n1. 第一阶段：Embedding 余弦相似度粗筛，对新条目与同类型已有条目计算向量距离，相似度 > 0.85 的候选对进入第二阶段。\n2. 第二阶段：LLM 语义对比精判，将候选对提交给 LLM，prompt 要求判定「两条知识是否对同一主题给出互斥结论」，返回 conflict / compatible / unrelated 三分类结果。\n\n阈值 0.85 作为初始值，通过冲突评估集（≥ 50 组标注样本）校准。Embedding 不可用时降级为元数据匹配（同类型 + 关键词重叠度 > 60%）+ LLM 精判。\n\n## 后果\n\n- 保证知识库零矛盾共存，满足 QS-01 质量目标\n- 写入路径增加延迟（两阶段检测），但一致性优先于性能\n- 需要维护冲突评估集用于阈值校准\n- Embedding 不可用时有降级方案，不会阻断写入流程\n\n## 替代方案\n\n| 方案 | 优势 | 劣势 | 否决理由 |\n|------|------|------|----------|\n| 写入后异步检测 | 写入延迟低，不阻塞入库 | 矛盾知识短暂共存，Agent 可能在检测完成前读到矛盾结果 | 违反「冲突解决率 100%，无矛盾共存」的质量目标（QS-01） |\n| 定期批量扫描 | 实现简单，对写入路径零侵入 | 扫描间隔内矛盾持续存在，扫描频率与数据量成正比 | 无法满足实时一致性要求，规模增长后扫描成本不可控 |\n\nArchive v1.2.2: 3 files, 1692 bytes\n\nFiles: package.json (1011b), SKILL.md (1259b), _meta.json (123b)\n\nFile v1.2.2:SKILL.md\n\n---\nname: kivo\ndescription: \"KIVO — Agent Knowledge Iteration Engine. A knowledge management system for AI agents that provides knowledge extraction, storage, search, conflict resolution, and iterative learning capabilities. Use when building agent systems that need persistent, evolving knowledge bases.\"\nlicense: MIT\n---\n\n# KIVO — Agent Knowledge Iteration Engine\n\nAgent 知识平台。覆盖知识提取、存储、检索、迭代、调研、图谱、工作台全生命周期。\n\n## Features\n\n- Knowledge extraction and storage (SQLite-backed)\n- Semantic and keyword search\n- Conflict detection and resolution\n- Knowledge distribution and subscription\n- Multi-agent authentication and permissions\n- Bootstrap initialization and health checks\n- Document gate for doc-code consistency\n\n## Quick Start\n\n```bash\nnpm install @self-evolving-harness/kivo\n```\n\n```typescript\nimport { KnowledgeStore, ExtractionPipeline } from '@self-evolving-harness/kivo';\n\nconst store = new KnowledgeStore({ dbPath: './knowledge.db' });\nconst pipeline = new ExtractionPipeline({ store });\nawait pipeline.extract(document);\n```\n\n## CLI\n\n```bash\nnpx kivo init # Initialize knowledge base\nnpx kivo health # Health check\nnpx kivo capabilities # Show capabilities\n```\n\nFile v1.2.2:_meta.json\n\n{\n \"ownerId\": \"kn71kk78dbbgtentzcetv7d1zn8536vd\",\n \"slug\": \"kivo\",\n \"version\": \"1.2.2\",\n \"publishedAt\": 1777723143766\n}\n\nFile v1.2.2:package.json\n\n{\n \"name\": \"@self-evolving-harness/kivo\",\n \"version\": \"1.2.1\",\n \"description\": \"KIVO — Agent 知识平台，覆盖知识提取、存储、检索、迭代、调研、图谱、工作台全生命周期\",\n \"type\": \"module\",\n \"main\": \"dist/index.js\",\n \"types\": \"dist/index.d.ts\",\n \"exports\": {\n \".\": {\n \"types\": \"./dist/index.d.ts\",\n \"import\": \"./dist/index.js\"\n }\n },\n \"bin\": {\n \"kivo\": \"./dist/cli/index.js\"\n },\n \"scripts\": {\n \"build\": \"tsc\",\n \"test\": \"vitest run\",\n \"typecheck\": \"tsc --noEmit\"\n },\n \"dependencies\": {\n \"bcryptjs\": \"^3.0.3\",\n \"better-sqlite3\": \"^11.7.0\",\n \"jszip\": \"^3.10.1\",\n \"pdfjs-dist\": \"^5.7.284\",\n \"uuid\": \"^14.0.0\"\n },\n \"devDependencies\": {\n \"@types/bcryptjs\": \"^2.4.6\",\n \"@types/better-sqlite3\": \"^7.6.12\",\n \"@types/node\": \"^22.0.0\",\n \"@types/uuid\": \"^10.0.0\",\n \"typescript\": \"^5.7.0\",\n \"vitest\": \"^3.1.0\"\n },\n \"engines\": {\n \"node\": \">=20\"\n },\n \"files\": [\n \"dist\",\n \"README.md\",\n \"LICENSE\"\n ]\n}\n\nArchive v1.2.1: 220 files, 394435 bytes\n\nFiles: docs/architecture/arc42-architecture-v2.md (73278b), docs/architecture/arc42-architecture.md (111505b), docs/architecture/decisions/ADR-001-pipeline-filter-architecture.md (1473b), docs/architecture/decisions/ADR-002-repository-spi-storage.md (1455b), docs/architecture/decisions/ADR-003-conflict-detection-pre-write.md (1887b), docs/architecture/decisions/ADR-004-pull-first-rule-distribution.md (1275b), docs/architecture/decisions/ADR-005-research-definition-execution-separation.md (1516b), docs/architecture/decisions/ADR-006-fixed-six-knowledge-types.md (1504b), docs/architecture/decisions/ADR-007-wave1-embedded-deployment.md (1327b), docs/architecture/decisions/ADR-008-web-api-style-rest.md (1632b), docs/architecture/decisions/ADR-009-frontend-framework-selection.md (2677b), docs/architecture/decisions/ADR-010-dictionary-as-knowledge-entry-specialization.md (3877b), docs/configuration-reference.md (8775b), docs/design/user-facing-requirements.md (10548b), docs/product-requirements.md (53378b), docs/quick-start.md (6864b), docs/spec-batch2-append.md (5367b), docs/test-cases.md (16773b), docs/troubleshooting.md (10238b), docs/upgrade-guide.md (4207b), kivo.config.json (102b), package.json (1011b), README.md (11181b), scripts/doc-consistency-check.sh (8960b), SKILL.md (1259b), skill/ingest/scripts/ingest.ts (2008b), skill/ingest/SKILL.md (896b), skill/inject/scripts/inject.ts (2156b), skill/inject/SKILL.md (761b), skill/package.json (433b), skill/query/scripts/query.ts (2076b), skill/query/SKILL.md (817b), skill/resolve/scripts/resolve.ts (3133b), skill/resolve/SKILL.md (972b), skill/tsconfig.json (195b), src/access-control/access-control-types.ts (713b), src/access-control/domain-access-checker.ts (2733b), src/access-control/index.ts (220b), src/adapter/capability-registry.ts (5433b), src/adapter/host-adapter.ts (1667b), src/adapter/index.ts (938b), src/adapter/llm-provider-manager.ts (5728b), src/adapter/llm-provider.ts (345b), src/adapter/openclaw-adapter.ts (3607b), src/adapter/standalone-adapter.ts (3362b), src/association/association-discovery.ts (8225b), src/association/association-retrieval.ts (3798b), src/association/association-store.ts (5641b), src/association/association-types.ts (398b), src/association/graph-insights.ts (13994b), src/association/index.ts (1104b), src/association/knowledge-graph.ts (12468b), src/auth/audit-logger.ts (1413b), src/auth/auth-types.ts (1550b), src/auth/index.ts (566b), src/auth/permission-checker.ts (900b), src/auth/session-manager.ts (2053b), src/auth/user-store.ts (3019b), src/bootstrap/bootstrap-runner.ts (9789b), src/bootstrap/index.ts (203b), src/bootstrap/init-detector.ts (2233b), src/bulk-export/bulk-export-types.ts (826b), src/bulk-export/bulk-exporter.ts (3101b), src/bulk-export/index.ts (217b), src/bulk-import/bulk-import-types.ts (855b), src/bulk-import/bulk-importer.ts (3973b), src/bulk-import/index.ts (264b), src/cli/capabilities.ts (2119b), src/cli/health-check.ts (6047b), src/cli/index.ts (3592b), src/cli/init.ts (6575b), src/cli/install-validator.ts (4467b), src/cli/minimal-mode.ts (2917b), src/cli/query.ts (3633b), src/config.ts (786b), src/config/config-validator.ts (2355b), src/config/env-loader.ts (2667b), src/config/index.ts (306b), src/config/secret-manager.ts (3529b), src/config/types.ts (860b)\n\nFile v1.2.1:SKILL.md\n\n---\nname: kivo\ndescription: \"KIVO — Agent Knowledge Iteration Engine. A knowledge management system for AI agents that provides knowledge extraction, storage, search, conflict resolution, and iterative learning capabilities. Use when building agent systems that need persistent, evolving knowledge bases.\"\nlicense: MIT\n---\n\n# KIVO — Agent Knowledge Iteration Engine\n\nAgent 知识平台。覆盖知识提取、存储、检索、迭代、调研、图谱、工作台全生命周期。\n\n## Features\n\n- Knowledge extraction and storage (SQLite-backed)\n- Semantic and keyword search\n- Conflict detection and resolution\n- Knowledge distribution and subscription\n- Multi-agent authentication and permissions\n- Bootstrap initialization and health checks\n- Document gate for doc-code consistency\n\n## Quick Start\n\n```bash\nnpm install @self-evolving-harness/kivo\n```\n\n```typescript\nimport { KnowledgeStore, ExtractionPipeline } from '@self-evolving-harness/kivo';\n\nconst store = new KnowledgeStore({ dbPath: './knowledge.db' });\nconst pipeline = new ExtractionPipeline({ store });\nawait pipeline.extract(document);\n```\n\n## CLI\n\n```bash\nnpx kivo init # Initialize knowledge base\nnpx kivo health # Health check\nnpx kivo capabilities # Show capabilities\n```\n\nFile v1.2.1:skill/ingest/SKILL.md\n\n---\nname: knowledge-ingest\ndescription: \"从对话或文档中提取并存储结构化知识。支持文件和文本输入，自动执行知识提取、冲突检测和入库。\"\n---\n\n# KnowledgeIngestSkill — 知识摄入\n\n从对话、文档、代码中自动提取结构化知识，经冲突检测后存入知识库。\n\n## 触发词\n\n学习这个、记住、摄入知识、记住这个、把这段话存下来、从这篇文档提取知识、学习这个文件、保存到知识库、ingest、learn this、save knowledge、remember this、extract knowledge\n\n## 使用方式\n\n```bash\n# 从文件摄入\ntsx scripts/ingest.ts --file ./docs/design.md --source \"design-doc\"\n\n# 从文本摄入\ntsx scripts/ingest.ts --text \"用户偏好短答，先结论后证据\" --source \"conversation\"\n```\n\n## 核心路径\n\n`src/extraction/` → `src/pipeline/engine.ts` → `src/conflict/` → `src/repository/`\n\nFile v1.2.1:skill/inject/SKILL.md\n\n---\nname: context-inject\ndescription: \"系统级 Skill：系统自动触发，非用户直接调用。为当前任务自动注入相关知识上下文。根据请求语义检索知识库，按注入策略格式化后注入 Agent 上下文窗口。\"\ntrigger-mode: system\n---\n\n# ContextInjectSkill — 上下文注入\n\n为 Agent 当前任务自动注入相关知识上下文，提升回答质量。\n\n## 触发词\n\nsystem:context-inject\n\n## 使用方式\n\n```bash\n# 为查询注入相关上下文\ntsx scripts/inject.ts --query \"当前用户请求\" [--budget ]\n\n# 指定注入格式\ntsx scripts/inject.ts --query \"设计决策\" --format markdown --budget 3000\n```\n\n## 核心路径\n\n`src/injection/context-injector.ts` → `src/injection/injection-policy.ts`\n\nFile v1.2.1:skill/query/SKILL.md\n\n---\nname: knowledge-query\ndescription: \"检索知识库并返回相关知识条目。支持语义搜索，按相关性排序，可指定 token 预算控制返回量。\"\n---\n\n# KnowledgeQuerySkill — 知识查询\n\n基于语义搜索检索知识库，返回与查询最相关的知识条目。\n\n## 触发词\n\n查知识、搜索记忆、搜索知识库、你知道关于、查一下之前的决策、有没有相关经验、你还记得、recall、query knowledge、search knowledge、what do you know about\n\n## 使用方式\n\n```bash\n# 查询相关知识（默认 budget 2000 tokens）\ntsx scripts/query.ts --query \"用户的交付偏好\"\n\n# 指定 token 预算\ntsx scripts/query.ts --query \"架构决策\" --budget 4000\n```\n\n## 核心路径\n\n`src/search/semantic-search.ts` → `src/repository/knowledge-repository.ts`\n\nFile v1.2.1:skill/resolve/SKILL.md\n\n---\nname: conflict-resolve\ndescription: \"处理知识冲突的人工裁决请求。展示冲突详情，支持用户选择保留策略（新覆旧、保留旧、合并、标记待定）。\"\n---\n\n# ConflictResolveSkill — 冲突裁决\n\n处理知识库中的冲突条目，支持人工裁决和自动解决策略。\n\n## 触发词\n\n知识冲突、矛盾了、哪个是对的、这两条知识矛盾了、用新的、保留旧的、帮我决定哪个对、resolve conflict、conflict、which one is correct\n\n## 使用方式\n\n```bash\n# 列出待裁决冲突\ntsx scripts/resolve.ts --list\n\n# 裁决指定冲突（保留新条目）\ntsx scripts/resolve.ts --id --verdict keep-incoming\n\n# 裁决指定冲突（保留旧条目）\ntsx scripts/resolve.ts --id --verdict keep-existing\n\n# 合并两条\ntsx scripts/resolve.ts --id --verdict merge\n```\n\n## 核心路径\n\n`src/conflict/conflict-resolver.ts` → `src/conflict/conflict-record.ts`\n\nFile v1.2.1:README.md\n\n# KIVO\n\n**让 AI Agent 拥有不会遗忘、持续进化的知识系统。**\n\n---\n\n## 你的 Agent 是不是也这样？\n\n每次新对话，Agent 都像失忆了一样。上周讨论过的决策、踩过的坑、定好的规则——全忘了。你反复投喂同样的信息，Agent 反复犯同样的错。知识散落在聊天记录、配置文件和临时笔记里，没人整理，没人维护，更没人主动去补盲区。\n\nKIVO 改变这一切。\n\n## KIVO 做了什么\n\nKIVO 覆盖知识的完整生命周期，横跨 15 个功能域。更重要的是，KIVO 的用户交互体验远超市面上现有的知识库和 AI 笔记应用（Obsidian、Notion、Mem、Reflect 等）——前端交互体验是 KIVO 作为平台的核心竞争力，不是附属品。\n\n- **交互式知识图谱**：力导向布局、节点按类型着色、缩放平移拖拽、聚焦高亮关联、洞察标记一目了然——不是静态的关系图，是可以探索和发现的知识地图。支持局部图谱（选中节点后按深度展开邻居）、图谱内搜索高亮、关系类型/节点类型过滤\n- **多视图知识浏览**：列表、表格、看板三种视图一键切换，表格视图支持类型和状态的内联编辑（点击即改，自动保存），看板按知识类型分组纵览\n- **版本 diff 对比**：知识条目的历史版本支持词级差异对比，精确到每个修改点\n- **冲突裁决工作台**：冲突双方并排对比、一键保留/合并/废弃、裁决理由留痕——知识冲突不再是被忽略的系统日志，而是用户可以直接操作的决策界面。支持差异对比和升级裁决\n- **语义搜索与后续动作**：向量检索 + 关键词检索，搜索结果支持后续动作（查看详情、跳转图谱、触发调研），高级过滤按类型/时间/域/来源精确筛选\n- **调研管理驾驶舱**：缺口报告、调研队列、任务详情、进度追踪、一键重新调研——从发现盲区到填补知识的完整闭环，全程可视可控\n- **仪表盘总览**：最近编辑的知识、解决的冲突、进行中的调研一目了然，知识健康度和过期预警实时呈现\n- **首次引导与示例数据**：新用户首次进入时自动展示 onboarding 引导，可一键加载示例数据快速体验完整功能\n- **文档导入流水线**：拖拽上传、分段提取进度、逐条确认/拒绝/编辑、原文溯源定位——不是黑盒导入，每一步都透明可控\n- **多源知识提取**：对话、文档、规则文件、URL、手动录入，统一管线自动提取结构化知识\n- **语义检索与关联**：向量检索 + 关键词检索，四种关联类型，按域目标约束排序\n- **知识迭代**：新旧知识冲突自动检测并解决，过时知识自动清理，同主题知识自动合并\n- **自主调研闭环**：发现知识缺口后自动生成调研任务，调研结果回流入库\n- **规则订阅与分发**：系统规则统一注册，按需订阅，变更自动推送\n- **意图理解增强**：Agent 执行任务时自动注入相关知识和术语，辅助意图消歧\n- **系统词典**：术语统一管理，Prompt 自动注入，确保全系统术语语义一致\n\n## 30 秒跑起来\n\n```bash\nnpm install @self-evolving-harness/kivo\nnpx kivo init --yes\nnpx kivo health\n```\n\n直接在命令行验证核心路径（复制粘贴即可运行）：\n\n```bash\nnode --input-type=module -e \"\nimport { Kivo } from '@self-evolving-harness/kivo';\n\nconst kivo = new Kivo({ dbPath: './kivo.db', mode: 'standalone' });\nawait kivo.init();\n\n// 写入一条知识\nconst result = await kivo.ingest('TypeScript 为 JavaScript 添加了静态类型系统。', 'quick-start');\nconsole.log('写入条目数:', result.entries.length);\n\n// 语义检索\nconst results = await kivo.query('TypeScript');\nconsole.log('检索结果:', results.map(r => r.entry.content));\n\nawait kivo.shutdown();\n\"\n```\n\n在项目代码中使用（TypeScript）：\n\n```ts\nimport { Kivo } from '@self-evolving-harness/kivo';\n\nconst kivo = new Kivo({ dbPath: './kivo.db', mode: 'standalone' });\nawait kivo.init();\n\n// 写入一条知识\nawait kivo.ingest('TypeScript 为 JavaScript 添加了静态类型系统。', 'quick-start');\n\n// 语义检索\nconst results = await kivo.query('TypeScript');\nconsole.log(results.map(r => r.entry.title));\n\nawait kivo.shutdown();\n```\n\n验证安装：\n\n```bash\nnpx kivo health\nnpx kivo config-check\n```\n\n## 谁在用、怎么用\n\n### 独立产品操盘者\n\n用 Agent 推进产品研发和运营。需要 Agent 记住历史决策和经验教训，不在同一个坑上反复踩；需要 Agent 能自主调研行业动态，不依赖手动投喂。\n\n### Agent 开发者\n\n构建和维护 Agent 系统。需要统一的知识管理接口，让不同 Agent 共享知识而不互相污染；需要规则分发机制，确保系统规则变更能及时传达到所有相关 Agent。\n\n### 系统管理员\n\n负责 Agent 集群的知识治理。需要知道知识库的健康状态——有多少盲区、多少过时条目、多少冲突待解决。\n\n## 三种使用方式\n\n### standalone：最短路径\n\n适合本地脚本、单机验证、测试环境。上面的「30 秒跑起来」就是这种模式。\n\n环境变量配置（可选）：\n\n```bash\nexport KIVO_DB_PATH=./kivo.db\nexport KIVO_MODE=standalone\nexport KIVO_CONFLICT_THRESHOLD=0.85\n```\n\n### host-embedded：嵌入宿主应用\n\n适合把 KIVO 接进已有 Agent、编排器或聊天系统。\n\n```bash\ngit clone https://github.com/yuchangxu1989-Openclaw/kivo.git\ncd kivo\nnpm install && npm run build\n```\n\n```ts\nimport { Kivo, OpenClawAdapter, EventBus } from '@self-evolving-harness/kivo';\n\nconst kivo = new Kivo({ dbPath: './embedded-kivo.db', mode: 'hosted' });\nawait kivo.init();\n\nconst adapter = new OpenClawAdapter({\n kivo,\n injector: kivo.createContextInjector(),\n eventBus: new EventBus(),\n});\n\n// 对话知识自动提取入库\nawait adapter.onSessionMessage(\n '状态报告应包含结论、行动项、证据和下一步计划。',\n { sessionId: 'sess-001', agentId: 'main' },\n);\n\n// 按 token 预算注入相关知识\nconst context = await adapter.injectContext('状态报告格式', 800);\n\nawait kivo.shutdown();\n```\n\n### full-stack：Core + Web 驾驶舱\n\n适合团队通过浏览器查看知识库、搜索条目、查看活动流和仪表盘指标。\n\n```bash\n# 先构建 Core（同 host-embedded）\ncd kivo\nnpm install && npm run build\n\n# 启动 Web\ncd web\nnpm install\nexport AUTH_PASSWORD='your-password'\nnpm run dev\n```\n\n打开浏览器访问 `http://localhost:3000/kivo/dashboard`。\n\n## 核心能力一览\n\n| 能力 | 说明 |\n|------|------|\n| 对话知识提取 | 从 Agent 对话中自动识别事实、方法论、决策、经验、意图、元认知 |\n| 文档知识提取 | 支持 Markdown、PDF、网页正文，保留原文溯源 |\n| 规则提取与分发 | 从治理文件中提取规则，按订阅关系推送给相关 Agent |\n| 个人知识录入 | 手动录入、文件导入、URL 抓取、对话沉淀、批量文件夹导入 |\n| 语义检索 | 基于语义相似度检索，支持按类型、时间、来源、知识域过滤 |\n| 知识关联 | 补充、替代、冲突、依赖四种关联类型，自动检测潜在关联 |\n| 知识版本管理 | 每条知识条目可追溯历史版本，状态流转清晰 |\n| 冲突检测与解决 | Embedding 粗筛 + LLM 精判，支持时间优先、来源优先、人工裁决 |\n| 知识过期清理 | 基于时间衰减和引用频率自动标记过时知识 |\n| 知识合并 | 不同来源的同主题知识自动识别并合并，按类型区分策略 |\n| 缺口检测 | 基于查询未命中、关联结构缺失和图谱信号识别知识盲区 |\n| 自主调研 | 发现缺口后自动生成调研任务，调研结果入库形成闭环 |\n| 上下文注入 | Agent 处理请求时自动注入相关知识，按 token 预算裁剪 |\n| 意图消歧 | 利用历史知识辅助消解用户意图歧义 |\n| 系统词典 | 术语统一注册、Prompt 注入、冲突检测、生命周期管理 |\n| 知识管线编排 | 提取→分析→分类→冲突→合并→入库，阶段化事件驱动 |\n| 分析中间产物 | 提取过程的结构化分析结果持久化，支持审核和回放 |\n| 知识域目标声明 | 为每个域定义目标和边界，约束提取、检索和调研行为 |\n| 知识图谱构建 | 基于关联关系自动构建，增量更新，API 暴露 |\n| 图谱洞察 | 识别孤立节点、桥接节点、稀疏社区、意外关联 |\n| 图谱可视化 | 力导向布局，节点按类型着色，支持缩放、过滤、聚焦 |\n| 网页抓取 | WebFetchAdapter 用原生 fetch 抓取 URL 提取正文，无需额外依赖 |\n| Web 工作台 | 仪表盘、知识浏览、冲突管理、调研队列、活动流、文档导入、词典、意图库 |\n| 访问控制 | 域级知识隔离，不同 Agent 访问不同知识域 |\n| 批量导入导出 | 知识库和术语的 JSON/YAML/CSV 批量导入导出 |\n| 宿主适配层 | 能力协商、LLM Provider 管理、降级策略 |\n| 开箱即用 | 安装校验、Bootstrap 引导、最小运行模式、升级迁移 |\n\n## 配置参考\n\n| 环境变量 | 说明 | 默认值 |\n|----------|------|--------|\n| `KIVO_DB_PATH` | 数据库路径 | `./kivo.db` |\n| `KIVO_MODE` | 运行模式 | `standalone` |\n| `KIVO_CONFLICT_THRESHOLD` | 冲突检测阈值 | `0.85` |\n| `KIVO_EMBEDDING_PROVIDER` | 向量化提供商 | — |\n| `KIVO_EMBEDDING_API_KEY` | 向量化 API Key | — |\n| `KIVO_EMBEDDING_MODEL` | 向量化模型 | — |\n| `AUTH_PASSWORD` | Web 登录密码 | — |\n\n不配置 embedding 也能运行，语义检索会退化为关键词检索。\n\n## 运行要求\n\n- Node.js >= 20\n- SQLite（通过 `better-sqlite3`，安装时自动编译）\n\n## 常用命令\n\n```bash\nnpx kivo health # 健康检查\nnpx kivo init --yes # 初始化配置\nnpx kivo config-check # 验证配置\nnpx kivo env # 查看环境变量\nnpx kivo capabilities # 查看可用能力\nnpx kivo query # 命令行检索知识\nnpx kivo doc-gate # 文档-代码一致性检查\n```\n\n## 文档\n\n- [快速开始](./docs/quick-start.md)\n- [配置参考](./docs/configuration-reference.md)\n- [故障排查](./docs/troubleshooting.md)\n- [升级指南](./docs/upgrade-guide.md)\n- [产品规格](./docs/product-requirements.md)\n- [架构文档](./docs/architecture/arc42-architecture.md)\n\n## 已知依赖漏洞\n\nWeb 驾驶舱使用 `next@14.2.35`（14.x 最新 patch），存在以下已知漏洞：\n\n| 依赖 | 严重程度 | 说明 |\n|------|----------|------|\n| `next` ≥9.3.4 | **high** | DoS（Image Optimizer）、HTTP 请求走私（rewrites）、磁盘缓存无限增长、Server Components DoS |\n| `postcss` <8.5.10 | moderate | CSS Stringify 输出中的 XSS |\n\n修复需升级到 `next@16`（breaking change），当前暂不升级。生产部署建议：\n- 禁用或限制 `next/image` 远程模式\n- 在反向代理层过滤异常请求\n- 限制磁盘缓存目录大小\n\n## 许可证\n\nMIT License。商业使用和衍生作品须保留原作者署名（yuchangxu1989@gmail.com）。\n\n详见 [LICENSE](./LICENSE)。\n\nFile v1.2.1:_meta.json\n\n{\n \"ownerId\": \"kn71kk78dbbgtentzcetv7d1zn8536vd\",\n \"slug\": \"kivo\",\n \"version\": \"1.2.1\",\n \"publishedAt\": 1777721688485\n}\n\nFile v1.2.1:docs/architecture/arc42-architecture-v2.md\n\n# KIVO — arc42 架构文档\nOpenClaw（dev-01 子Agent）| 2026-04-29\n\n---\n\n## 目录\n1. 引言与目标（Introduction and Goals）\n2. 约束（Architecture Constraints）\n3. 上下文与范围（System Scope and Context）\n4. 解决方案策略（Solution Strategy）\n\n---\n\n## 1. 引言与目标（Introduction and Goals）\n\n### 1.1 问题陈述\nKIVO（Knowledge Iteration & Vibe Orchestration）处理的是 Agent 知识管理问题。\n当前知识散落在对话、记忆文件、规则文件、调研报告、网页摘录和临时笔记中。\n这些内容有价值，但大多还停留在原始记录层，没有进入结构化、可检索、可迭代、可治理的状态。\n由此带来的后果很直接：\n- Agent 记住片段，记不住稳定结论。\n- 新知识入库后，旧知识可能继续生效。\n- 用户纠偏发生过多次，系统仍会重复同类错误。\n- 规则、事实、方法、经验混在一起，调用边界不清。\n- 用户想看知识全貌时，只能翻文件，无法从系统层获得统一视图。\nKIVO 的目标，是把分散知识转成可运营的知识资产，并让 Agent 与用户都能稳定消费这套资产。\n\n### 1.2 系统目标\nKIVO 有两个直接消费面：\n- 面向 Agent：提供知识提取、结构化存储、语义检索、冲突解决、上下文注入、规则分发和缺口驱动调研。\n- 面向用户：提供 Knowledge Workbench，用于导入、查看、审核、探索、调研和治理知识库。\n围绕这两个消费面，系统需要达成以下结果：\n- 知识条目结构统一，能稳定存取和追溯。\n- 知识变更走版本与冲突流程，不发生静默覆盖。\n- 检索支持语义、类型、时间、来源、知识域与目标声明约束。\n- 系统能主动发现知识缺口，并把缺口转成可执行调研任务。\n- 规则分发与知识检索分开建模，治理信息和内容信息分别处理。\n- 核心逻辑与宿主环境解耦，不绑死某个运行时或工具链。\n- 外部陌生用户能在最小依赖下跑通首次知识旅程。\n\n### 1.3 架构驱动因素\n本架构由以下因素主导：\n- 知识生命周期长于单次会话，需要跨对话、跨任务、跨 Agent 持续存在。\n- 知识同时服务机器消费和人工审阅，结构与可读性都要成立。\n- 宿主能力并不恒定，网络访问、Provider、文件权限和工具能力都可能变化。\n- 系统初期要能单机运行，后续还要支持更复杂的嵌入式部署。\n- 研发资源有限，架构要先保证主干闭环，再开放扩展点。\n\n### 1.4 最重要的质量目标\n#### QG-1 一致性（Consistency）\n知识写入必须经过分类、冲突检测和状态管理。\n新旧结论冲突时，系统要么自动裁决，要么显式进入人工裁决流。\n衡量标准：\n- 冲突检测覆盖所有写入路径。\n- 冲突解决率达到 100%。\n- 条目状态流转可审计、可回放。\n\n#### QG-2 检索有效性（Retrieval Effectiveness）\nKIVO 的价值主要体现在取用环节。\n知识已经入库却在检索时拿不到，整套结构化工作就失去意义。\n衡量标准：\n- 检索命中率达到 spec 目标。\n- 返回结果包含来源、类型、相关度和版本语义。\n- 语义检索失败时可降级，不让系统整体失明。\n\n#### QG-3 宿主解耦（Host Decoupling）\nKIVO 需要在 OpenClaw 体系内落地，也要保留迁移到其他宿主的能力。\n衡量标准：\n- 更换宿主适配层时，核心域逻辑不改。\n- 更换底层存储或检索引擎时，上层接口行为稳定。\n- 宿主能力下降时，系统进入可解释的降级状态。\n\n#### QG-4 可治理性（Governability）\n知识系统进入真实使用后，治理成本会持续上升。\n系统必须让用户看见待确认条目、待裁决冲突、未补齐盲区和关键状态变化。\n衡量标准：\n- 关键事件进入活动流。\n- 核心指标能聚合到仪表盘。\n- 审计链路能追到来源、版本、裁决和分发记录。\n\n#### QG-5 开箱即用（Out-of-Box Readiness）\nKIVO 需要支持外部用户安装、启动、录入、检索和持续使用。\n衡量标准：\n- 最小运行模式成立。\n- 首次知识旅程可在 10 分钟内完成。\n- 安装与配置错误有清楚提示和恢复路径。\n\n### 1.5 利益相关者\n#### Solo Founder / 独立产品操盘者\n关注点：Agent 是否能持续记住决策、方法论和经验教训；知识缺口能否被主动发现并补齐；历史积累能否持续复用。\n\n#### Agent 开发者\n关注点：是否有统一知识接口供多个 Agent 共用；知识共享时是否有域边界和规则边界；宿主升级或 Provider 变化时接口是否稳定。\n\n#### 系统管理员 / 运营者\n关注点：访问控制是否可管；冲突、缺口、分发失败、待确认条目是否可观察；导入导出、升级迁移是否可控。\n\n#### 最终用户 / 知识工作者\n关注点：能否通过 Workbench 直接导入和管理知识；搜索、详情、活动流、调研入口是否清楚；空库时是否有引导。\n\n#### OpenClaw 宿主环境\n关注点：KIVO 是否遵守插件边界和运行时约束；与 Gateway、工具调用、文件系统、消息通道的集成成本是否可控；核心能力能否复用到其他项目。\n\n#### 研发相关模块（SEVO / AEO / Claw Design）\n关注点：SEVO 需要历史规格、方法论、规则和经验；AEO 需要在效果漂移时联动 KIVO 排查知识缺失；Claw Design 只消费知识，不承担知识治理职责。\n\n---\n\n## 2. 约束（Architecture Constraints）\n\n### 2.1 技术约束\n#### TC-1 OpenClaw 插件体系约束\nKIVO 当前以 OpenClaw 为主宿主。\n集成边界需要兼容 Gateway、插件、skills、共享工作区和消息调度模型。\n核心知识逻辑可以独立抽象，但运行时要接受宿主的事件方式、文件布局和工具分发方式。\n\n#### TC-2 Node.js 运行时约束\n系统主实现以 Node.js 为边界条件。\n这会影响并发模型、内存使用、I/O 方式、生态选择和部署形态。\n架构需要优先采用适合 Node.js 的异步事件驱动方案，避免依赖重型本地服务才能成立。\n\n#### TC-3 Provider 可变约束\n知识提取、冲突精判、Embedding 生成、结构化输出依赖 LLM Provider。\nProvider 可能有能力差异、配额限制、网络波动和临时不可用场景。\n系统必须支持 Provider 注册、能力声明、降级和切换。\n\n#### TC-4 宿主能力协商约束\nKIVO 不能假设每个宿主都具备完整能力。\n有的宿主没有浏览器，有的宿主没有 Embedding Provider，有的宿主网络能力受限。\n因此需要显式的 Host Adapter 与 capability negotiation 机制。\n\n#### TC-5 最小运行模式约束\nspec 明确要求 standalone 最小组合可运行。\n架构不能建立在必须有向量数据库、图数据库或外部任务系统的前提上。\n默认形态要能落在单机、本地存储、单 Provider 的组合上。\n\n#### TC-6 原始内容治理约束\n系统遵守“知识先结构化再存储”。\n原始文档、网页正文、对话片段可以作为来源引用和处理中输入，但核心库不以原文堆积作为主存储模型。\n\n#### TC-7 事件化写入约束\n知识条目写入、图谱更新、缺口检测、规则分发和活动流刷新存在天然串联关系。\n为了满足异步提取和局部失败隔离，系统需要以事件驱动推进阶段，而不是把所有处理压进单个同步请求。\n\n### 2.2 组织约束\n#### OC-1 单人开发约束\nKIVO 当前处于 solo founder + AI agents 的研发组织里。\n架构要能被少量维护者理解、调试和演进，避免把核心闭环拆成过多高耦合微服务。\n\n#### OC-2 开源发布约束\n系统目标包含对外可安装、可文档化、可升级。\n架构需要为 README、Quick Start、配置参考、故障排查和迁移脚本预留稳定入口。\n\n#### OC-3 多宿主潜力约束\n当前优先服务 OpenClaw，但产品定义要求核心逻辑与宿主环境解耦。\n架构阶段就要保留宿主适配面，避免未来迁移时整体重写。\n\n#### OC-4 审计与交付约束\n关键状态变更需要能被审计、回看和解释。\n架构从一开始就要把活动流、指标聚合、版本历史和裁决记录纳入主路径。\n\n### 2.3 惯例约束\n#### CC-1 六类知识类型固定起步\n系统首批采用 fact、methodology、decision、experience、intent、meta 六种类型。\n后续允许扩展，但当前所有提取、存储、检索和展示逻辑都围绕这六类先闭环。\n\n#### CC-2 规则与知识分离\nRule Entry 与 Knowledge Entry 职责不同。\n规则描述治理语义，知识描述事实、方法、经验和意图。\n这两类对象的生命周期、订阅机制和消费方式不同。\n\n#### CC-3 冲突必须显式处理\n系统接受知识会发生冲突，但不接受冲突悄悄留在库里继续生效。\n任何写入路径都必须进入统一冲突机制。\n\n#### CC-4 溯源与版本是基础元数据\n知识条目、调研结果、裁决结论和系统生成产物都必须有来源引用与版本语义。\n没有来源的条目可以临时保存在待确认状态，不能直接成为高置信长期知识。\n\n#### CC-5 Workbench 是独立消费层\nWorkbench 是用户使用 KIVO 的正式入口之一。\n架构上要与引擎层解耦，功能上要覆盖导入、审核、探索、调研和活动流。\n\n---\n\n## 3. 上下文与范围（System Scope and Context）\n\n### 3.1 业务边界\nKIVO 负责知识提取、分类、冲突治理、持久化、检索、图谱构建、缺口检测、调研任务定义、规则管理和用户工作台。\nKIVO 不负责：\n- 研发流水线推进与任务编排，那是 SEVO 的职责。\n- Agent 效果度量与漂移分析，那是 AEO 的职责。\n- 设计资产生成，那是 Claw Design 的职责。\n- 宿主工具的实现细节，KIVO 只通过适配层消费宿主能力。\n\n### 3.2 业务上下文\n```text\n用户 / 管理员 / Agent 开发者\n │\n │ 浏览 / 检索 / 审核 / 配置 / 调研\n ▼\nKnowledge Workbench\n │\n │ HTTP API / Event Stream\n ▼\nKIVO Core\n ├─ 知识提取与分析\n ├─ 分类与路由\n ├─ 冲突治理与版本\n ├─ 检索与上下文注入\n ├─ 规则注册与分发\n ├─ 图谱与缺口检测\n └─ 调研任务定义\n │\n ├──────── OpenClaw Gateway / Host Adapter\n ├──────── LLM Providers / Embedding Providers\n ├──────── 文件系统 / 本地存储 / 导入源\n ├──────── Web / 文档 / URL 信息源\n └──────── 飞书等外部协作系统\n```\n\n### 3.3 业务交互对象\n#### 用户\n与 KIVO 的交互：上传文档、录入知识、搜索条目、查看图谱和活动流、裁决 pending 条目与冲突条目、管理系统字典和意图库。\nKIVO 交付给用户的价值：可见的知识资产全貌、可操作的审核与调研闭环、清楚的首次知识旅程。\n\n#### Agent\n与 KIVO 的交互：发起语义检索请求、请求上下文注入与术语注入、查询订阅规则、提交对话或调研结果进入知识管线。\nKIVO 交付给 Agent 的价值：稳定的知识消费接口、具备边界的上下文增强、知识缺失后的补盲动作。\n\n#### OpenClaw Gateway / 宿主环境\n与 KIVO 的交互：提供运行时、工具分发、文件工作区、消息通道和外部系统访问能力；通过 Host Adapter 向 KIVO 注册可用能力；接收 KIVO 输出的调研任务定义或高优先级分发事件。\nKIVO 对宿主的要求：能声明能力、承载异步事件、提供基础持久化，并允许功能降级。\n\n#### LLM Provider / Embedding Provider\n与 KIVO 的交互：负责知识提取、结构化分析、冲突精判、意图增强和向量生成；以能力声明形式暴露文本生成、Embedding、结构化输出等能力。\nKIVO 对 Provider 的要求：可注册、可切换、失败可解释、输出可标准化处理。\n\n#### 文件系统与外部信息源\n与 KIVO 的交互：提供文档导入、URL 抓取结果、规则文件、报告文件和导出文件；作为 Source Reference 的承载位置之一。\n处理原则：先分析，再生成条目，再入库；结构化知识入主库，原始内容保留为来源与辅助上下文。\n\n#### 飞书等外部协作系统\n与 KIVO 的交互：承接通知、分享和协作场景，可消费调研完成、冲突待裁决、系统就绪度等外部消息。\n定位：协作出口，不承担知识主存储职责。\n\n### 3.4 技术上下文\n#### 入口接口\n- Knowledge Query API：给 Agent 和 Workbench 提供搜索能力。\n- Context Injection API：给 Agent 提供检索后上下文。\n- Extraction Input：接收对话、文档、网页、规则文件和手工录入内容。\n- Rule Query / Subscription API：给 Agent 查询和订阅规则。\n- Research Task API / Event：输出结构化调研任务定义。\n- Dashboard / Activity / Detail API：给 Workbench 提供聚合与明细数据。\n- Research Task API / Queue Adapter：给调研规划器、Workbench 和宿主执行器提供任务创建、领取、回写和取消接口。\n\n#### 调研任务执行路径\n1. D 域的 Gap Detector 或用户手工操作生成 `Research Task draft`，写入 Research Queue。\n2. Research Planner 为任务补齐目标、范围、预算、优先级和推荐信息源，并决定进入 active 还是 silent 队列。\n3. Queue Adapter 把可执行任务暴露给宿主执行器、外部检索工具或人工领取入口。\n4. 执行器完成后，把结构化结果、原始引用和失败原因回写到 Research Task，并触发新的 Extraction Input。\n5. K 管线重新接管回流结果，生成 Analysis Artifact 和正式 Knowledge Entry；若执行失败，则保留失败记录与重试建议，不污染主知识库。\n6. W 通过 Activity API 和 Task Detail API 展示任务状态、预算消耗、回流结果和下一步操作。\n\n#### 外部协议与接口风格\n- 同步查询场景以 HTTP REST 或进程内函数接口承载。\n- 异步阶段推进以事件流承载。\n- 活动流与实时状态更新采用 SSE 或等价流式机制。\n- 外部宿主能力通过 Adapter SPI 或 capability registration 暴露。\n- 规则推送可用 Webhook、消息事件或宿主内信号机制承载。\n\n#### 技术边界图\n```text\n[Browser / Workbench]\n │ HTTP + SSE\n ▼\n[Web API Layer]\n │ internal service calls\n ▼\n[KIVO Core]\n ├─ Pipeline Orchestrator\n ├─ Knowledge Store\n ├─ Retrieval Engine\n ├─ Conflict Resolver\n ├─ Graph & Insight Engine\n ├─ Rule Distribution Engine\n └─ Host Adapter Layer\n │\n ├─ Provider APIs\n ├─ Storage SPI\n ├─ File System\n └─ Host Events / Notifications\n```\n\n### 3.5 上下文中的关键边界决定\n- KIVO 不等同于某个向量数据库封装层。\n- KIVO 不等同于某个图数据库产品。\n- KIVO 不把调研执行器写死在系统内部。\n- KIVO 不把 Workbench 和 Core 混成一层。\n- KIVO 不把规则订阅逻辑塞进普通知识检索流程。\n\n---\n\n## 4. 解决方案策略（Solution Strategy）\n\n### 4.1 总体策略\nKIVO 采用”核心知识平台 + 宿主适配层 + Workbench 消费层”的分层策略。\n整体按以下结构组织：\n- 一条事件驱动的知识管线，负责从输入走到入库和回流。\n- 一套结构化知识存储与检索能力，负责长期保留与取用。\n- 一层宿主适配机制，负责承接 Gateway、Provider、文件系统和调度能力。\n- 一层 Workbench，负责面向人类用户的浏览、审核、探索和调研操作。\n这套策略服务三个目标：让知识主干闭环先成立，让宿主可替换，让用户可直接使用。\n\n### 4.2 关键架构决策\n#### D-1 以 Knowledge Entry 为统一核心对象\n所有消费面都围绕 Knowledge Entry 工作。\n规则、调研任务、分析产物、冲突记录和图谱关系围绕它形成辅助对象。\n这样可以避免每个入口各自产生一套近似但不兼容的数据语义。\n\n#### D-2 提取管线拆成“分析产物生成”与“知识条目生成”两步\n系统先产出 Analysis Artifact，再决定是否生成正式知识条目。\n这样能提升可审计性，也给人工审核、低置信度拦截和调研建议生成留出稳定中间层。\n\n#### D-3 所有写入路径统一进入冲突治理\n手工录入、文档导入、网页抓取、对话提取、调研回流和批量导入都不能绕过冲突机制。\n这样能把一致性从规则变成基础设施。\n\n#### D-4 检索与规则分发双通道并存\n知识检索解决“当前要知道什么”。\n规则分发解决“当前必须遵守什么”。\n二者消费时机、权限模型和更新频率不同，分开设计更稳。\n\n#### D-5 宿主能力通过 Host Adapter 暴露\nKIVO Core 只认抽象能力：文件读写、网络访问、LLM 调用、Embedding 生成、事件投递和通知发送。\nOpenClaw 是首个适配目标，但不是唯一合法目标。\n\n#### D-6 Workbench 与 Core 解耦\nWorkbench 通过 API 消费 Core，而不是直接操纵内部存储结构。\n这样做能统一人类用户与 Agent 的业务语义，也有利于集中处理访问控制、审计和活动流。\n\n#### D-7 图谱、缺口检测、调研形成后置增值链路\n知识入库是主路径。\n图谱、洞察、缺口报告和调研任务围绕主路径生长。\n这样能保证最小运行模式成立，同时为高阶能力保留演进空间。\n\n#### D-8 先支持单机闭环，再开放后端替换点\n默认形态优先满足本地文件系统、轻量关系存储、可插拔向量能力和单 Node.js 进程运行。\n后续如需扩展到外部存储、分布式执行器或更复杂的 Provider 编排，可在 SPI 边界后替换实现。\n\n### 4.3 技术选型理由\n#### Node.js 作为主运行时\n理由：与 OpenClaw 宿主生态一致；适合 I/O 密集、事件驱动、接口聚合型系统；便于统一 Web API、后台管线和工具集成；对外发布和最小运行模式更友好。\n\n#### OpenClaw 插件 / 适配器边界作为首发集成点\n理由：当前业务就在 OpenClaw 体系内真实发生；宿主已有 Gateway、工具路由、工作区文件系统和外部协作能力；可把架构重点放在知识语义而不是重复造运行时。\n\n#### HTTP REST + 事件流的双制式接口\n理由：检索、详情、仪表盘适合同步请求；提取、图谱更新、活动流、调研任务生成适合异步流转；双制式接口能兼顾 Workbench、Agent 和宿主三类消费者。\n\n#### 存储抽象层（Storage SPI）\n理由：允许最小模式先跑在轻量本地存储上；为后续替换向量引擎、关系存储和图关系存储保留空间；避免上层逻辑被底层供应商特性反向塑形。\n\n#### Provider Router / Capability Registry\n理由：不同 Provider 的能力差异很大；KIVO 的核心能力依赖模型，但依赖方式不同；用 capability registry 管理模型能力，能把切换、降级和容错做成显式机制。\n\n#### SSE 驱动 Workbench 活动流与实时状态\n理由：活动流、调研状态、待确认项和冲突提醒有实时更新需求；SSE 比轮询更轻，部署成本也低，足够覆盖当前场景。\n\n### 4.4 与 15 个功能域的映射关系\n- 域 A 知识提取：落在输入适配层与分析管线入口，负责对话、文档、URL、规则文件和手工录入的进入方式。\n- 域 B 知识存储与检索：落在 Knowledge Store 与 Retrieval Engine，负责条目持久化、版本管理、关系维护、Embedding 缓存和语义查询。\n- 域 C 知识迭代：落在 Conflict Resolver 与 Lifecycle Manager，负责冲突检测、裁决策略、过期清理和合并回退。\n- 域 D 自主调研：落在 Gap Detector、Research Planner 与 Host Adapter 协同边界，负责把知识缺口变成可执行调研任务并接收回流结果。\n- 域 E 意图理解增强：落在 Retrieval Engine、Context Injector 与术语注入链路，负责给 Agent 提供贴近当前请求的上下文和消歧能力。\n- 域 F 规则订阅与分发：落在 Rule Engine、Subscription Registry 与 Distribution Channel，负责规则注册、订阅匹配、推送确认和范围控制。\n- 域 G 知识图谱与洞察：落在 Graph Engine 与 Insight Analyzer，负责关系图构建、结构洞察、图谱可视化支撑数据和缺口信号生成。\n- 域 H 系统词典：落在 Terminology Registry 与 Prompt Injection Support，负责术语统一、冲突识别、生命周期管理和注入支持。\n- 域 I 宿主适配层：落在 Host Adapter、Capability Registry 与 Provider Connector，负责宿主能力协商、Provider 管理与降级控制。\n- 域 K 知识管线编排：落在 Pipeline Orchestrator，负责阶段顺序、阶段跳过、失败隔离、事件推进和扩展阶段注册。\n- 域 L 分析中间产物：落在 Analysis Artifact Store 与 Review Queue，负责保存语义中间层，支撑审计、人工审核和后续消费。\n- 域 M 知识域目标声明：落在 Domain Purpose Registry 与 Ranking / Research Constraints，负责给提取、检索、缺口检测和调研生成提供目标边界。\n- 域 W 知识工作台：落在 Workbench Frontend 与 Web API Layer，负责人类使用面的仪表盘、列表、详情、活动流、调研、导入、字典和意图库。\n- 域 X 访问控制与可观测性：横切整个系统，负责域访问控制、操作审计、指标采集、导入导出和聚合观察视图。\n- 域 Z 开箱即用与商用就绪：横切安装、配置、Bootstrap、最小运行模式、文档交付和升级迁移，决定系统能否被外部用户直接使用。\n\n### 4.5 策略收束\nKIVO 用统一知识对象、事件驱动管线、宿主适配抽象和独立 Workbench，把分散的 Agent 知识转成可持续运营的知识系统。\n\n---\n\n## 5. 构建块视图（Building Block View）\n\n### 5.1 Level 1：顶层模块分解\n\nKIVO 的顶层构建块按 15 个功能域展开，但实现上按四层组织：输入与消费层、核心知识层、横切治理层、外部适配层。\n\n```text\nKIVO\n├─ 输入与消费层\n│ ├─ A 知识提取\n│ ├─ W 知识工作台\n│ └─ E 意图理解增强\n├─ 核心知识层\n│ ├─ B 知识存储与检索\n│ ├─ C 知识迭代\n│ ├─ D 自主调研\n│ ├─ F 规则订阅与分发\n│ ├─ G 知识图谱与洞察\n│ ├─ H 系统词典\n│ ├─ K 知识管线编排\n│ ├─ L 分析中间产物\n│ └─ M 知识域目标声明\n├─ 横切治理层\n│ ├─ X 访问控制与可观测性\n│ └─ Z 开箱即用与商用就绪\n└─ 外部适配层\n └─ I 宿主适配层\n```\n\n#### A. 知识提取（Knowledge Extraction）\n- 职责：接收对话、文档、URL、规则文件和手工录入内容，归一化为 Extraction Input，并产出可追溯的 Source Reference。\n- 接口：`submitConversation()`、`submitDocument()`、`submitUrl()`、`submitManualEntry()`。\n- 依赖：K 管线编排、L 分析中间产物、I 宿主适配层、X 审计日志。\n\n#### B. 知识存储与检索（Knowledge Store & Retrieval）\n- 职责：管理 Knowledge Entry、版本、状态、向量、关联与查询计划，是所有知识消费路径的主存储中心。\n- 接口：`saveEntry()`、`updateEntry()`、`queryKnowledge()`、`getEntryHistory()`、`findRelatedEntries()`。\n- 依赖：C 知识迭代、G 图谱、H 系统词典、I Provider 管理、X 访问控制。\n\n#### C. 知识迭代（Knowledge Iteration）\n- 职责：检测冲突、处理合并、执行过期清理、管理 superseded 与 deprecated 状态。\n- 接口：`detectConflicts()`、`resolveConflict()`、`mergeEntries()`、`deprecateEntry()`、`archiveEntry()`。\n- 依赖：B 存储与检索、L 分析中间产物、I Provider 管理、X 审计与指标。\n\n#### D. 自主调研（Autonomous Research）\n- 职责：根据缺口报告生成调研任务、控制预算、接收回流结果，并把结果送回知识管线。\n- 接口：`createResearchTask()`、`reprioritizeTask()`、`cancelTask()`、`ingestResearchResult()`。\n- 依赖：G 图谱洞察、M 域目标声明、I 宿主适配层、W 调研管理界面。\n\n#### E. 意图理解增强（Intent Enhancement）\n- 职责：对 Agent 查询做语义解释、上下文筛选、术语注入与歧义提示，形成面向执行时的增强上下文。\n- 接口：`prepareContext()`、`rankContextEntries()`、`injectTerminology()`、`suggestClarification()`。\n- 依赖：B 检索、H 术语、M 域目标声明、X 权限裁剪。\n\n#### F. 规则订阅与分发（Rule Subscription & Distribution）\n- 职责：管理 Rule Entry、订阅关系、分发记录和确认状态，保证治理信息以独立通道传播。\n- 接口：`registerRule()`、`subscribeRules()`、`pullRules()`、`pushRuleChange()`、`ackDistribution()`。\n- 依赖：I 宿主事件能力、X 权限模型、W 规则相关配置页。\n\n#### G. 知识图谱与洞察（Knowledge Graph & Insights）\n- 职责：根据条目与关系维护图谱，识别孤立节点、桥接节点、稀疏社区和跨主题异常连接。\n- 接口：`updateGraph()`、`listGraphNeighbors()`、`generateInsights()`、`exportGraphView()`。\n- 依赖：B 关联关系、C 生命周期状态、D 调研任务生成、W 图谱可视化。\n\n#### H. 系统词典（System Dictionary）\n- 职责：统一术语名、定义、约束、正负例和别名，给意图增强和内容生成提供术语语义底座。\n- 接口：`upsertTerm()`、`searchTerm()`、`injectTerms()`、`mergeTerms()`。\n- 依赖：B 存储、C 冲突检测、E 上下文注入、W 系统字典管理。\n\n#### I. 宿主适配层（Host Adapter）\n- 职责：把 OpenClaw 或其他宿主暴露的文件、网络、Provider、事件、通知能力转成稳定 SPI。\n- 接口：`registerHostCapabilities()`、`callProvider()`、`emitHostEvent()`、`readSource()`、`writeExport()`。\n- 依赖：宿主环境本身；被 A、D、F、K、Z 多个域调用。\n\n#### K. 知识管线编排（Knowledge Pipeline Orchestration）\n- 职责：编排提取、分析、分类、冲突检测、合并、入库、图谱更新和缺口检测阶段。\n- 接口：`startPipeline()`、`resumeStage()`、`registerStage()`、`recordStageFailure()`。\n- 依赖：A、L、C、B、G、D、X。\n\n#### L. 分析中间产物（Analysis Artifacts）\n- 职责：保存提取过程中的断言候选、实体候选、冲突候选、缺口候选与审核候选，作为审计与人工介入入口。\n- 接口：`saveArtifact()`、`loadArtifact()`、`approveCandidate()`、`rejectCandidate()`。\n- 依赖：A 输入、K 管线、W 审核界面、X 审计日志。\n\n#### M. 知识域目标声明（Domain Purpose）\n- 职责：定义每个知识域的目标、关键问题、非目标和研究边界，约束提取、检索和调研方向。\n- 接口：`getDomainPurpose()`、`rankAgainstPurpose()`、`validateResearchBoundary()`。\n- 依赖：E 意图增强、D 调研、A 提取路由、W 意图库与域配置界面。\n\n#### W. 知识工作台（Knowledge Workbench）\n- 职责：向用户提供仪表盘、列表、详情、活动流、冲突裁决、调研管理、文档导入、系统字典与意图库。\n- 接口：HTTP API、SSE 事件流、文件上传入口、管理操作入口。\n- 依赖：B、C、D、G、H、L、X、Z。\n\n#### X. 访问控制与可观测性（Access Control & Observability）\n- 职责：统一处理 callerRole、域级权限、操作审计、指标采集、导入导出和故障可观测性。\n- 接口：`authorizeDomainAccess()`、`recordMetric()`、`appendAuditLog()`、`exportKnowledgeSet()`。\n- 依赖：横切所有域；底层依赖 I 提供的持久化和事件能力。\n\n#### Z. 开箱即用与商用就绪（Out-of-Box & Commercial Readiness）\n- 职责：管理安装校验、初始化引导、最小运行模式、配置检查、升级迁移和首次知识旅程。\n- 接口：`runBootstrap()`、`runHealthCheck()`、`loadSeedData()`、`runMigration()`。\n- 依赖：I 宿主适配、W 界面、X 审计、B 数据导入导出。\n\n### 5.2 Level 2：核心模块内部结构\n\n#### 5.2.1 Knowledge Entry Management\n\n```text\nKnowledge Entry Management\n├─ Entry Factory\n├─ Schema Validator\n├─ Version Manager\n├─ Lifecycle Manager\n└─ Link Maintainer\n```\n\n##### Entry Factory\n- 职责：把 Analysis Artifact、手工录入或调研结果转换为统一的 Knowledge Entry 草稿。\n- 接口：`buildDraftFromArtifact()`、`buildDraftFromManualInput()`。\n- 依赖：L 分析中间产物、M 域目标声明。\n\n##### Schema Validator\n- 职责：校验类型、状态、来源引用、metadata 扩展和领域约束，阻止脏数据进入主库。\n- 接口：`validateEntry()`、`validateMetadataExtension()`。\n- 依赖：B 存储模型、H 术语约束、X 访问控制规则。\n\n##### Version Manager\n- 职责：维护版本号、变更摘要、supersedes 关系和乐观锁字段 `expectedVersion`。\n- 接口：`createNextVersion()`、`diffVersions()`、`checkOptimisticLock()`。\n- 依赖：B 持久化、C 冲突治理。\n\n##### Lifecycle Manager\n- 职责：驱动 pending、active、superseded、deprecated、archived 的状态流转。\n- 接口：`activateEntry()`、`supersedeEntry()`、`deprecateEntry()`、`archiveEntry()`。\n- 依赖：C 过期清理、W 条目操作、X 审计日志。\n\n##### Link Maintainer\n- 职责：维护 supplements、supersedes、conflicts、depends_on 等关系，并把关系同步给图谱。\n- 接口：`linkEntries()`、`unlinkEntries()`、`syncGraphEdges()`。\n- 依赖：G 图谱、C 合并策略、B 检索索引。\n\n#### 5.2.2 Intent Routing & Context Injection\n\n这里的“意图路由”指用户请求进入 KIVO 后，系统决定该请求落入哪个知识域、调用哪种检索策略、是否触发澄清。\n\n```text\nIntent Routing & Context Injection\n├─ Query Analyzer\n├─ Domain Selector\n├─ Retrieval Planner\n├─ Context Packager\n└─ Clarification Advisor\n```\n\n##### Query Analyzer\n- 职责：解析查询文本、识别任务类型、抽取时间/来源/知识类型过滤条件。\n- 接口：`analyzeQuery()`。\n- 依赖：H 术语注册表、M 域目标声明。\n\n##### Domain Selector\n- 职责：根据 query、callerRole 与 domain purpose 选择优先知识域，并执行域外裁剪。\n- 接口：`selectDomains()`、`pruneOutOfScopeEntries()`。\n- 依赖：M 域目标声明、X 访问控制。\n\n##### Retrieval Planner\n- 职责：决定走语义检索、元数据检索还是混合检索；在 Provider 不可用时切到降级路径。\n- 接口：`buildQueryPlan()`、`fallbackToKeywordMode()`。\n- 依赖：B 检索引擎、I Provider Registry。\n\n##### Context Packager\n- 职责：把返回条目压缩成 token 预算内的上下文包，优先保留术语、近期决策和高置信事实。\n- 接口：`packageContext()`、`rankByBudget()`。\n- 依赖：B 检索结果、H 术语注入、C 生命周期状态。\n\n##### Clarification Advisor\n- 职责：在高歧义查询下返回澄清建议，避免系统强行猜测。\n- 接口：`suggestClarification()`、`explainWhyAmbiguous()`。\n- 依赖：E 历史偏好、B 检索结果、M 关键问题集。\n\n#### 5.2.3 Rule Subscription & Distribution\n\n```text\nRule Subscription & Distribution\n├─ Rule Registry\n├─ Subscription Matcher\n├─ Delivery Coordinator\n└─ Distribution Ledger\n```\n\n##### Rule Registry\n- 职责：保存 Rule Entry 正文、适用范围、优先级、生效条件和失效条件。\n- 接口：`createRule()`、`updateRule()`、`listRulesByScope()`。\n- 依赖：B 持久化、C 规则冲突检测。\n\n##### Subscription Matcher\n- 职责：根据 agent、角色、域和场景，计算某次规则变更影响的订阅者集合。\n- 接口：`matchSubscribers()`、`refreshSubscriptions()`。\n- 依赖：X 权限模型、I 宿主 Agent 元数据。\n\n##### Delivery Coordinator\n- 职责：执行拉取优先、推送补充的分发策略；对高优先级规则触发主动通知。\n- 接口：`pushRuleChange()`、`prepareRulePullSnapshot()`。\n- 依赖：I 宿主事件能力、W 管理界面。\n\n##### Distribution Ledger\n- 职责：记录送达目标、目标版本、确认状态、失败原因和重试次数。\n- 接口：`recordDelivery()`、`recordAck()`、`listUndeliveredRules()`。\n- 依赖：X 审计和指标、F 重试策略。\n\n#### 5.2.4 Pipeline Orchestrator\n\n```text\nPipeline Orchestrator\n├─ Stage Registry\n├─ Event Router\n├─ Failure Isolator\n└─ Progress Tracker\n```\n\n##### Stage Registry\n- 职责：注册提取、审核、冲突检测、入库、图谱更新、缺口检测、调研回流等阶段，并声明前后置依赖与可跳过条件。\n- 接口：`registerStage()`、`resolveStagePlan()`、`listEnabledStages()`。\n- 依赖：Z 最小运行模式配置、I 宿主能力、X 审计日志。\n\n##### Event Router\n- 职责：在阶段之间传递 `pipelineId`、事件载荷和上下文状态，保证同一条知识管线按确定顺序推进。\n- 接口：`dispatchStageEvent()`、`resumeFromCheckpoint()`、`fanOutPostCommitEvents()`。\n- 依赖：A 输入层、L 分析中间产物、B 主存储、G 图谱、D 调研。\n\n##### Failure Isolator\n- 职责：把局部失败限制在当前阶段或当前条目，防止一条低质量输入拖垮整批导入或其他并发任务。\n- 接口：`quarantineFailedStage()`、`markRetryableFailure()`、`openManualReviewPath()`。\n- 依赖：X 指标与告警、W 审核界面、I 宿主任务能力。\n\n##### Progress Tracker\n- 职责：记录阶段开始、结束、耗时、重试次数和当前状态，为活动流、审计和恢复执行提供统一真相源。\n- 接口：`startStage()`、`completeStage()`、`snapshotPipeline()`。\n- 依赖：X 审计日志、W 活动流、Z 首次知识旅程引导。\n\n#### 5.2.5 Conflict Resolver\n\n```text\nConflict Resolver\n├─ Candidate Screener\n├─ Semantic Judge\n├─ Strategy Selector\n└─ Rollback Guard\n```\n\n##### Candidate Screener\n- 职责：对新条目做 embedding 粗筛、主题聚类和元数据预过滤，缩小需要精判的候选冲突集合。\n- 接口：`screenCandidates()`、`scoreTopicOverlap()`、`dropIrrelevantPairs()`。\n- 依赖：B 检索索引、H 术语约束、I Embedding Provider。\n\n##### Semantic Judge\n- 职责：对候选冲突对执行语义精判，区分互斥、补充、改写、时间先后和表述差异。\n- 接口：`judgeConflict()`、`classifyContradictionType()`、`explainDecision()`。\n- 依赖：I LLM Provider、L Analysis Artifact、B 历史版本。\n\n##### Strategy Selector\n- 职责：根据冲突类型、来源权重、时间新鲜度和 callerRole 选择自动合并、保留并存、人工裁决或延迟处理策略。\n- 接口：`selectResolutionStrategy()`、`rankSourceAuthority()`、`decideAutoMerge()`。\n- 依赖：M 域目标声明、X 权限与审计、W 冲突裁决界面。\n\n##### Rollback Guard\n- 职责：在自动裁决或合并后保留可恢复快照，发现误判时能回退到上一个稳定版本。\n- 接口：`createResolutionCheckpoint()`、`rollbackResolution()`、`replayConflictFlow()`。\n- 依赖：B Version Manager、X 审计日志、G 图谱关系同步。\n\n### 5.3 构建块之间的主依赖关系\n\n- A 只负责把来源送进 K，不直接写主库。\n- K 是主干调度器，驱动 A → L → C → B → G → D 的事件链。\n- B 是知识资产中心，E、G、H、W 都通过 B 消费知识，而不是直接读原始来源。\n- C 管状态和冲突，所有写入路径都要经过它。\n- F 与 E 分离：F 管必须遵守的规则，E 管当前需要知道的知识。\n- I 提供能力边界，避免 Core 直接粘在 OpenClaw 运行时细节上。\n- X 和 Z 横切所有层，分别管治理质量与可交付性。\n\n---\n\n## 6. 运行时视图（Runtime View）\n\n### 6.1 场景一：知识条目的完整生命周期\n\n#### 触发\n用户上传文档、标记对话片段、提交 URL，或调研任务回流结果。\n\n#### 运行时交互\n1. 输入先进入 A 域，生成统一的 Source Reference。\n2. K 启动新的 pipeline instance，写入 `pipelineId` 和阶段状态。\n3. L 生成 Analysis Artifact，提取断言、实体、概念、候选关联、候选冲突和候选缺口。\n4. 若分析置信度过低，artifact 进入审核队列，条目暂不生成。\n5. Entry Factory 从 artifact 生成 Knowledge Entry draft。\n6. Schema Validator 校验类型、来源、domain、metadata 扩展。\n7. C 的 Conflict Resolver 做粗筛：按 embedding 相似度或元数据主题找候选冲突对。\n8. 若 Provider 可用，进入语义精判；若不可用，保留候选冲突并标记待补判。\n9. 无冲突时，B 保存新条目并生成版本号；有冲突时，按时间优先、来源优先或人工裁决流继续。\n10. Link Maintainer 建立 supplements、supersedes、depends_on、conflicts 等关系。\n11. G 基于新条目和关系更新图谱局部子图。\n12. D 读取新增条目后的图谱与查询未命中信号，判断是否形成新缺口。\n13. X 记录整条链路的审计日志、指标和耗时。\n14. W 的活动流收到事件，用户可在界面里看到“导入完成”“待确认”“冲突待裁决”等状态。\n15. 后续若条目长时间未被引用或被外部验证为过时，C 把它从 active 转为 deprecated，再在清理周期后归档。\n\n#### 结果\n- 正常路径：条目进入 active，可检索、可关联、可注入。\n- 低置信路径：条目进入 pending，等待人工确认。\n- 冲突路径：生成 Conflict Record，并暂停到裁决完成。\n- 过时路径：条目退出主检索结果，但历史版本仍可追踪。\n\n### 6.2 场景二：意图路由的请求处理流程\n\n#### 触发\nAgent 在处理用户请求前调用 `prepareContext()` 或直接发起 `queryKnowledge()`。\n\n#### 运行时交互\n1. E 的 Query Analyzer 解析查询文本，提取关键词、语义主题、时间限定、知识类型限定和 domain 候选。\n2. X 根据 callerRole 裁剪可访问知识域。\n3. Domain Selector 结合 M 的域目标声明，选出优先查询域与排除域。\n4. Retrieval Planner 判断当前 Provider 能力：\n - 有 embedding 能力：走混合检索。\n - 无 embedding 能力：走关键词 + 元数据过滤降级路径。\n5. B 执行检索，返回候选条目、相关度评分、来源、版本状态和图谱邻居摘要。\n6. H 查询与当前主题高度相关的术语条目，按 scope 和 token 预算裁剪。\n7. Context Packager 组装上下文包：术语 → 最新决策 → 高置信事实 → 相关经验 → 补充方法。\n8. 如果结果分散且置信度低，Clarification Advisor 返回澄清建议，例如“你要的是安装路径，还是迁移策略”。\n9. E 把最终上下文包返回给 Agent，Agent 再进入自己的任务执行流程。\n10. 若本次查询未命中或结果质量低，X 记录 miss 信号，D 后续可把它纳入缺口检测。\n\n#### 结果\n- 命中路径：Agent 获得按预算压缩后的高相关上下文。\n- 降级路径：返回结果带有 `degraded=true` 标记，便于上层知道当前依赖关键词检索。\n- 歧义路径：系统优先返回澄清建议，不直接给出高风险结论。\n\n### 6.3 场景三：规则订阅的触发与分发\n\n#### 触发\n治理文件变更、手工新增 Rule Entry，或已有规则的优先级与适用范围变化。\n\n#### 运行时交互\n1. A 的规则提取入口接收到 AGENTS.md、SOUL.md 或规则配置变更。\n2. L 产出规则类分析结果，提取规则正文、作用域、优先级、前置条件和覆盖关系候选。\n3. F 的 Rule Registry 创建新版本 Rule Entry。\n4. C 检查规则冲突：同一场景下是否出现相互矛盾的约束。\n5. Subscription Matcher 计算受影响的订阅者集合，依据包括 agentId、角色、域、场景标签。\n6. Delivery Coordinator 判断分发方式：\n - 普通规则：下一次拉取时获取。\n - 高优先级规则：立即推送通知。\n7. I 通过宿主事件能力把变更送到目标 Agent 或共享快照存储。\n8. Distribution Ledger 记录本次分发的目标版本、成功数、失败数、未确认数。\n9. 目标 Agent 启动时或收到事件后执行 `pullRules()`，并回写确认状态。\n10. 若超过重试阈值仍未确认，X 触发告警并在 Workbench 活动流中显示异常。\n\n#### 结果\n- 规则可追溯地送达到订阅者。\n- 失败分发不会污染普通知识检索路径。\n- 用户能在 Workbench 里看到哪些 Agent 还未拿到新规则版本。\n\n### 6.4 场景四：知识质量审计流程\n\n#### 触发\n定时审计、用户主动发起审计、升级前自检，或某个域连续出现检索未命中与冲突堆积。\n\n#### 运行时交互\n1. W 发起“运行知识审计”操作，或系统按计划触发 Audit Job。\n2. X 聚合近一段时间的核心信号：检索命中率、pending 数量、冲突积压、分发失败、图谱孤立节点占比。\n3. 审计器按域扫描 B 中的条目状态，检查是否存在：\n - 无来源引用的 active 条目。\n - 长期 pending 未处理条目。\n - superseded 关系断裂。\n - deprecated 但仍频繁被注入的条目。\n4. G 输出结构洞察，识别近期新增但未形成关联的知识簇。\n5. D 根据审计缺口生成候选调研任务，但默认先进入建议态，不直接抢占资源执行。\n6. 审计结果汇总成 Audit Report，按问题类型分级：P0 数据一致性、P1 检索有效性、P2 可观测性、P3 体验问题。\n7. W 展示可操作清单，用户可直接进入冲突裁决、条目清理、调研创建或规则修复。\n8. X 把审计结论写入审计日志，用于后续趋势分析。\n\n#### 结果\n- 系统知道知识库“有没有东西”，也知道“这些东西好不好用”。\n- 审计输出直接联动修复动作，不停留在静态报告。\n\n### 6.5 场景五：首次知识旅程\n\n#### 触发\n外部陌生用户首次打开空库环境，系统已经完成安装与基础配置校验。\n\n#### 运行时交互\n1. Z 的 `runBootstrap()` 检查 workspace 可写、存储 schema 就绪、文本 LLM 可用、Workbench basePath 正常。\n2. W 渲染空库首页，展示“上传文档”“导入示例数据”“手动新建知识”三个入口和系统就绪度清单。\n3. 用户选择任一入口后，A 把输入转换成统一的 Extraction Input，并为这次首次旅程打上 `journey=first-run` 标记。\n4. K 创建新的 pipeline instance，Progress Tracker 把当前进度同步到 Activity Stream。\n5. L 生成首批 Analysis Artifact，若结果置信度过低，则把候选项送入 Pending Queue，并在界面提示用户先确认一条示例知识。\n6. C 执行最小冲突检查，避免示例数据或首次导入内容和已存在种子数据重复冲突。\n7. B 保存首批 active 条目，并在必要时为缺失 embedding 的条目标记待补建索引。\n8. G 为首批条目建立基础关系，生成可浏览的最小知识子图。\n9. W 自动跳转到知识列表或刚导入条目的详情页，给出一次预填的搜索建议。\n10. 用户执行第一次检索，E 调用 Query Analyzer、Domain Selector 和 Retrieval Planner 生成查询计划。\n11. B 返回命中结果后，W 在结果页展示来源、类型、状态和关联摘要；若未命中，则 Z 提供下一步动作建议，而不是空白页。\n12. X 记录首次知识旅程耗时、卡点阶段和成功率，供后续引导优化使用。\n\n#### 结果\n- 成功路径：用户在 10 分钟内完成首次导入、看到结果并完成第一次检索命中。\n- 待确认路径：系统仍能给出明确下一步动作，用户不会卡在空库状态。\n- 降级路径：当 embedding 或实时能力缺失时，系统显式提示当前运行在最小模式，但核心旅程仍可完成。\n\n---\n\n## 7. 部署视图（Deployment View）\n\n### 7.1 OpenClaw 插件部署拓扑\n\n```text\n┌────────────────────────────────────────────┐\n│ Browser / Workbench Client │\n│ - Dashboard / Search / Graph / Review │\n└─\n\nArchive v0.5.4: 2 files, 596 bytes\n\nFiles: SKILL.md (312b), _meta.json (123b)\n\nArchive v0.4.0: 440 files, 525892 bytes\n\nFiles: dist/adapter/host-adapter.d.ts (1225b), dist/adapter/host-adapter.js (279b), dist/adapter/index.d.ts (423b), dist/adapter/index.js (151b), dist/adapter/llm-provider.d.ts (122b), dist/adapter/llm-provider.js (51b), dist/adapter/openclaw-adapter.d.ts (1308b), dist/adapter/openclaw-adapter.js (1699b), dist/adapter/standalone-adapter.d.ts (1345b), dist/adapter/standalone-adapter.js (1331b), dist/association/association-store.d.ts (866b), dist/association/association-store.js (5441b), dist/association/association-types.d.ts (461b), dist/association/association-types.js (56b), dist/association/index.d.ts (189b), dist/association/index.js (92b), dist/auth/audit-logger.d.ts (701b), dist/auth/audit-logger.js (1220b), dist/auth/auth-types.d.ts (1266b), dist/auth/auth-types.js (486b), dist/auth/index.d.ts (585b), dist/auth/index.js (380b), dist/auth/permission-checker.d.ts (555b), dist/auth/permission-checker.js (762b), dist/auth/session-manager.d.ts (648b), dist/auth/session-manager.js (1965b), dist/auth/user-store.d.ts (981b), dist/auth/user-store.js (2710b), dist/bootstrap/bootstrap-runner.d.ts (1338b), dist/bootstrap/bootstrap-runner.js (9665b), dist/bootstrap/index.d.ts (230b), dist/bootstrap/index.js (146b), dist/bootstrap/init-detector.d.ts (645b), dist/bootstrap/init-detector.js (2216b), dist/cli/capabilities.d.ts (693b), dist/cli/capabilities.js (1703b), dist/cli/health-check.d.ts (451b), dist/cli/health-check.js (4659b), dist/cli/index.d.ts (126b), dist/cli/index.js (2886b), dist/cli/init.d.ts (245b), dist/cli/init.js (3196b), dist/config.d.ts (600b), dist/config.js (630b), dist/config/config-validator.d.ts (459b), dist/config/config-validator.js (2310b), dist/config/env-loader.d.ts (347b), dist/config/env-loader.js (2266b), dist/config/index.d.ts (341b), dist/config/index.js (255b), dist/config/types.d.ts (810b), dist/config/types.js (260b), dist/conflict/conflict-detector.d.ts (2119b), dist/conflict/conflict-detector.js (6247b), dist/conflict/conflict-record.d.ts (501b), dist/conflict/conflict-record.js (103b), dist/conflict/conflict-resolver.d.ts (617b), dist/conflict/conflict-resolver.js (2024b), dist/conflict/index.d.ts (488b), dist/conflict/index.js (185b), dist/conflict/spi.d.ts (661b), dist/conflict/spi.js (144b), dist/dictionary/dictionary-service.d.ts (2399b), dist/dictionary/dictionary-service.js (12270b), dist/dictionary/index.d.ts (1067b), dist/dictionary/index.js (472b), dist/dictionary/term-conflict-checker.d.ts (1303b), dist/dictionary/term-conflict-checker.js (4757b), dist/dictionary/term-importer.d.ts (1314b), dist/dictionary/term-importer.js (9609b), dist/dictionary/term-injection-strategy.d.ts (1677b), dist/dictionary/term-injection-strategy.js (4492b), dist/dictionary/term-search.d.ts (1019b), dist/dictionary/term-search.js (2652b), dist/dictionary/term-types.d.ts (2487b), dist/dictionary/term-types.js (451b), dist/distribution/distribution-types.d.ts (1995b), dist/distribution/distribution-types.js (604b), dist/distribution/index.d.ts (396b), dist/distribution/index.js (90b) (+40 more)\n\nArchive v0.3.1: 402 files, 428888 bytes\n\nFiles: dist/adapter/host-adapter.d.ts (1225b), dist/adapter/host-adapter.js (279b), dist/adapter/index.d.ts (423b), dist/adapter/index.js (151b), dist/adapter/llm-provider.d.ts (122b), dist/adapter/llm-provider.js (51b), dist/adapter/openclaw-adapter.d.ts (1308b), dist/adapter/openclaw-adapter.js (1699b), dist/adapter/standalone-adapter.d.ts (1345b), dist/adapter/standalone-adapter.js (1331b), dist/association/association-store.d.ts (866b), dist/association/association-store.js (5441b), dist/association/association-types.d.ts (461b), dist/association/association-types.js (56b), dist/association/index.d.ts (189b), dist/association/index.js (92b), dist/auth/audit-logger.d.ts (701b), dist/auth/audit-logger.js (1220b), dist/auth/auth-types.d.ts (1266b), dist/auth/auth-types.js (486b), dist/auth/index.d.ts (585b), dist/auth/index.js (380b), dist/auth/permission-checker.d.ts (555b), dist/auth/permission-checker.js (762b), dist/auth/session-manager.d.ts (648b), dist/auth/session-manager.js (1965b), dist/auth/user-store.d.ts (981b), dist/auth/user-store.js (2710b), dist/bootstrap/bootstrap-runner.d.ts (1338b), dist/bootstrap/bootstrap-runner.js (9665b), dist/bootstrap/index.d.ts (230b), dist/bootstrap/index.js (146b), dist/bootstrap/init-detector.d.ts (645b), dist/bootstrap/init-detector.js (2216b), dist/cli/capabilities.d.ts (693b), dist/cli/capabilities.js (1703b), dist/cli/health-check.d.ts (451b), dist/cli/health-check.js (4659b), dist/cli/index.d.ts (126b), dist/cli/index.js (2886b), dist/cli/init.d.ts (245b), dist/cli/init.js (3196b), dist/config.d.ts (600b), dist/config.js (630b), dist/config/config-validator.d.ts (459b), dist/config/config-validator.js (2310b), dist/config/env-loader.d.ts (347b), dist/config/env-loader.js (2266b), dist/config/index.d.ts (341b), dist/config/index.js (255b), dist/config/types.d.ts (810b), dist/config/types.js (260b), dist/conflict/conflict-detector.d.ts (2119b), dist/conflict/conflict-detector.js (6247b), dist/conflict/conflict-record.d.ts (501b), dist/conflict/conflict-record.js (103b), dist/conflict/conflict-resolver.d.ts (617b), dist/conflict/conflict-resolver.js (2024b), dist/conflict/index.d.ts (488b), dist/conflict/index.js (185b), dist/conflict/spi.d.ts (661b), dist/conflict/spi.js (144b), dist/dictionary/dictionary-service.d.ts (2399b), dist/dictionary/dictionary-service.js (12270b), dist/dictionary/index.d.ts (1067b), dist/dictionary/index.js (472b), dist/dictionary/term-conflict-checker.d.ts (1303b), dist/dictionary/term-conflict-checker.js (4757b), dist/dictionary/term-importer.d.ts (1314b), dist/dictionary/term-importer.js (9609b), dist/dictionary/term-injection-strategy.d.ts (1677b), dist/dictionary/term-injection-strategy.js (4492b), dist/dictionary/term-search.d.ts (1019b), dist/dictionary/term-search.js (2652b), dist/dictionary/term-types.d.ts (2487b), dist/dictionary/term-types.js (451b), dist/distribution/distribution-types.d.ts (1995b), dist/distribution/distribution-types.js (604b), dist/distribution/index.d.ts (396b), dist/distribution/index.js (90b) (+2 more)","readmeExcerpt":"Skill: KIVO Owner: yuchangxu1989-openclaw Summary: Agent 知识平台 — 覆盖知识提取、存储、检索、迭代、调研闭环的完整生命周期 Tags: latest:1.11.0 Version history: v1.11.0 | 2026-05-04T05:40:51.087Z | auto - Bumped version to 1.11.0 in SKILL.md. v1.10.0 | 2026-05-04T05:25:22.451Z | auto - 更新了描述，强调了知识平台覆盖的全生命周期闭环 - 版本号从 1.9.0 升级至 1.10.0 - 文档大幅精简，仅保留名称和一句简要介绍 v1.9.0 | 2026-05-04T04:02:47.244Z | auto - Major simplification: removed legacy components and ","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"npm install @self-evolving-harness/kivo\nnpx kivo init"},{"language":"bash","snippet":"npm install @self-evolving-harness/kivo"},{"language":"typescript","snippet":"import { KnowledgeStore, ExtractionPipeline } from '@self-evolving-harness/kivo';\n\nconst store = new KnowledgeStore({ dbPath: './knowledge.db' });\nconst pipeline = new ExtractionPipeline({ store });\nawait pipeline.extract(document);"},{"language":"bash","snippet":"npx kivo init # Initialize knowledge base\nnpx kivo health # Health check\nnpx kivo capabilities # Show capabilities"},{"language":"bash","snippet":"# 从文件摄入\ntsx scripts/ingest.ts --file ./docs/design.md --source \"design-doc\"\n\n# 从文本摄入\ntsx scripts/ingest.ts --text \"用户偏好短答，先结论后证据\" --source \"conversation\""},{"language":"bash","snippet":"# 为查询注入相关上下文\ntsx scripts/inject.ts --query \"当前用户请求\" [--budget ]\n\n# 指定注入格式\ntsx scripts/inject.ts --query \"设计决策\" --format markdown --budget 3000"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: kivo\ndescription: \"Agent 知识平台 — 覆盖知识提取、存储、检索、迭代、调研闭环的完整生命周期\"\nversion: 1.11.0\n---\n# KIVO\nAgent 知识平台。"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn71kk78dbbgtentzcetv7d1zn8536vd\",\n \"slug\": \"kivo\",\n \"version\": \"1.11.0\",\n \"publishedAt\": 1777873251087\n}"},{"path":"skill-card.md","content":"## Description:\n\nKIVO is an agent knowledge platform covering knowledge extraction, storage, retrieval, iteration, and research-loop workflows.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[yuchangxu1989-openclaw](https://clawhub.ai/user/yuchangxu1989-openclaw)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use KIVO as guidance for knowledge-platform workflows across extraction, storage, retrieval, iteration, and research-loop activities.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill description is Chinese-language, which may be misunderstood by readers who cannot review Chinese text directly.\n\nMitigation: Have a Chinese-proficient reviewer confirm the intended use and wording before relying on the skill in production workflows.\n\nRisk: The artifact is minimal descriptive guidance rather than an executable integration.\n\nMitigation: Review the artifact contents and add implementation-specific documentation before treating it as an operational knowledge-platform workflow.\n\n## Reference(s):\n\n- [ClawHub KIVO skill page](https://clawhub.ai/yuchangxu1989-openclaw/skills/kivo)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, guidance]\n\n**Output Format:** [Markdown or plain text guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [The inspected artifact contains descriptive skill text only and no commands, scripts, credential handling, network calls, or persistence mechanisms.]\n\n## Skill Version(s):\n\n1.11.0 (source: SKILL.md frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Agent 知识平台 — 覆盖知识提取、存储、检索、迭代、调研闭环的完整生命周期 Skill: KIVO Owner: yuchangxu1989-openclaw Summary: Agent 知识平台 — 覆盖知识提取、存储、检索、迭代、调研闭环的完整生命周期 Tags: latest:1.11.0 Version history: v1.11.0 | 2026-05-04T05:40:51.087Z | auto - Bumped version to 1.11.0 in SKILL.md. v1.10.0 | 2026-05-04T05:25:22.451Z | auto - 更新了描述，强调了知识平台覆盖的全生命周期闭环 - 版本号从 1.9.0 升级至 1.10.0 - 文档大幅精简，仅保留名称和一句简要介绍 v1.9.0 | 2026-05-04T04:02:47.244Z | auto - Major simplification: removed legacy components and","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":687,"uniquenessScore":62,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T22:46:14.361Z","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-10T22:46:14.361Z","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-11T01:49:47.953Z","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"}]}}}