{"id":"7b84a4f0-2f94-4774-8923-f8ef344a61d9","entityType":"agent","slug":"clawhub-kaisersong-kai-business-blueprint","name":"Business Blueprint Skill","canonicalUrl":"https://www.xpersona.co/agent/clawhub-kaisersong-kai-business-blueprint","canonicalPath":"/agent/clawhub-kaisersong-kai-business-blueprint","generatedAt":"2026-10-11T14:17:03.787Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T10:37:35.978Z","emptyReason":null},"description":"Use when turning presales requirements, meeting notes, or solution materials into editable business capability blueprints, swimlane flows, and application ar... Skill: Business Blueprint Skill Owner: kaisersong Summary: Use when turning presales requirements, meeting notes, or solution materials into editable business capability blueprints, swimlane flows, and application ar... Tags: latest:0.15.0 Version history: v0.15.0 | 2026-04-30T14:17:32.981Z | user Domain-knowledge blueprints now produce product-grade strategy names (统一归因模型 vs 测款节奏). Adds namingHints to cross-border-e","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17e36cy6y9drqxrb49xdqh05d83hqde:kai-business-blueprint","sourceUrl":"https://clawhub.ai/kaisersong/kai-business-blueprint","homepage":"https://clawhub.ai/kaisersong/skills/kai-business-blueprint","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/kaisersong/kai-business-blueprint","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/kaisersong/skills/kai-business-blueprint","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Use when turning presales requirements, meeting notes, or solution materials into editable business capability blueprints, swimlane flows, and application ar..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T10:37:35.978Z","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-11T10:37:35.978Z","emptyReason":null},"stars":null,"forks":null,"downloads":1086,"packageName":null,"latestVersion":"0.15.0","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T10:37:35.959Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T10:37:35.978Z","lastCrawledAt":"2026-10-11T10:37:35.959Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T10:37:35.959Z","lastVerifiedAt":null,"highlights":[{"version":"0.15.0","createdAt":"2026-04-30T14:17:32.981Z","changelog":"Domain-knowledge blueprints now produce product-grade strategy names (统一归因模型 vs 测款节奏). Adds namingHints to cross-border-ecommerce seed + refine prompt + SKILL.md. Documents pass-through fields painPoint.audience and metric.forecast.","fileCount":140,"zipByteSize":400572},{"version":"0.14.1","createdAt":"2026-04-30T08:54:56.371Z","changelog":"Regenerate demo SVG to reflect free-flow Bezier rendering; prune superseded plan.","fileCount":139,"zipByteSize":396353},{"version":"0.14.0","createdAt":"2026-04-29T11:16:36.258Z","changelog":"Domain-knowledge blueprints (痛点/策略/规则/指标/实践/误区) with three quality-driven mechanisms: clarification turn (validator requires >=3 entity-targeted clarifyRequests), per-entity self-check (entities surface own uncertainty as ? glyph), and --refine command (LLM emits structured diff applied to new revision). New cross-border-ecommerce industry pack (depth-validated). Knowledge SVG renderer uses three-band layout with row alignment, capsule cards, three-tier opacity, cubic Bezier connections. Free-flow arrows also switch to Bezier. 67 new unit tests, 85 total. All v2 fields optional - architecture blueprints unchanged.","fileCount":112,"zipByteSize":330606},{"version":"0.12.0","createdAt":"2026-04-24T11:57:39.770Z","changelog":"Export audit trail (generation-prompt-*.md), dynamic SVG column spacing, arrow label overlap fix, system color consistency","fileCount":78,"zipByteSize":197279},{"version":"0.10.0","createdAt":"2026-04-21T10:44:28.378Z","changelog":"Quality hardening release with explicit export routing, SVG integrity diagnostics, eval fixtures, cross-platform CLI fixes, and evolution timeline rendering fixes.","fileCount":75,"zipByteSize":186262},{"version":"0.9.0","createdAt":"2026-04-21T04:12:27.290Z","changelog":"Add canonical projection generation, prompt-native orchestration docs, freeflow fallback rules, and upgraded SVG export quality.","fileCount":59,"zipByteSize":160361},{"version":"0.8.0","createdAt":"2026-04-20T08:59:38.413Z","changelog":"Rename skill to kai-business-blueprint. Updated docs, GitHub URLs, and install paths.","fileCount":52,"zipByteSize":128438}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17e36cy6y9drqxrb49xdqh05d83hqde:kai-business-blueprint","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-kaisersong-kai-business-blueprint/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-business-blueprint/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-business-blueprint/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-business-blueprint/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-business-blueprint/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-business-blueprint/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-11T14:17:03.783Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-business-blueprint/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-business-blueprint/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-business-blueprint/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaisersong-kai-business-blueprint/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-11T10:37:35.978Z","emptyReason":null},"readme":"Skill: Business Blueprint Skill\n\nOwner: kaisersong\n\nSummary: Use when turning presales requirements, meeting notes, or solution materials into editable business capability blueprints, swimlane flows, and application ar...\n\nTags: latest:0.15.0\n\nVersion history:\n\nv0.15.0 | 2026-04-30T14:17:32.981Z | user\n\nDomain-knowledge blueprints now produce product-grade strategy names (统一归因模型 vs 测款节奏). Adds namingHints to cross-border-ecommerce seed + refine prompt + SKILL.md. Documents pass-through fields painPoint.audience and metric.forecast.\n\nv0.14.1 | 2026-04-30T08:54:56.371Z | user\n\nRegenerate demo SVG to reflect free-flow Bezier rendering; prune superseded plan.\n\nv0.14.0 | 2026-04-29T11:16:36.258Z | user\n\nDomain-knowledge blueprints (痛点/策略/规则/指标/实践/误区) with three quality-driven mechanisms: clarification turn (validator requires >=3 entity-targeted clarifyRequests), per-entity self-check (entities surface own uncertainty as ? glyph), and --refine command (LLM emits structured diff applied to new revision). New cross-border-ecommerce industry pack (depth-validated). Knowledge SVG renderer uses three-band layout with row alignment, capsule cards, three-tier opacity, cubic Bezier connections. Free-flow arrows also switch to Bezier. 67 new unit tests, 85 total. All v2 fields optional - architecture blueprints unchanged.\n\nv0.12.0 | 2026-04-24T11:57:39.770Z | user\n\nExport audit trail (generation-prompt-*.md), dynamic SVG column spacing, arrow label overlap fix, system color consistency\n\nv0.10.0 | 2026-04-21T10:44:28.378Z | user\n\nQuality hardening release with explicit export routing, SVG integrity diagnostics, eval fixtures, cross-platform CLI fixes, and evolution timeline rendering fixes.\n\nv0.9.0 | 2026-04-21T04:12:27.290Z | user\n\nAdd canonical projection generation, prompt-native orchestration docs, freeflow fallback rules, and upgraded SVG export quality.\n\nv0.8.0 | 2026-04-20T08:59:38.413Z | user\n\nRename skill to kai-business-blueprint. Updated docs, GitHub URLs, and install paths.\n\nArchive index:\n\nArchive v0.15.0: 140 files, 400572 bytes\n\nFiles: demos/common.blueprint.json (23013b), demos/finance.blueprint.json (6005b), demos/manufacturing.blueprint.json (6161b), demos/retail.blueprint.json (5058b), demos/screenshots/retail-arch.svg (9274b), evals/defect-taxonomy.json (313b), evals/export-integrity-thresholds.json (145b), evals/export-scoring-schema.json (352b), evals/fixtures/route-architecture.json (359b), evals/fixtures/route-evolution.json (381b), evals/fixtures/route-freeflow.json (234b), evals/README.md (1064b), plans/2026-04-28-domain-knowledge-v2.md (56286b), PURE_SKILL_CLEANUP.md (11296b), README.md (18735b), README.zh-CN.md (16512b), REFACTOR_SUMMARY.md (6409b), references/architecture-design-system.md (6986b), references/architecture-diagram-design.md (11111b), references/architecture-templates/microservices.md (2441b), references/architecture-templates/serverless.md (2305b), references/authoring-rules.md (256b), references/blueprint-schema.md (231b), references/blueprint-skill-optimization-proposal.md (18110b), references/domain-knowledge-design-adversarial-review.md (22970b), references/domain-knowledge-design-v2.md (22113b), references/domain-knowledge-entities-extension-design.md (47457b), references/domain-knowledge-test-eval-design.md (29292b), references/entities-schema.md (5653b), references/implementation-plan.md (12463b), references/industry-packs.md (254b), references/knowledge-entities-schema.md (4017b), references/knowledge-self-check.md (2603b), references/layout-quality-check.md (2428b), references/prompt-orchestration-templates.md (8925b), references/schema-refactor-proposal.md (16318b), references/schema-refactor-v2-actionable.md (29130b), references/systems-schema.md (3162b), references/test-and-eval-strategy.md (34890b), references/theme-dark.md (4505b), references/visual-enhancement-plan.md (9770b), reports/phase0_final_report.json (1826b), reports/phase0_migration_report.json (215b), reports/phase1_accuracy_report_fixed.json (2806b), reports/phase1_accuracy_report.json (3622b), reports/phase3_ab_comparison_report.json (3744b), reports/schema-refactor-complete-final-report.md (11630b), reports/schema-refactor-final-evaluation-report.md (12349b), reports/schema-refactor-implementation-report.md (7092b), reports/score.txt (8b), reports/validate.json (29847b), reports/validate.report.md (9502b), scripts/business_blueprint/assets/viewer.html (28441b), scripts/business_blueprint/clarify.py (9747b), scripts/business_blueprint/cli.py (9373b), scripts/business_blueprint/diff_patcher.py (7370b), scripts/business_blueprint/export_drawio.py (644b), scripts/business_blueprint/export_excalidraw.py (710b), scripts/business_blueprint/export_html.py (11555b), scripts/business_blueprint/export_integrity.py (5225b), scripts/business_blueprint/export_knowledge.py (32098b), scripts/business_blueprint/export_mermaid.py (4153b), scripts/business_blueprint/export_routes.py (5332b), scripts/business_blueprint/export_svg.py (150450b), scripts/business_blueprint/export_text.py (2189b), scripts/business_blueprint/export_theme.py (4876b), scripts/business_blueprint/fixtures/baseline/common.svg (24513b), scripts/business_blueprint/fixtures/baseline/finance.svg (10434b), scripts/business_blueprint/fixtures/baseline/manufacturing.svg (10923b), scripts/business_blueprint/fixtures/baseline/retail.svg (9274b), scripts/business_blueprint/generate.py (4026b), scripts/business_blueprint/intent_resolver.py (6870b), scripts/business_blueprint/knowledge_self_check.py (6867b), scripts/business_blueprint/knowledge_validate.py (12699b), scripts/business_blueprint/migrations/v1_to_v2.py (4703b), scripts/business_blueprint/model.py (2131b), scripts/business_blueprint/normalize.py (2651b), scripts/business_blueprint/projection.py (6258b), scripts/business_blueprint/prompt_generator.py (3097b), scripts/business_blueprint/refine.py (7348b)\n\nFile v0.15.0:SKILL.md\n\n---\nname: kai-business-blueprint\ndescription: Use when turning presales requirements, meeting notes, or solution materials into editable business capability blueprints, swimlane flows, and application architecture diagrams. Use when generating blueprint JSON, static HTML viewers, or exporting to SVG, draw.io, Excalidraw, or Mermaid formats. When no standard export template applies, default to free-flow output.\n---\n\n# Business Blueprint Skill\n\nUse the Python scripts in this repository as the execution surface.\n\n## Output Directory\n\nAll generated files (blueprint JSON, viewers, exports) go into `projects/workspace/` — not the repository root.\n\n```bash\npython scripts/business_blueprint/cli.py --plan projects/workspace/solution.blueprint.json --from \"...\"\npython scripts/business_blueprint/cli.py --project projects/workspace/solution.blueprint.json\npython scripts/business_blueprint/cli.py --export projects/workspace/solution.blueprint.json\n```\n\n## Industry Selection\n\nChoose `--industry` from exactly one of: `\"common\"`, `\"finance\"`, `\"manufacturing\"`, `\"retail\"`. Select the closest match based on the user's domain and materials; do not invent other values.\n\n| Industry | Hints content |\n|----------|-------------|\n| `common` | No hints — generic domains |\n| `finance` | Risk control, credit, compliance, customer profile, etc. |\n| `manufacturing` | Production planning, quality, warehouse, supply chain, etc. |\n| `retail` | Store operations, membership, POS, order fulfillment, etc. |\n\n## How to Generate a Blueprint\n\nThe AI agent is responsible for entity extraction. The Python tool handles JSON writing, visualization, and export.\n\n### Step 1: Read industry hints\n\nRead the seed template at `business_blueprint/templates/{industry}/seed.json` and get the `industryHints.checklist`.\n\n### Step 2: Extract entities from source text\n\nUsing the user's source material AND the industry hints checklist, extract:\n- **capabilities**: business capability areas (name, description)\n- **actors**: roles/people involved (name)\n- **flowSteps**: business process steps (name, actorId, capabilityIds, stepType)\n- **systems**: IT systems that support capabilities\n - See `references/entities-schema.md` for all entity field definitions\n - See `references/systems-schema.md` for systems category/layer rules\n - See `scripts/business_blueprint/templates/common/seed.json` for field examples\n\n**Domain-knowledge mode** (when seed has `meta.blueprintType: \"domain-knowledge\"`,\ne.g. `cross-border-ecommerce`): entities go into `library.knowledge.*`\n(painPoints / strategies / rules / metrics / practices / pitfalls), not the\narchitecture buckets above. The seed's `industryHints.knowledgeHints.namingHints`\nsection, when present, dictates content granularity:\n- `strategy.name` must be a 4-10 字 product-grade noun phrase\n (e.g. \"统一归因模型\", \"AIGC 素材工厂\"), not an action (\"优化素材\") or a\n dimension (\"测款节奏\"). Reference the seed's `strategy_named_examples`.\n- `painPoint.audience` and `strategy.audience` are free-string fields tagging\n the primary persona (\"品牌方/DTC\", \"平台卖家\", \"代运营/服务商\"). Multiple\n values comma-separated. No standalone persona entity is required.\n- `metric.forecast: {direction, magnitude, unit}` is optional and used for\n commitments to the customer (\"ROAS 提升 25%\"). Keep `value`/`benchmarkContext`\n for current baseline; the two coexist as \"now X, can reach Y\".\n\nThese fields are pass-through under v2 minimal-validation: the validator does\nnot enforce them, but renderers and pitch flows consume them.\n\n### Step 3: Write the blueprint JSON\n\nWrite the JSON file directly to the output path. Use this schema:\n\n```json\n{\n \"version\": \"1.0\",\n \"meta\": {\n \"title\": \"...\",\n \"industry\": \"retail\",\n \"revisionId\": \"rev-YYYYMMDD-NN\",\n \"parentRevisionId\": null,\n \"lastModifiedAt\": \"ISO8601\",\n \"lastModifiedBy\": \"ai\"\n },\n \"context\": {\n \"goals\": [],\n \"scope\": [],\n \"assumptions\": [],\n \"constraints\": [],\n \"sourceRefs\": [{\"type\": \"inline-text\", \"excerpt\": \"...\"}],\n \"clarifyRequests\": [],\n \"clarifications\": []\n },\n \"library\": {\n \"capabilities\": [\n {\"id\": \"cap-xxx\", \"name\": \"...\", \"level\": 1, \"description\": \"...\", \"ownerActorIds\": [], \"supportingSystemIds\": []}\n ],\n \"actors\": [\n {\"id\": \"actor-xxx\", \"name\": \"...\"}\n ],\n \"flowSteps\": [\n {\"id\": \"flow-xxx\", \"name\": \"...\", \"actorId\": \"actor-xxx\", \"capabilityIds\": [\"cap-xxx\"], \"systemIds\": [], \"stepType\": \"task\", \"inputRefs\": [], \"outputRefs\": []}\n ],\n \"systems\": [\n {\"id\": \"sys-xxx\", \"kind\": \"system\", \"name\": \"...\", \"aliases\": [], \"description\": \"...\", \"resolution\": {\"status\": \"canonical\", \"canonicalName\": \"...\"}, \"capabilityIds\": [\"cap-xxx\"]}\n ]\n },\n \"relations\": [\n {\"id\": \"rel-xxx\", \"type\": \"supports\", \"from\": \"sys-xxx\", \"to\": \"cap-xxx\", \"label\": \"支撑\"}\n ],\n \"views\": [],\n \"editor\": {\"fieldLocks\": {}, \"theme\": \"enterprise-default\"},\n \"artifacts\": {}\n}\n```\n\n### Step 4: Generate visualizations\n\n```bash\npython scripts/business_blueprint/cli.py --export \n```\n\nThis generates SVG + HTML viewer by default. Use `--format drawio|excalidraw|mermaid` for other formats.\n\n## Export View Selection Policy\n\nTreat export view choice as a routing decision, not a styling preference.\n\n- If a request matches a supported, standard export template, use that template.\n- If there is no standard export template for the requested diagram, fall back to `freeflow`.\n- Do **not** substitute `swimlane`, `matrix`, `product tree`, or other generic views just because they are available.\n- When embedding a blueprint diagram into a report or ad hoc analysis, `freeflow` is the safe default unless the user explicitly asks for a supported standard template.\n\n### Step 5: Generate downstream projection\n\n```bash\npython scripts/business_blueprint/cli.py --project \n```\n\nThis generates `solution.projection.json`, the canonical machine projection consumed by downstream report/slide workflows.\n\n## Workflow Decision Tree\n\n```\nUser provides raw requirements / meeting notes?\n → AI agent reads hints, extracts entities, writes blueprint JSON\n → Optionally run --project for downstream machine handoff\n → Then run --export for visualization\n\nUser needs diagram files (SVG, draw.io, etc.)?\n → --export (default: SVG + HTML viewer)\n\nUser unsure about blueprint quality?\n → --validate\n\nUser wants downstream report / slide generation?\n → --project\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `--plan --from ` | Generate empty blueprint JSON from source text (AI should prefer writing JSON directly) |\n| `--project ` | Generate canonical projection JSON for downstream skills |\n| `--export ` | Export SVG + HTML viewer (default), or use `--format` for other formats |\n| `--validate ` | Validate a blueprint and print JSON results |\n\n**Execution**: Run directly as scripts:\n```bash\npython scripts/business_blueprint/cli.py --plan ...\npython scripts/business_blueprint/cli.py --export ...\n```\n\n## Export Formats\n\n| Format | File | Use Case |\n|--------|------|----------|\n| `svg` (default) | `solution.exports/solution.svg` + HTML viewer | Quick preview, embedding |\n| `drawio` | `solution.exports/solution.drawio` | Editable diagrams |\n| `excalidraw` | `solution.exports/solution.excalidraw` | Whiteboard-style diagrams |\n| `mermaid` | `solution.exports/solution.mermaid.md` | GitHub-native rendering |\n\n## Collaboration Boundary\n\nThis skill produces **semantic intermediate artifacts**. Downstream skills consume them:\n\n- `report-creator` consumes `solution.projection.json` → assembles reports\n- `slide-creator` consumes `solution.projection.json` → assembles presentations\n- Other skills may consume `relations` → generate PlantUML or other diagram syntax\n- Downstream skills should **never directly edit** `solution.blueprint.json`\n- `solution.handoff.json` is viewer-only metadata, not a downstream narrative input\n\n## Sandbox Execution\n\nWhen running in an isolated Python sandbox (Jupyter, notebook, cloud REPL) that auto-installs dependencies:\n\n1. **The sandbox uses scripts directly.** Run execution scripts from the repository root:\n ```python\n import subprocess\n subprocess.run([\"python\", \"scripts/business_blueprint/cli.py\", \"--export\", \"solution.blueprint.json\"])\n ```\n - `sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))` — will raise NameError\n - `subprocess.run([\"business-blueprint\", ...])` — sandbox runs Python cells, not shell\n - `os.system()` — same reason\n\n## Architecture Diagram Generation\n\nWhen user requests an architecture diagram (keywords: \"架构图\", \"architecture diagram\", \"--export\", \"diagram\"):\n\n1. Read `references/architecture-design-system.md` for the complete design system.\n2. Read the appropriate template from `references/architecture-templates/` based on the user's domain:\n - AWS/Serverless/Lambda → `serverless.md`\n - Microservices/Kubernetes/微服务 → `microservices.md`\n - Other → use `serverless.md` as a structural reference\n3. Read the blueprint JSON to extract entities and flow steps.\n4. Generate a self-contained HTML file with inline SVG following the design system rules.\n5. Write the output file to the same directory as the blueprint JSON.\n\nIf the request does not match one of the supported standard templates above, stay on the default `freeflow` export path. Do not switch to another generic view type as a fallback.\nIf a standard template would create a squeezed, clipped, or overcrowded diagram, stop using the fixed template geometry and fall back to `freeflow` or a wrapped multi-row layout.\n\n### Route eligibility matrix\n\nUse an explicit route contract before rendering:\n\n| Route | Structural prerequisites | First fallback | Terminal behavior |\n|------|---------------------------|----------------|-------------------|\n| `freeflow` | Any valid blueprint with at least one renderable node or relation | None | If integrity still fails, export exits non-zero with a structural diagnostics payload |\n| `architecture-template` | Recognizable L→R architecture shape, categorized systems, limited per-layer density, and no route-breaking overflow risk | `freeflow` | Same as above |\n| `poster` | Clear layer/group structure with bounded peer density per row or wrapped-row support | wrapped poster or `freeflow` | Same as above |\n| `swimlane` | Actor-owned flow steps with meaningful lane grouping | `freeflow` | Same as above |\n| `hierarchy` | Stable tree/group relationship with low ambiguity in parent-child grouping | `freeflow` | Same as above |\n| `evolution` | Ordered chronological or staged progression data | `freeflow` | Same as above |\n\nDo not invent route heuristics ad hoc inside a renderer. Route eligibility must stay explicit and reviewable.\n\n### Generation Rules\n- Use dark mode by default (`#020617` bg + 40px grid). Only use light mode when the user explicitly asks for it.\n- L→R data flow: Clients(左) → Frontend → Backend → Database(右)\n- Map `systems[].category` to semantic colors from the design system\n- Map `systems[].properties.type == \"aws\"` → AWS Region boundary box\n- Map `systems[].properties.type == \"k8s\"` → Kubernetes Cluster boundary box\n- Use `flowSteps[].seqIndex` for L→R ordering\n- Component sizing: 0-1 cap = small(44px h), 2-4 = medium(80px h), 5+ = large(80px h)\n- Layout must be content-driven. Never force every node in a layer into one fixed row if that creates toothpaste-style squeezing.\n- When a layer has more than 3 peer nodes, or labels/features become tight, wrap into multiple rows or widen the canvas before shrinking the content.\n- Render users/actors as actor labels, badges, or lane headers by default. Do not render them as ordinary system cards unless the user explicitly asks for that visual treatment.\n- Legend must live in a bottom safe area and participate in canvas sizing. Never place the legend as a floating overlay in the top-right corner.\n- Final SVG/HTML height must be derived from the bottom-most node, legend, summary cards, and footer plus padding. Do not use fixed-height wrappers or `overflow: hidden` that can clip the last row.\n- Z-order: bg → grid → title → region → arrows → nodes → legend → cards → footer\n- Component border: `rx=\"8\"`, `stroke-width=\"2\"`\n- Region border: `rx=\"16\"`, `stroke-dasharray=\"8,4\"`, `opacity=\"0.4\"`\n- Geometry-sensitive integrity checks must use the numeric thresholds from `evals/export-integrity-thresholds.json`, not prose heuristics.\n\n### Output\n- Single HTML file: `{blueprint_stem}.html` alongside the blueprint JSON\n- No external dependencies (except Google Fonts CDN for JetBrains Mono)\n- Opens in any browser, printable to PDF\n\n## Error Handling\n\n- If `--validate` returns errors: fix structural issues before proceeding to `--export`.\n- If `--validate` returns only warnings: proceed but note the warnings in any handoff.\n- If Python version < 3.12: the package will refuse to install. Use `python3 -m business_blueprint.cli` with system Python as fallback.\n- If a specialized route fails integrity: fall back to its configured fallback route.\n- If `freeflow` also fails integrity: export exits non-zero with a structural diagnostics payload instead of emitting a silently broken artifact.\n\n## Cross-Platform Scope\n\nPhase 2 does not attempt full Windows terminal parity.\n\nKnown deferred cases:\n- PowerShell pipe quirks beyond documented CLI contract tests\n- console-default encoding issues outside explicit UTF-8 execution paths\n\nAccepted workaround for encoding-sensitive runs:\n# Use scripts directly (pure Skill, no package structure)\n subprocess.run([\"python\", \"scripts/business_blueprint/cli.py\", \"--export\", str(blueprint_path)])\n- set `PYTHONIOENCODING=utf-8` where needed\n\nFile v0.15.0:evals/README.md\n\n# Export Evals\n\nThis directory holds machine-readable export quality inputs, thresholds, and taxonomy data for `kai-business-blueprint`.\n\n## Files\n\n- `export-integrity-thresholds.json` — numeric thresholds for geometry-sensitive integrity checks\n- `defect-taxonomy.json` — canonical defect categories used by tests and eval fixtures\n- `export-scoring-schema.json` — minimal scoring/output schema for export eval runs\n\n## Fixtures\n\n- `fixtures/route-freeflow.json` — generic graph that should stay on `freeflow`\n- `fixtures/route-architecture.json` — categorized architecture graph that should resolve to `architecture-template`\n- `fixtures/route-evolution.json` — dated staged flow that should resolve to `evolution`\n\n## Usage\n\n- Route tests read these fixtures to keep export-family decisions stable.\n- Integrity tests should reference taxonomy ids instead of inventing one-off failure labels.\n- Human-readable failure maps, if needed later, should be generated from these files and test references rather than hand-maintained as the source of truth.\n\nFile v0.15.0:README.md\n\n# kai-business-blueprint\n\n> 售前需求、会议纪要、RFP 材料 → 可编辑的业务能力蓝图、泳道流程图、应用架构图。一份 canonical JSON IR，多个下游导出格式（SVG / draw.io / Excalidraw / Mermaid）。\n\nA [Claude Code](https://claude.ai/claude-code) skill that turns raw presales inputs into canonical business capability blueprints, with a static HTML viewer and multi-format diagram exports.\n\nEnglish | [简体中文](README.zh-CN.md)\n\n---\n\n## Demo\n\nRetail industry blueprint, exported as SVG:\n\n![retail-blueprint](demos/screenshots/retail-arch.svg)\n\nThe SVG is generated by `business-blueprint --export demos/retail.blueprint.json` — the source JSON is in `demos/retail.blueprint.json`, the viewer is `demos/solution.viewer.html`.\n\n---\n\n## Design Philosophy: IR-First Pipeline\n\n### 1. JSON as Canonical Intermediate Representation\n\nEvery workflow converges on `solution.blueprint.json` — the single source of truth. All other artifacts (viewer, SVG, draw.io) are deterministic projections from it.\n\n```\nRaw Text ──(--plan)──→ JSON ──(--generate)──→ Viewer HTML\n │\n ├──(--export)──→ SVG / draw.io / Excalidraw / Mermaid\n │\n └──(--edit)────→ JSON (patch logged) + Viewer refresh\n```\n\nThe IR is:\n- **Version-controllable** — standard JSON, diffs are meaningful\n- **AI-readable** — downstream skills parse `entities`, `relations`, `flowSteps` without HTML parsing\n- **Human-editable** — light fields (labels, names) can be edited without breaking structure\n\n### 2. Progressive Disclosure\n\nThe skill file (`SKILL.md`) is a routing layer — it tells Claude *which* file to read for *which* command. Heavy assets (industry packs, viewer HTML template, export engine) stay on disk until needed.\n\n```\n--plan → only model + generation rules; no CSS, no export engine\n--generate → one viewer.html template + one industry pack\n--export → only the requested export engine; other formats stay on disk\n--validate → schema + rules; no rendering code\n```\n\n### 3. Silicon-Carbon Collaboration\n\n**Input:** Humans write natural language (requirements, meeting notes, RFPs). AI parses into structured entities (Application Systems, Business Capabilities, Process Flows, Actors) and relations.\n\n**Output:** The viewer is a static HTML page — no build step, no JS framework, works offline. Every node is editable in-place, and edits are logged as a JSON patch trail (`solution.patch.jsonl`) for full traceability.\n\n---\n\n## Install\n\n### Claude Code\n\n```bash\ngit clone https://github.com/kaisersong/kai-business-blueprint ~/.claude/skills/kai-business-blueprint\n```\n\nThen: `cd kai-business-blueprint && pip install -e .`\n\n### OpenClaw\n\n```bash\ngit clone https://github.com/kaisersong/kai-business-blueprint ~/.openclaw/skills/kai-business-blueprint\ncd kai-business-blueprint && pip install -e .\n```\n\n---\n\n## Usage\n\n### CLI Commands\n\n| Flag | Purpose |\n|------|---------|\n| `--plan \"text\"` | Parse raw text into canonical blueprint JSON |\n| `--project ` | Derive canonical `solution.projection.json` for downstream skills |\n| `--generate ` | Generate JSON + static HTML viewer package |\n| `--edit ` | Refresh viewer for an existing blueprint (preserves human edits) |\n| `--export ` | Export diagrams (default: free-flow SVG + HTML viewer) |\n| `--export-auto ` | Alias for --export (free-flow SVG + HTML viewer) |\n| `--html ` | Generate self-contained HTML viewer with inline SVG |\n| `--validate ` | Validate blueprint structure, output errors/warnings |\n| `--refine ` | Refine an existing blueprint with `--feedback \"...\"` (LLM produces a structured diff that is applied to a new blueprint) |\n| `--from ` | Read source material from file path |\n| `--industry ` | Apply industry template pack (common, finance, manufacturing, retail, **cross-border-ecommerce**) |\n| `--theme ` | Color theme for output (default: dark) |\n| `--format ` | Export format: svg, drawio, excalidraw, mermaid, all |\n\n### Domain-Knowledge Blueprints (v0.14)\n\nBeyond the architecture-style blueprint (capabilities / actors / flowSteps / systems), the skill now produces **domain-knowledge blueprints** for know-how pitches: pain points, strategies, rules, metrics, practices, pitfalls — six entity types tied together by `solves` / `measures` / `enforces` / `requires` / `prevents` / `causes` relations.\n\nA domain-knowledge blueprint is selected by `meta.blueprintType: \"domain-knowledge\"` (set automatically when you choose a know-how-leaning industry such as `cross-border-ecommerce`, or by AI intent extraction). Three quality-driven mechanisms live in the pipeline:\n\n- **Clarification turn.** Validator rejects a domain-knowledge blueprint with fewer than 3 `clarifyRequests`, each pointing to a specific entity. The AI must surface what it is uncertain about before producing the chart.\n- **Per-entity self-check.** Every knowledge entity carries an optional `_selfCheck` field with `passed` / `questions` arrays. Entities with non-empty `questions` are rendered with a soft amber accent and a `?` glyph so reviewers can spot what still needs verification.\n- **Refine command.** `--refine blueprint.json --feedback \"...\"` asks the LLM to emit an `add` / `modify` / `delete` diff which is then applied to produce a new revision. The diff structure is JSON-Patch-like and can be filtered per-operation before applying.\n\nThe knowledge SVG renderer uses a three-band layout: rules across the top, a `pain → strategy → metric` triptych in the middle (rows aligned by `solves` / `measures` so the dominant lines stay near-horizontal), and `practices` + `pitfalls` capsules at the bottom. Cross-zone connections are cubic Bezier; relations are drawn at three opacity tiers so the primary `solves` / `measures` story stays readable even with 30+ relations.\n\n### Export Quality Contracts\n\n- Export routing is explicit: specialized views are only used when the blueprint structure clearly matches them; otherwise the exporter stays on `freeflow`.\n- SVG output now runs structural integrity checks for missing defs references and basic canvas overflow before an artifact is accepted.\n- Export thresholds and defect taxonomy live under [`evals/`](evals), so route and integrity behavior are backed by machine-readable fixtures rather than prose only.\n- Windows/terminal support is intentionally scoped: the canonical path is `python -m business_blueprint.cli`, and encoding-sensitive runs should use `PYTHONIOENCODING=utf-8` when needed.\n\n### Typical Workflows\n\n**From raw text:**\n```bash\n# Step 1: parse into canonical JSON\nbusiness-blueprint --plan \"ERP supports POS system...\" --from meeting-notes.md --industry retail\n\n# Step 2: generate viewer\nbusiness-blueprint --generate solution.blueprint.json\n\n# Step 3: export diagrams\nbusiness-blueprint --export solution.blueprint.json\n```\n\n**Edit existing blueprint:**\n```bash\n# Edit the JSON manually or let AI edit it\n# Then refresh the viewer (preserves human-edited fields via editor.fieldLocks)\nbusiness-blueprint --edit solution.blueprint.json\n```\n\n**Validate before export:**\n```bash\nbusiness-blueprint --validate solution.blueprint.json\n# Fix errors, then:\nbusiness-blueprint --export solution.blueprint.json\n```\n\n**Prepare downstream machine handoff:**\n```bash\nbusiness-blueprint --project solution.blueprint.json\n```\n\n---\n\n## Outputs\n\n| File | Role |\n|------|------|\n| `solution.blueprint.json` | Canonical IR — single source of truth |\n| `solution.projection.json` | Canonical downstream machine projection |\n| `solution.viewer.html` | Static viewer + light editor |\n| `solution.exports/` | SVG, draw.io, Excalidraw, Mermaid exports |\n| `solution.patch.jsonl` | Edit traceability log (JSON patches) |\n| `solution.handoff.json` | Viewer revision manifest |\n\n### SVG Architecture Export\n\nThe SVG export renders a free-flow L→R architecture diagram:\n\n- **Main flow chain** (center row) — systems connected via flow steps, left to right\n- **Auxiliary systems** (rows above/below) — placed by category (database, security, cloud)\n- **Entry node** (left) — auto-generated from blueprint actors\n- **Semantic arrows** — 4 types with distinct colors/markers: `supports` (green solid), `depends-on` (gray dashed), `flows-to` (blue solid), `owned-by` (yellow dotted)\n- **Semantic node shapes** — diamond for flow steps, left color strip for systems, rounded rects for capabilities, pill shapes for actors\n- **Industry themes** — accent color overlays for retail (orange), finance (blue), manufacturing (gray)\n\nThe layout engine computes positions dynamically with overlap resolution, horizontal alignment, and mid-y collision avoidance. The region boundary box and SVG canvas auto-expand to contain all arrow paths.\n\n---\n\n## Project Structure\n\n```\nkai-business-blueprint/\n├── SKILL.md # Skill definition (routing layer)\n├── business_blueprint/ # Python engine (zero external deps)\n│ ├── cli.py # CLI entry point\n│ ├── generate.py # Blueprint generation from text\n│ ├── model.py # Data model & top-level shape\n│ ├── projection.py # Downstream projection builder\n│ ├── validate.py # Machine-readable validation\n│ ├── clarify.py # Clarification request builder\n│ ├── normalize.py # Entity resolution & synonym merging\n│ ├── viewer.py # HTML viewer package writer\n│ ├── export_theme.py # Shared export theme tokens and semantic colors\n│ ├── export_text.py # Shared SVG text width + wrapping helpers\n│ ├── export_routes.py # Explicit export route resolution\n│ ├── export_integrity.py # Structural export integrity checks + diagnostics\n│ ├── export_svg.py # SVG exporter (two-pass layout, content router, free-flow)\n│ ├── export_drawio.py # draw.io exporter\n│ ├── export_excalidraw.py # Excalidraw exporter\n│ ├── export_mermaid.py # Mermaid markdown exporter\n│ ├── templates/ # Industry packs (common, retail, finance, manufacturing)\n│ ├── assets/ # viewer.html template\n│ └── specs/ # Blueprint schema definitions\n├── references/ # Schema, authoring rules, industry packs\n├── tests/ # Test suite\n├── demos/ # Demo blueprints & exports\n└── examples/ # Sample blueprint JSON\n```\n\n---\n\n## Architecture Rules\n\nThe engine enforces structural rules:\n\n| Rule | Description |\n|------|-------------|\n| **Every capability links to a system** | No orphaned capabilities |\n| **Every flow links to a capability** | No floating flow steps |\n| **Actor → System** | Actors must reference valid system IDs |\n| **No circular relations** | System → Capability → Flow must be DAG |\n\nRun `--validate` to check all rules. Warnings indicate potential issues (e.g., a system with no capabilities), errors block export.\n\n---\n\n## For AI Agents\n\nOther skills should consume blueprint artifacts through prompt orchestration, not through the viewer handoff manifest.\n\n```\n# 1. Prepare the machine artifacts\nbusiness-blueprint --plan solution.blueprint.json --from \"...\"\nbusiness-blueprint --project solution.blueprint.json\n\n# 2. Prompt report-creator with the blueprint/projection artifacts\n\"Use solution.blueprint.json and solution.projection.json to generate a report IR first. Do not render HTML yet.\"\n\n# 3. Prompt slide-creator with the blueprint/projection artifacts\n\"Use solution.blueprint.json and solution.projection.json to generate PLANNING.md first. Do not generate HTML yet.\"\n```\n\nSee [references/prompt-orchestration-templates.md](references/prompt-orchestration-templates.md) for copy-paste prompt templates.\n\n`solution.handoff.json` is only a viewer manifest. Do not use it as report/deck input.\n\n**Extracting structured data:**\n```python\nimport json\n\nwith open(\"solution.blueprint.json\") as f:\n bp = json.load(f)\n\n# Systems\nfor sys in bp[\"library\"].get(\"systems\", []):\n print(f\"System: {sys['name']}\")\n\n# Capabilities\nfor cap in bp[\"library\"].get(\"capabilities\", []):\n print(f\"Capability: {cap['name']}\")\n\n# Relations\nfor rel in bp[\"relations\"]:\n print(f\"{rel['from']} --{rel['type']}--> {rel['to']}\")\n```\n\n---\n\n## Requirements\n\n| Requirement | Version | Notes |\n|-------------|---------|-------|\n| **Python** | >= 3.12 | Zero external dependencies |\n\n---\n\n## Compatibility\n\n| Platform | Version | Install path |\n|----------|---------|--------------|\n| Claude Code | any | `~/.claude/skills/kai-business-blueprint/` |\n| OpenClaw | >= 0.9 | `~/.openclaw/skills/kai-business-blueprint/` |\n\n---\n\n## Version History\n\n**v0.14.0** — Domain-knowledge blueprints: add a second blueprint type for know-how pitches (pain points / strategies / rules / metrics / practices / pitfalls) on top of the existing architecture mode. Three quality-driven mechanisms — clarification turn (validator requires ≥3 entity-targeted clarifyRequests), per-entity self-check (entities surface their own uncertainty as a `?` glyph), and `--refine` command (LLM emits a structured diff that is applied to produce a new revision). New `cross-border-ecommerce` industry pack with depth-validated knowledgeHints; existing retail/finance/manufacturing packs gain `knowledgeHints` blocks marked `template-only-not-domain-validated` so AI must disclose the limitation. Knowledge SVG renderer uses a three-band layout (rules / pain-strategy-metric triptych / practices-pitfalls capsules) with row alignment by `solves` / `measures`, cubic Bezier connections, and three-tier opacity so the dominant story stays readable on dense graphs. Free-flow renderer also switches simple connections from straight lines to Bezier. 85 unit tests (67 new) lock the v2 behaviour.\n\n**v0.13.0** — Intent resolution & label overlap fix: integrate `IntentResolver` + `RuleEngine` into the SVG export pipeline so layer assignment becomes data-driven; resolve label-node overlap on free-flow output.\n\n**v0.10.0** — Quality hardening release: add explicit export route resolution and SVG integrity checks with structured fallback diagnostics; introduce machine-readable eval assets under `evals/` (thresholds, defect taxonomy, route fixtures, scoring schema); improve cross-platform CLI handling for spaced paths, CRLF input, and UTF-8 validation output; split shared export text/theme helpers out of `export_svg.py`; and refine the evolution timeline view so dark cards stay readable and wrapped system pills no longer overflow.\n\n**v0.9.0** — Canonical projection release: add `solution.projection.json` generation via `--project`; formalize prompt-native orchestration templates for report/slide downstream skills; strengthen export routing rules so non-standard diagram requests fall back to free-flow; and ship substantial SVG quality upgrades across poster, swimlane, hierarchy, and evolution views, including dark-theme fixes, label collision handling, width-aware title wrapping, centered card rows, and new regression coverage.\n\n**v0.8.0** — Skill rename: rebranded from `business-blueprint-skill` to `kai-business-blueprint`; updated all GitHub URLs, install paths, and documentation references.\n\n**v0.7.0** — Visual enhancements: 4 semantic arrow types (supports/depends-on/flows-to/owned-by) with distinct colors, dash patterns, and SVG markers; semantic node shapes (diamond for flowStep, left color strip for systems, rounded rects for capabilities, pill for actors); 3 industry theme overlays (retail=#F97316, finance=#3B82F6, manufacturing=#6B7280); HTML template-driven viewer generation (replaces 244 lines of f-strings); architecture layout fix — one column per unique capability; free-flow now renders full relation arrows from `blueprint.relations`; same-column arrow routing uses direct vertical paths; region box covers all system nodes; 46 new tests.\n\n**v0.6.1** — Layout engine genericization: remove all hardcoded company/product names (AWS service mappings, Kingdee product IDs, brand text) from layout and rendering code; `_categorize_system()` now uses language-agnostic keyword matching (Chinese + English); `_layout_layered()` assigns distinct colors per layer instead of category keyword lookup; dark theme node colors increased contrast (brighter fills, bolder strokes); legend rendered behind arrows and nodes (z-order fix) so overlaps never obscure content; product tree and capability matrix auto-derive segments from blueprint data instead of hardcoded IDs.\n\n**v0.6.0** — Free-flow layout engine overhaul: arrow routing with cross-row elbow paths and mid_y collision avoidance; dark theme as default; all user-facing labels in Chinese (legend, footer, summary cards); arrowheads shrunk (8×6px, stroke-width 1.5) for cleaner look; region boundary box and SVG canvas dynamically expand to contain arrow paths; rendering z-order fixed (arrows behind nodes); `--html` flag for standalone viewer; `--format` and `--theme` CLI flags; description section from blueprint context; download SVG button.\n\n**v0.5.0** — Content router & free-flow layout engine: `_content_router()` auto-selects views (architecture, capability map, swimlane, process chain) based on blueprint content; `_layout_free_flow()` computes free-form positions with domain grouping and auto-wrapping; `export_svg_auto()` combines routing + layout; `--export-auto` CLI flag; HTML viewer now dynamically shows tabs only for available views.\n\n**v0.4.0** — HTML viewer & layout fix: self-contained HTML viewer with three inline SVG views (architecture, capability map, swimlane), tab-based navigation, summary cards, dark theme support with grid background.\n\n**v0.3.1** — CLI fixes: `--from` long Chinese text no longer triggers `File name too long`, stdin pipe support for `--plan`, subprocess `text=True`/bytes compatibility guidance.\n\n**v0.2.0** — SVG layout engine: two-pass dynamic layer height, actor overflow fix, title/layer gap, header clipping fix, legend truncation fix.\n\n**v0.1.0** — Initial release: plan/generate/edit/export/validate pipeline, HTML viewer with in-place editing, SVG/draw.io/Excalidraw/Mermaid exports, industry template packs (common, retail, finance, manufacturing).\n\nFile v0.15.0:_meta.json\n\n{\n \"ownerId\": \"kn7bjv9d2ccsjqk1m4edthgtgx82fem8\",\n \"slug\": \"kai-business-blueprint\",\n \"version\": \"0.15.0\",\n \"publishedAt\": 1777558652981\n}\n\nFile v0.15.0:references/architecture-design-system.md\n\n# Architecture Diagram Design System\n\n本文件定义 Agent 生成架构图时使用的完整设计系统。所有颜色、字体、间距、布局规则必须严格遵循。\n\n## 1. 主题\n\n### 暗黑模式（默认）\n\n| Token | 值 | 用途 |\n|-------|-----|------|\n| `bg` | `#020617` | 页面背景（Slate-950） |\n| `canvas` | `#0F172A` | 卡片表面（Slate-900） |\n| `text_main` | `#E2E8F0` | 主文字 |\n| `text_sub` | `#94A3B8` | 副文字 |\n| `border` | `#1E293B` | 边框 |\n| `grid` | `#1E293B` | 网格线（40px pattern） |\n\n暗黑模式是默认输出。除非用户明确要求亮色模式，否则不得切换到亮色主题。\n\n### 亮色模式\n\n| Token | 值 | 用途 |\n|-------|-----|------|\n| `bg` | `#F8FAFC` | 页面背景 |\n| `canvas` | `#FFFFFF` | 卡片表面 |\n| `text_main` | `#0F172A` | 主文字 |\n| `text_sub` | `#64748B` | 副文字 |\n| `border` | `#CBD5E1` | 边框 |\n\n## 2. 字体\n\n- 主字体：`'JetBrains Mono', 'Fira Code', monospace`（Google Fonts CDN 引入）\n- 回退字体：`system-ui, -apple-system, sans-serif`\n\n| 层级 | 字号 | 字重 | 用途 |\n|------|------|------|------|\n| 标题 | 20px | 700 | SVG 主标题 |\n| 副标题 | 13px | 400 | 副标题/注解 |\n| 组件名 | 14px | 600 | 节点名称 |\n| 副标签 | 11px | 400 | 节点描述 |\n| 注解 | 9-10px | 400 | 标签、Legend |\n| Region 标签 | 12px | 600 | Region 名称 |\n\n## 3. 语义色\n\n7 种系统类别，每种定义 fill + stroke（暗黑模式值）：\n\n| 类别 | 填充色 | 描边色 | 用途 |\n|------|--------|--------|------|\n| `frontend` | `rgba(8,51,68,0.4)` | `#22d3ee` | Web、移动端、UI |\n| `backend` | `rgba(6,78,59,0.4)` | `#34d399` | Lambda、API、服务 |\n| `database` | `rgba(76,29,149,0.4)` | `#a78bfa` | DynamoDB、RDS |\n| `cloud` | `rgba(120,53,15,0.3)` | `#fbbf24` | Region 框、CloudFront |\n| `security` | `rgba(136,19,55,0.4)` | `#fb7185` | Security Group、WAF |\n| `message_bus` | `rgba(251,146,60,0.3)` | `#fb923c` | SQS、SNS、EventBridge |\n| `external` | `rgba(30,41,59,0.5)` | `#94a3b8` | 第三方 API、SaaS |\n\n无类别时回退到：fill `#1E293B`，stroke `#94A3B8`。\n\n## 4. 布局规则\n\n### 4.1 L→R 数据流\n\n```\nClients(左) → Frontend → Backend → Database(右)\n```\n\n- Clients 通常放在 Region 框外左侧\n- 其他组件按 `flowSteps[].seqIndex` 排序，从左到右排列\n- 水平间距 40-60px，垂直居中对齐\n\n### 4.2 组件尺寸\n\n根据 capabilities 数量决定：\n\n| 能力数 | 宽度 | 高度 | 用途 |\n|--------|------|------|------|\n| 0-1 | 140px | 44px | 简单组件（SQS 等） |\n| 2-4 | 150px | 80px | 中等组件（Lambda、S3） |\n| 5+ | 160px | 80px | 大组件（API Gateway、DynamoDB） |\n\n所有组件：`rx=\"8\"` 圆角，`stroke-width=\"2\"` 描边。\n\n如果文本、特征列表或标签超出上述尺寸，不得硬压缩成“牙膏图”。优先顺序是：\n1. 增大卡片宽度或高度\n2. 将同层节点换到多行\n3. 扩大画布\n4. 必要时回退到 `freeflow`\n\n禁止通过把整层强行塞成一行、把图例改成浮层、或让底部内容被裁切来维持模板外观。\n\n### 4.3 Region 边界\n\n- 矩形框：`rx=\"16\"`, `stroke-dasharray=\"8,4\"`, 琥珀色 `#F59E0B`, `opacity=\"0.4\"`\n- Region 标签放在框外上方（x=Region左边界+20, y=Region上边界-10）\n- 填充：`none`（仅描边）\n\n### 4.4 Summary Cards\n\n放在架构图底部，3 组卡片，响应式网格布局：\n\n| 卡片 | 颜色 | 内容 |\n|------|------|------|\n| Infrastructure | 琥珀色 `#F59E0B` | 基础设施列表 |\n| Compute | 翠绿色 `#34D399` | 计算资源描述 |\n| Data | 紫色 `#A78BFA` | 数据存储描述 |\n\n每张卡片：`rx=\"10\"`, fill `#0F172A`, stroke `#1E293B`, 宽 340-370px, 高 130px。\n\n### 4.5 分层布局约束\n\n- 分层图中的“层”是语义分组，不是强制单行容器。\n- 每层 `1-3` 个节点时可单行展示。\n- 每层 `4-6` 个节点时默认拆成两行，保持卡片尺寸可读。\n- 每层 `7+` 个节点时应扩大画布或直接回退到 `freeflow`，不要继续压缩。\n- Actor / User 角色默认渲染为边栏标签、badge 或 lane header，不应伪装成普通系统卡片。\n\n### 4.6 Legend 位置\n\n- Legend 默认放在左下或底部保留区。\n- Legend 必须参与整体高度计算，不能作为右上角悬浮遮罩。\n- 禁止将 legend 放在 top-right 覆盖标题区或内容区。\n\n### 4.7 画布尺寸与裁切\n\n- `viewBox` 和最终 `height` 必须覆盖：最底部节点、legend、summary cards、footer，再加至少 `32px` 底部留白。\n- 外层 HTML 容器不得使用固定高度裁切内容。\n- 禁止使用 `overflow: hidden` 裁掉最后一层、legend 或 summary cards。\n- 如果模板内容超出当前画布，应增加画布高度或改为多行布局，而不是截断。\n\n### 4.8 完整性阈值\n\n所有几何类完整性检查必须使用阈值配置，而不是凭渲染器里的临时经验判断。\n\n阈值来源：\n- `evals/export-integrity-thresholds.json`\n\n最小阈值集合：\n- `minLabelClearancePx`\n- `legendBottomMarginPx`\n- `legendContentGapPx`\n- `titleOverflowTolerancePx`\n- `cardTextInsetPx`\n\n只要是以下检查，都必须绑定到阈值：\n- label 与折线拐点、卡片边界的最小安全距离\n- legend 与底部/内容区的安全距离\n- 标题文本的溢出容忍度\n- 卡片正文与边框的内边距\n\n## 5. 视觉元素\n\n### 5.1 箭头\n\n```svg\n\n \n\n```\n\n- 实线箭头：`stroke=\"#64748B\"`, `stroke-width=\"2\"`, `marker-end=\"url(#arrow-solid)\"`\n- 虚线箭头（可选）：`stroke-dasharray=\"4,3\"`, `stroke=\"#475569\"`\n\n### 5.2 网格 Pattern\n\n```svg\n\n \n\n```\n\n### 5.3 节点结构\n\n```svg\n\n \n 名称\n 副标签\n\n```\n\n## 6. Z 序\n\n1. 背景（`#020617` rect）\n2. 网格 pattern\n3. 标题文字\n4. Region 框\n5. 箭头\n6. 节点（rect + text）\n7. Legend（底部保留区）\n8. Summary Cards\n9. Footer\n\n## 7. Blueprint 字段映射\n\n| 视觉概念 | Blueprint 字段 | 推导逻辑 |\n|---------|---------------|---------|\n| 组件色 | `systems[].category` | 直接映射到语义色 |\n| L→R 顺序 | `flowSteps[].seqIndex` | 按 seqIndex 排序 |\n| Region 框 | `systems[].properties.type` | `type == \"aws\"` → Region |\n| 组件大小 | `capabilities` 数量 | 0-1=小, 2-4=中, 5+=大 |\n| 副标签 | `systems[].description` | 取前 2-3 个特征 |\n| 箭头 | `flowSteps[].nextStepIds` | 从 nextStepIds 推导连接 |\n\nFile v0.15.0:references/architecture-diagram-design.md\n\n# Architecture Diagram Generator — Design Document (v2)\n\n## Context\n\n当前 `export_svg.py` 包含复杂的自动布局引擎（`_layout_free_flow`、`_content_router`、`_render_free_flow_svg`），产出却是网格堆叠的卡片，不是真正的架构图。更关键的是：**Python 代码太重，沙箱频繁出问题**——依赖链长、`importlib.metadata` 不稳定、`__file__` 在 Jupyter 中未定义。\n\n参考项目 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) 走了完全不同的路：**SKILL.md 定义设计系统，Claude 按规则直接生成 HTML+SVG，零 Python 依赖。**\n\n本文档设计 v2 重构方案：**核心架构图生成完全脱离 Python，由 Claude 读取 SKILL.md → 直接输出 HTML+SVG。Python 只做 JSON 校验和格式转换（draw.io/excalidraw/mermaid）。**\n\n## 核心决策\n\n### 1. Python 轻量化\n\n| 当前 | v2 |\n|------|-----|\n| `export_svg.py` 1500+ 行布局引擎 | 保留 300 行核心常量，移除自动布局 |\n| `export_html.py` 200+ 行内嵌 SVG 构建 | 改为直接输出预生成的 SVG |\n| `--export` 默认调 9 个 Python 函数 | Claude 生成 HTML+SVG（主），Python 格式转换（备） |\n| 依赖 `importlib.metadata`、`math`、`pathlib` | 只依赖 `json`、`pathlib`（stdlib） |\n| 沙箱需 `pip install kai-business-blueprint` | 沙箱只需 `json.load()` + 写文件，或 Claude 直接生成 |\n\n### 2. Claude 生成架构图的具体机制\n\n不是\"Claude 在对话中手写 SVG\"，而是：\n\n```\n1. Claude 读取 blueprint JSON（或用户自然语言描述）\n2. Claude 读取 SKILL.md 中的设计系统规范\n3. Claude 生成 HTML+SVG 文本 → 写入文件\n4. 输出：单个 .html 文件\n```\n\n**在沙箱环境中**，不需要 `pip install`：\n```python\n# 沙箱只需这两行——无第三方依赖\nimport json\nblueprint = json.load(open(\"solution.blueprint.json\"))\n# 然后 Claude 根据 blueprint 数据直接生成 HTML+SVG 字符串并写入文件\n```\n\n**Python 脚本完全退出架构图渲染**——它只做：\n- `--plan`：将用户需求写入 blueprint JSON\n- `--validate`：校验 blueprint 结构\n- `--format drawio/excalidraw/mermaid`：从 blueprint 生成对应格式（这些格式有成熟的 Python 库/字符串拼接即可）\n\n### 3. Blueprint Schema 适配\n\n当前 schema **已有足够字段**，不需要扩展：\n\n| 设计系统概念 | Blueprint 字段 | 映射方式 |\n|------------|---------------|---------|\n| 组件类型/颜色 | `systems[].category` | frontend/backend/database/cloud/security/external |\n| L→R 数据流 | `flowSteps[].seqIndex` + `nextStepIds` | 按 seqIndex 排序，L→R 排列 |\n| Region 边界 | `systems[].properties.type` | `type == \"aws\"` → 包在 AWS Region 框内 |\n| 消息总线 | `systems[].properties.service == \"sqs\"` 等 | SQS/EventBridge/SNS → MessageBus 颜色 |\n| 组件副标题 | `systems[].description` 或 `properties.features` | 取前 2-3 个特征 |\n| 组件大小 | 根据 `capabilities` 数量决定 | 0-1 cap → 小框(60px)，2-4 → 中框(80px)，5+ → 大框(120px) |\n\n**不需要新增字段。** 所有视觉决策都从现有字段推导。\n\n## 设计系统（从参考项目继承）\n\n### 颜色 Palette\n\n| 类型 | 填充色 | 边框色 | 用途 |\n|------|--------|--------|------|\n| Frontend | `rgba(8,51,68,0.4)` | `#22d3ee` | Web、移动端、UI |\n| Backend | `rgba(6,78,59,0.4)` | `#34d399` | Lambda、API Gateway、服务 |\n| Database | `rgba(76,29,149,0.4)` | `#a78bfa` | DynamoDB、RDS、S3 |\n| AWS/Cloud | `rgba(120,53,15,0.3)` | `#fbbf24` | Region 框、CloudFront |\n| Security | `rgba(136,19,55,0.4)` | `#fb7185` | Security Group、WAF |\n| MessageBus | `rgba(251,146,60,0.3)` | `#fb923c` | SQS、SNS、EventBridge |\n| External | `rgba(30,41,59,0.5)` | `#94a3b8` | 第三方 API、SaaS |\n\n### 字体\n- JetBrains Mono（Google Fonts CDN）\n- 组件名：14px / 600\n- 副标签：11px / 400\n- 注解：9px\n- Region 标签：10px / 600\n\n### 布局规则\n- L→R 数据流：Clients(左) → Frontend → Backend → Database(右)\n- Region 虚线框：`rx=\"12\"`, `stroke-dasharray=\"8,4\"`, 琥珀色\n- 组件圆角：`rx=\"6\"`, 1.5px 描边\n- Z 序：箭头 → 节点遮罩 → 节点样式 → 文字 → Legend\n\n## SKILL.md 结构\n\n遵循**渐进披露**原则，SKILL.md 本身不塞设计系统细节：\n\n```\nSKILL.md（路由层，<100行）\n ├── 何时触发架构生成（关键词：architecture diagram, 架构图, --export）\n ├── 读取 references/architecture-design-system.md（完整设计系统）\n ├── 读取 references/architecture-templates/serverless.md（模板）\n └── Claude 生成 HTML+SVG → 写入文件\n\nreferences/architecture-design-system.md（设计系统，~80行）\n ├── 颜色 Palette\n ├── 字体与间距\n ├── 视觉元素（Region框、组件框、箭头）\n └── Z 序规则\n\nreferences/architecture-templates/（模板库）\n ├── serverless.md（AWS Serverless 模板）\n ├── microservices.md（微服务模板）\n └── three-tier.md（三层架构模板）\n```\n\n## Python 代码改动\n\n### 删除（~900 行）\n\n| 文件 | 删除内容 |\n|------|---------|\n| `export_svg.py` | `_content_router()`、`_layout_free_flow()`、`_render_free_flow_svg()`、`export_svg_auto()` |\n| `export_html.py` | `_build_architecture_svg()` 整个函数 |\n\n### 保留（~600 行）\n\n| 文件 | 保留内容 |\n|------|---------|\n| `export_svg.py` | 设计常量（`C_LIGHT`、`C_DARK`、字体、尺寸）、箭头/节点渲染函数、`export_svg()` 三层布局（回退用）、`export_*_svg()` 专业视图 |\n| `export_drawio.py` | 完整保留 |\n| `export_excalidraw.py` | 完整保留 |\n| `export_mermaid.py` | 完整保留 |\n| `cli.py` | 简化：`--export` 默认触发 Claude 生成（见下），`--format drawio/excalidraw/mermaid/all` 调 Python |\n\n### `cli.py` 中 `--export` 新逻辑\n\n**关键设计：** `--export` 既要保证向后兼容（Python 产出基础文件），也要让 Agent 有机会生成增强版架构图。\n\n```python\nif args.export:\n blueprint_path = Path(args.export)\n blueprint = load_json(blueprint_path)\n stem = blueprint_path.stem\n export_dir = blueprint_path.parent / f\"{stem}.exports\"\n export_dir.mkdir(parents=True, exist_ok=True)\n \n fmt = args.export_format or \"svg\"\n \n if fmt == \"svg\":\n # Python 产出经典三层布局 SVG（向后兼容，确保有文件产出）\n export_svg(blueprint, export_dir / \"solution.svg\", theme=args.theme)\n # Agent 在沙箱外读取 blueprint → 按 SKILL.md 生成增强版 HTML+SVG\n # 这是 Agent 的下一步动作，不在 CLI 中执行\n return 0\n \n elif fmt == \"drawio\":\n export_drawio(blueprint, export_dir / \"solution.drawio\")\n elif fmt == \"excalidraw\":\n export_excalidraw(blueprint, export_dir / \"solution.excalidraw\")\n elif fmt == \"mermaid\":\n export_mermaid(blueprint, export_dir / \"solution.mermaid.md\")\n elif fmt == \"all\":\n # Python 产出所有格式（向后兼容）\n export_svg(blueprint, export_dir / \"solution.svg\", theme=args.theme)\n export_capability_map_svg(blueprint, export_dir / \"capability-map.svg\", theme=args.theme)\n export_swimlane_flow_svg(blueprint, export_dir / \"swimlane-flow.svg\", theme=args.theme)\n export_product_tree_svg(blueprint, export_dir / \"product-tree.svg\", theme=args.theme)\n export_matrix_svg(blueprint, export_dir / \"capability-matrix.svg\", theme=args.theme)\n export_drawio(blueprint, export_dir / \"solution.drawio\")\n export_excalidraw(blueprint, export_dir / \"solution.excalidraw\")\n export_mermaid(blueprint, export_dir / \"solution.mermaid.md\")\n # Agent 可在此基础上额外生成增强版架构图 HTML\n return 0\n```\n\n**Agent 的增强流程（CLI 之外）：**\n1. `--export` 完成后，Agent 读取 blueprint JSON\n2. Agent 按 SKILL.md 设计系统规范生成架构图 HTML+SVG\n3. 写入 `{stem}.html` 到同目录\n\n### 沙箱兼容\n\n沙箱不是独立运行的——调用链是 `用户 → Agent(Claude/OpenAI/GLM) → tool call → 沙箱执行Python`。\n\n沙箱中 Agent 始终可用，所以架构生成流程是：\n1. Agent 在沙箱中 `json.load()` 读取 blueprint\n2. Agent 读取 SKILL.md 设计系统规范\n3. Agent 生成 HTML+SVG 字符串 → 通过沙箱 `write_file` 或 `Path.write_text()` 写入\n4. 返回给用户\n\n沙箱不再需要 `pip install kai-business-blueprint`：\n```python\n# 极简沙箱用法——只需 stdlib\nimport json\nfrom pathlib import Path\n\nblueprint = json.loads(Path(\"solution.blueprint.json\").read_text())\n# Agent 根据 blueprint 数据 + SKILL.md 设计系统，直接生成 HTML+SVG 并写入文件\n```\n\n**Python 脚本在沙箱中的角色：JSON 加载 + 校验。** 架构图渲染完全由 Agent 承担。\n\n## 回退策略\n\n由于调用链中 Agent 始终存在（Agent → tool call → 沙箱 → Agent 继续），**不存在\"无 Agent 可用\"的回退场景**。但保留以下回退以防代码层面断裂：\n\n1. **`--export` 时 Python 仍产出 `solution.svg`（三层布局经典版）** — 确保 `--format all` 向后兼容\n2. **`export_html.py` 不再自己构建 SVG** — 改为接受预生成的 SVG 内容参数\n\n三个保障：\n- `--export` 至少产出 `solution.svg`（Python 经典布局）\n- Agent 可在此基础上额外生成 HTML+SVG 架构图\n- `drawio/excalidraw/mermaid` 格式由 Python 稳定产出\n\n## 实施阶段\n\n| 阶段 | 内容 | 可回滚？ |\n|------|------|---------|\n| **Phase 1** | 写 `references/architecture-design-system.md` + 模板 | ✅ 只加文件 |\n| **Phase 2** | 更新 SKILL.md 添加架构图生成路由 | ✅ 只改 SKILL.md |\n| **Phase 3** | 删除 `_content_router`、`_layout_free_flow`、`_render_free_flow_svg` | ⚠️ 需确认无外部依赖 |\n| **Phase 4** | 简化 `cli.py` 和 `export_html.py` | ⚠️ 需测试沙箱兼容 |\n| **Phase 5** | 测试 `aws-serverless.blueprint.json` 生成效果 | — |\n\n## 评审问题应对\n\n| Codex 评审问题 | 应对 |\n|---------------|------|\n| `export_html.py` 导入断裂 | **`export_html.py` 的 `_build_architecture_svg()` 不再自己构建 SVG**，改为接受预生成的 SVG 字符串参数，或回退到三层布局。删除对 `_content_router`、`_layout_free_flow`、`_render_free_flow_svg` 的 import |\n| \"CLI plans, Claude generates\" 无明确机制 | **CLI 产出基础文件（Python 经典布局），Agent 在此基础上生成增强版**。CLI 不返回 0 空文件 |\n| 非交互环境无 Claude | **调用链始终是 Agent → tool call → 沙箱 → Agent**。不存在离线调用场景 |\n| Blueprint 字段不够 | 所有视觉决策从现有字段推导，不需新增 schema |\n| SKILL.md 膨胀 | 设计系统放 `references/`，SKILL.md 只引用 |\n| `--format all` 其他导出 | **保留所有 Python SVG 导出器在 `--format all` 中**，确保向后兼容 |\n| 测试文件断裂 | Phase 3 删除 `test_content_router_and_layout.py` 或重写 |\n\nFile v0.15.0:references/architecture-templates/microservices.md\n\n# Microservices Architecture Template\n\n## 适用场景\n\n用户描述包含：微服务、microservices、service mesh、Kubernetes、K8s、分布式服务等关键词。\n\n## 布局结构\n\n```\nClients → API Gateway → [Service A, Service B, Service C] → [DB A, DB B, Cache, MQ]\n```\n\n这些坐标只是起始参考，不是必须照抄的固定布局。如果服务或数据节点超出当前模板容量：\n- 允许服务列或数据列拆成多行\n- 允许增大画布和 cluster 边界\n- 仍然拥挤时回退到 `freeflow`\n\n不要把所有服务和数据卡片硬塞进同一行，造成牙膏式排版。\n\n## 组件定义\n\n| 组件 | 类别 | x | y | 宽 | 高 | 特征 |\n|------|------|---|---|-----|-----|------|\n| Clients | external | 80 | 280 | 140 | 80 | Web/Mobile |\n| API Gateway | cloud | 310 | 280 | 150 | 80 | Routing, Auth |\n| Service A | backend | 540 | 160 | 150 | 80 | 业务服务 |\n| Service B | backend | 540 | 280 | 150 | 80 | 用户服务 |\n| Service C | backend | 540 | 400 | 150 | 80 | 订单服务 |\n| DB A | database | 780 | 160 | 140 | 80 | 业务数据 |\n| DB B | database | 780 | 280 | 140 | 80 | 用户数据 |\n| Cache | database | 780 | 400 | 140 | 44 | Redis/ElastiCache |\n| MQ | message_bus | 780 | 500 | 140 | 44 | RabbitMQ/Kafka |\n\n## 连接关系\n\n| 从 | 到 | 方向 |\n|----|----|------|\n| Clients | API Gateway | 水平 → |\n| API Gateway | Service A | 水平 → |\n| API Gateway | Service B | 水平 → |\n| API Gateway | Service C | 水平 → |\n| Service A | DB A | 水平 → |\n| Service B | DB B | 水平 → |\n| Service C | Cache | 水平 → |\n| Service C | MQ | 水平 → |\n\n## K8s Cluster Region\n\n- 虚线框：x=290, y=120, width=660, height=450, rx=16\n- 描边：`#FBBF24`, `stroke-dasharray=\"8,4\"`, `opacity=\"0.4\"`\n- 标签：`Kubernetes Cluster`（x=310, y=110）\n- Clients 在 Cluster 框外左侧\n\n## 图例与画布\n\n- Legend 放在左下或底部保留区，不放右上角。\n- 最终 SVG 高度必须包含最底部节点、legend、summary cards 和 footer。\n- 不得用固定高度容器或裁切把底部内容截断。\n\n## Summary Cards\n\n### Gateway (琥珀色)\n- API Gateway routing\n- Authentication & authorization\n- Rate limiting\n- Load balancing\n\n### Services (翠绿色)\n- Microservice A/B/C\n- Independent deployment\n- Service discovery\n- Health monitoring\n\n### Data (紫色)\n- Database per service\n- Redis caching layer\n- Message queue\n- Event-driven communication\n\nFile v0.15.0:references/architecture-templates/serverless.md\n\n# AWS Serverless Architecture Template\n\n## 适用场景\n\n用户描述包含：Lambda、API Gateway、DynamoDB、Serverless、无服务器等关键词。\n\n## 布局结构\n\n```\nClients → CloudFront → API Gateway → Lambda → DynamoDB\n → SQS\n → S3\n```\n\n这些坐标是结构参考，不是必须死守的固定像素模板。如果内容变多、标签变长、或增加额外节点：\n- 先扩容画布或调整节点位置\n- 再把相关节点拆成多行\n- 仍然放不下时回退到 `freeflow`\n\n不要为了维持这一版模板，把整张图挤成单行牙膏布局。\n\n## 组件定义\n\n| 组件 | 类别 | x | y | 宽 | 高 | 特征 |\n|------|------|---|---|-----|-----|------|\n| Clients | external | 80 | 230 | 140 | 80 | Web/Mobile |\n| CloudFront | cloud | 310 | 230 | 140 | 80 | CDN |\n| API Gateway | cloud | 500 | 230 | 160 | 80 | REST API, WebSocket, HTTPS |\n| Lambda | backend | 720 | 230 | 150 | 80 | Functions, Auto-scaling |\n| SQS | message_bus | 720 | 130 | 150 | 44 | Message Queue |\n| S3 | cloud | 720 | 360 | 150 | 80 | Object Storage |\n| DynamoDB | database | 930 | 230 | 160 | 80 | NoSQL, On-demand |\n\n## 连接关系\n\n| 从 | 到 | 方向 |\n|----|----|------|\n| Clients | CloudFront | 水平 → |\n| CloudFront | API Gateway | 水平 → |\n| API Gateway | Lambda | 水平 → |\n| Lambda | SQS | 垂直 ↑ |\n| Lambda | S3 | 垂直 ↓ |\n| Lambda | DynamoDB | 水平 → |\n\n## AWS Region\n\n- 虚线框：x=260, y=110, width=900, height=350, rx=16\n- 描边：`#F59E0B`, `stroke-dasharray=\"8,4\"`, `opacity=\"0.4\"`\n- 标签：`AWS Region: us-east-1`（x=280, y=100）\n- Clients 在 Region 框外左侧\n\n## 图例与画布\n\n- Legend 放在左下或底部保留区，不放右上角。\n- 最终 SVG 高度必须包含最底部节点、legend、summary cards 和 footer。\n- 不得用固定高度容器或裁切把底部内容截断。\n\n## Summary Cards\n\n### Infrastructure (琥珀色)\n- CloudFront CDN distribution\n- API Gateway REST endpoints\n- S3 static asset hosting\n- SQS message queues\n\n### Compute (翠绿色)\n- Lambda functions\n- Auto-scaling to zero\n- Pay-per-invocation\n- 15 min max execution\n\n### Data (紫色)\n- DynamoDB tables\n- On-demand capacity\n- Global secondary indexes\n- Point-in-time recovery\n\nFile v0.15.0:references/authoring-rules.md\n\n# Authoring Rules\n\n- The viewer save action must export a new canonical revision package.\n- `solution.patch.jsonl` records human edits.\n- `editor.fieldLocks` protects human-edited semantic fields.\n- Validation must run before downstream completion claims.\n\nFile v0.15.0:references/blueprint-schema.md\n\n# Blueprint Schema Reference\n\nThe canonical file contains:\n\n- `meta`\n- `context`\n- `library`\n- `relations`\n- `views`\n- `editor`\n- `artifacts`\n\nEntity collections in `library`:\n\n- `capabilities`\n- `actors`\n- `flowSteps`\n- `systems`\n\nFile v0.15.0:references/blueprint-skill-optimization-proposal.md\n\n# Business Blueprint Skill 优化方案\n\n## 问题诊断\n\n### 现状分析\n\n**现有skill定位**：系统架构蓝图生成器\n- 实体类型：capabilities（能力）、actors（角色）、flowSteps（流程）、systems（系统）\n- 输出形式：架构分层图、泳道流程图、系统支撑关系图\n- 适用场景：售前方案设计、IT系统规划、业务流程梳理\n\n**缺失需求**：业务领域know-how知识图谱\n- 痛点挑战、关键策略、平台规则、数据指标、最佳实践、常见误区\n- 用于展示\"我们懂这个领域\"的专业度\n- 客户pitch时需要业务洞察，而非技术架构\n\n### 根本原因\n\nskill设计时将\"业务蓝图\"等同于\"系统架构蓝图\"，实体定义固化在IT系统视角：\n- `systems` 实体强制映射到技术架构层（客户端层、网关层、业务服务层）\n- 缺失\"策略要素\"、\"行业规则\"、\"数据基准\"等业务洞察实体\n- AI只能按IT架构思维提取实体，无法生成领域知识图谱\n\n---\n\n## 设计方案对比\n\n### 方案A：扩展实体类型（最小改动）\n\n**改造思路**：\n在现有`library`中新增实体类型：\n```json\n{\n \"library\": {\n \"capabilities\": [],\n \"actors\": [],\n \"flowSteps\": [],\n \"systems\": [],\n // 新增实体类型\n \"painPoints\": [\n {\"id\": \"pain-001\", \"name\": \"ROI不稳\", \"description\": \"广告投放ROI波动大，缺乏稳定增长路径\", \"severity\": \"high\"}\n ],\n \"strategies\": [\n {\"id\": \"str-001\", \"name\": \"测款节奏\", \"description\": \"3天测款周期，预算分配策略\", \"applicableCapabilityIds\": [\"cap-004\"]}\n ],\n \"platformRules\": [\n {\"id\": \"rule-001\", \"name\": \"Facebook政策红线\", \"description\": \"禁止误导性宣传、过度夸大效果\", \"riskLevel\": \"critical\"}\n ],\n \"metrics\": [\n {\"id\": \"met-001\", \"name\": \"ROAS基准\", \"value\": \">3.0\", \"unit\": \"ratio\", \"benchmarkContext\": \"欧美市场\"}\n ],\n \"bestPractices\": [\n {\"id\": \"bp-001\", \"name\": \"素材迭代周期\", \"description\": \"每7天测试新素材版本，避免疲劳\"}\n ],\n \"pitfalls\": [\n {\"id\": \"pit-001\", \"name\": \"过度依赖单一平台\", \"description\": \"Facebook封号后业务瘫痪风险\", \"impact\": \"critical\"}\n ]\n }\n}\n```\n\n**优点**：\n- 兼容现有JSON schema和export逻辑，改动最小\n- 一个蓝图可以同时包含架构和know-how\n\n**缺点**：\n- 实体职责混淆，一个JSON既要画架构图又要画知识图谱\n- 导出视图选择复杂化（需要判断显示哪些实体类型）\n- 与现有schema文档的\"实体概览表\"冲突（需要重新编写schema文档）\n\n---\n\n### 方案B：引入蓝图类型区分（路由层改造）\n\n**改造思路**：\n在SKILL.md中引入显式的蓝图类型参数：\n```bash\npython scripts/business_blueprint/cli.py --plan blueprint.json --type architecture\npython scripts/business_blueprint/cli.py --plan blueprint.json --type domain-knowledge\n```\n\n两种类型使用不同的schema和hints：\n- `--type architecture`：使用现有实体体系（capabilities/actors/flowSteps/systems）\n- `--type domain-knowledge`：使用新的实体体系（painPoints/strategies/rules/metrics/practices/pitfalls）\n\n**优点**：\n- 职责清晰，互不干扰\n- 每种类型有独立的hints模板和导出视图\n- schema文档可以分别编写\n\n**缺点**：\n- 需要用户显式指定类型（增加使用门槛）\n- 需要双倍维护成本（两套schema、两套模板、两套导出逻辑）\n- 不符合skill的\"渐进式披露\"设计原则（AI应该自动判断意图）\n\n---\n\n### 方案C：轻量级schema扩展（推荐方案）\n\n**改造思路**：\n保持核心schema不变，新增可选的`knowledge`块：\n\n```json\n{\n \"version\": \"1.0\",\n \"meta\": {\n \"title\": \"...\",\n \"industry\": \"retail\",\n \"blueprintType\": \"architecture\", // 新增字段：默认\"architecture\"，可选\"domain-knowledge\"或\"hybrid\"\n \"revisionId\": \"...\",\n \"lastModifiedAt\": \"...\",\n \"lastModifiedBy\": \"ai\"\n },\n \"context\": {...},\n \"library\": {\n // 保留现有实体（架构类）\n \"capabilities\": [],\n \"actors\": [],\n \"flowSteps\": [],\n \"systems\": [],\n // 新增可选块（know-how类）\n \"knowledge\": {\n \"painPoints\": [],\n \"strategies\": [],\n \"rules\": [],\n \"metrics\": [],\n \"practices\": [],\n \"pitfalls\": []\n }\n },\n \"relations\": [],\n \"views\": [],\n \"editor\": {...},\n \"artifacts\": {}\n}\n```\n\n**AI意图判断逻辑**（写在SKILL.md）：\n```\n用户需求关键词匹配：\n- \"架构图\"、\"系统设计\"、\"IT规划\" → blueprintType = \"architecture\"，只填充library核心实体\n- \"know-how\"、\"领域知识\"、\"业务洞察\"、\"最佳实践\"、\"行业玩法\" → blueprintType = \"domain-knowledge\"，只填充knowledge块\n- 混合需求（同时提到架构和策略） → blueprintType = \"hybrid\"，同时填充两类实体\n```\n\n**导出视图路由逻辑**（在export_routes.py中）：\n```python\nif blueprintType == \"architecture\":\n 使用现有视图模板（poster/swimlane/freeflow）\nelif blueprintType == \"domain-knowledge\":\n 使用新的knowledge视图模板（knowledge-graph/knowledge-cards）\nelif blueprintType == \"hybrid\":\n 分页渲染（第一页架构图，第二页知识图谱）\n```\n\n**优点**：\n- 不破坏现有架构蓝图能力（向后兼容）\n- AI自动判断意图，无需用户显式参数（符合渐进式披露）\n- 同一个JSON schema，不同视图模板（维护成本低）\n- 可以支持混合蓝图（架构+know-how并存）\n\n**缺点**：\n- 需要新增knowledge块的schema文档\n- 需要开发新的导出视图模板\n\n---\n\n## 推荐方案C的详细设计\n\n### 一、schema扩展设计\n\n#### 1. meta字段扩展\n\n```json\n{\n \"meta\": {\n \"blueprintType\": \"architecture\" // 新增，枚举值：architecture | domain-knowledge | hybrid\n }\n}\n```\n\n#### 2. library.knowledge实体定义\n\n新增`knowledge`块，包含6类know-how实体：\n\n| 实体类型 | 定义 | 示例数量 | 必填字段 |\n|---------|------|---------|---------|\n| **painPoints** | 痛点挑战 | 3-8 | id, name, description, severity |\n| **strategies** | 关键策略 | 3-10 | id, name, description, applicableCapabilityIds |\n| **rules** | 平台/政策规则 | 3-8 | id, name, description, riskLevel |\n| **metrics** | 数据指标/基准 | 3-10 | id, name, value, unit, benchmarkContext |\n| **practices** | 最佳实践 | 3-10 | id, name, description |\n| **pitfalls** | 常见误区 | 3-8 | id, name, description, impact |\n\n#### 3. knowledge实体字段详细定义\n\n**painPoints（痛点）**\n```json\n{\n \"id\": \"pain-001\",\n \"name\": \"ROI不稳\",\n \"description\": \"广告投放ROI波动大，缺乏稳定增长路径\",\n \"severity\": \"high\", // 枚举：low | medium | high | critical\n \"relatedCapabilityIds\": [\"cap-004\", \"cap-005\"] // 可选，关联到能力\n}\n```\n\n**strategies（策略）**\n```json\n{\n \"id\": \"str-001\",\n \"name\": \"测款节奏策略\",\n \"description\": \"3天测款周期，预算分配70%测款+30%放量\",\n \"applicableCapabilityIds\": [\"cap-004\"], // 可选，应用到哪些能力\n \"prerequisites\": [\"数据分析能力\"] // 可选，前置条件\n}\n```\n\n**rules（规则）**\n```json\n{\n \"id\": \"rule-001\",\n \"name\": \"Facebook广告政策红线\",\n \"description\": \"禁止误导性宣传、过度夸大效果、虚假折扣\",\n \"riskLevel\": \"critical\", // 枚举：low | medium | high | critical\n \"platform\": \"Facebook Ads\", // 可选，适用平台\n \"penalty\": \"账户封禁\" // 可选，违规后果\n}\n```\n\n**metrics（指标）**\n```json\n{\n \"id\": \"met-001\",\n \"name\": \"ROAS基准\",\n \"value\": \">3.0\",\n \"unit\": \"ratio\",\n \"benchmarkContext\": \"欧美市场，电商类目\",\n \"calculationMethod\": \"GMV / Ad Spend\" // 可选，计算公式\n}\n```\n\n**practices（最佳实践）**\n```json\n{\n \"id\": \"bp-001\",\n \"name\": \"素材迭代周期\",\n \"description\": \"每7天测试新素材版本，CTR下降10%时立即更换\",\n \"frequency\": \"weekly\", // 可选，执行频率\n \"successMetric\": \"CTR提升15%\" // 可选，成功指标\n}\n```\n\n**pitfalls（误区）**\n```json\n{\n \"id\": \"pit-001\",\n \"name\": \"过度依赖单一平台\",\n \"description\": \"只投放Facebook，平台封号后业务瘫痪\",\n \"impact\": \"critical\", // 枚举：low | medium | high | critical\n \"avoidanceStrategy\": \"多平台分散投放，预算占比不超过60%\" // 可选，规避建议\n}\n```\n\n---\n\n### 二、hints模板扩展\n\n#### 1. 行业hints增加know-how checklist\n\n修改`templates/{industry}/seed.json`：\n\n```json\n{\n \"industryHints\": {\n \"title\": \"零售行业蓝图关注点\",\n \"checklist\": [...], // 现有的架构类hints\n \"knowledgeHints\": { // 新增块\n \"title\": \"零售行业know-how关注点\",\n \"checklist\": [\n \"痛点：库存积压、客流下滑、会员流失、POS效率低\",\n \"策略：会员分层运营、智能补货、导购赋能、全渠道融合\",\n \"规则：食品安全合规、价格欺诈风险、数据隐私法规\",\n \"指标：坪效基准、客单价目标、会员复购率、员工人效\",\n \"最佳实践：陈列迭代周期、促销节奏、会员召回时机\",\n \"误区：过度依赖促销、忽视会员运营、数据孤岛\"\n ]\n }\n }\n}\n```\n\n#### 2. 为跨境电商新建industry模板\n\n新建`templates/cross-border-ecommerce/seed.json`：\n\n```json\n{\n \"industryHints\": {\n \"title\": \"跨境电商广告投放know-how关注点\",\n \"checklist\": [], // 空列表，架构类hints可选\n \"knowledgeHints\": {\n \"title\": \"跨境电商广告投放know-how\",\n \"checklist\": [\n \"痛点：ROI不稳、素材疲劳、平台封号、库存积压、汇率风险\",\n \"策略：测款节奏、出价策略、受众分层、再营销触发时机、预算动态分配\",\n \"规则：Facebook政策红线、Google Quality Score、TikTok审核要点、Amazon合规要求\",\n \"指标：ROAS基准(>3.0)、CPA阈值、CTR基准(>1.5%)、LTV测算\",\n \"最佳实践：素材迭代周期(7天)、测款预算分配(70%测款)、再营销触发时机(浏览>3次)\",\n \"误区：过度依赖单一平台、忽视合规风险、数据孤岛、盲目放量、忽视LTV\"\n ]\n }\n }\n}\n```\n\n---\n\n### 三、导出视图设计\n\n#### 1. 新增knowledge视图模板\n\n新建`references/knowledge-view-templates/`目录：\n\n**knowledge-graph.md**：知识图谱视图\n- 布局：中心发散式，painPoints为核心节点\n- 连线：painPoints → strategies → practices → metrics\n- 视觉：按severity/riskLevel分级颜色（critical=红，high=橙，medium=黄，low=绿）\n- 交互：点击节点展开详细描述卡片\n\n**knowledge-cards.md**：卡片式视图\n- 布局：分6列（痛点/策略/规则/指标/实践/误区）\n- 每列内按severity排序\n- 每个卡片显示name + description + 关联信息\n- 支持导出为PPT单页\n\n#### 2. export_routes.py路由逻辑\n\n```python\ndef select_export_route(blueprint):\n blueprint_type = blueprint.get(\"meta\", {}).get(\"blueprintType\", \"architecture\")\n\n if blueprint_type == \"architecture\":\n # 现有路由逻辑\n return select_architecture_route(blueprint)\n elif blueprint_type == \"domain-knowledge\":\n # 新路由：knowledge优先\n return \"knowledge-graph\" # 或 \"knowledge-cards\"\n elif blueprint_type == \"hybrid\":\n # 混合路由：双视图\n return \"hybrid-view\"\n else:\n # fallback\n return \"freeflow\"\n```\n\n---\n\n### 四、SKILL.md改造\n\n#### 1. AI意图判断指南\n\n在SKILL.md的\"How to Generate a Blueprint\"章节前插入：\n\n```markdown\n## Blueprint Type Detection\n\nAI must detect user intent before entity extraction:\n\n| Intent keywords | Blueprint type | Entity focus |\n|----------------|---------------|-------------|\n| \"架构图\"、\"系统设计\"、\"IT规划\"、\"技术蓝图\" | `architecture` | capabilities, actors, flowSteps, systems |\n| \"know-how\"、\"领域知识\"、\"业务洞察\"、\"最佳实践\"、\"行业玩法\"、\"痛点\"、\"策略\" | `domain-knowledge` | knowledge块（painPoints/strategies/rules/metrics/practices/pitfalls） |\n| 混合需求（同时提到架构和策略） | `hybrid` | 两类实体同时提取 |\n\nDefault behavior:\n- If unclear, default to `architecture` (backward compatibility)\n- If industryHints contains `knowledgeHints`, hint AI to also extract knowledge entities\n```\n\n#### 2. Step 2改造\n\n```markdown\n### Step 2: Extract entities from source text\n\n**If blueprintType = \"architecture\"**:\nUsing the user's source material AND the industry hints checklist, extract:\n- capabilities, actors, flowSteps, systems\n - See `references/entities-schema.md` for definitions\n\n**If blueprintType = \"domain-knowledge\"**:\nUsing the user's source material AND the knowledge hints checklist, extract:\n- painPoints, strategies, rules, metrics, practices, pitfalls\n - See `references/knowledge-schema.md` for definitions\n\n**If blueprintType = \"hybrid\"**:\nExtract both architecture and knowledge entities\n```\n\n---\n\n### 五、实施步骤\n\n#### Phase 1：Schema扩展（向后兼容）\n\n1. 修改`scripts/business_blueprint/templates/common/seed.json`，新增`meta.blueprintType`字段（默认值\"architecture\"）\n2. 新建`references/knowledge-schema.md`，定义knowledge块6类实体\n3. 修改`references/entities-schema.md`，在\"实体概览表\"中新增knowledge块说明\n4. 修改JSON schema validator，允许`library.knowledge`可选块\n\n#### Phase 2：Hints模板扩展\n\n1. 修改所有industry seed.json（common/finance/manufacturing/retail），新增`industryHints.knowledgeHints`块\n2. 新建`templates/cross-border-ecommerce/seed.json`（跨境电商专属模板）\n3. 新建`templates/ad-tech/seed.json`（广告技术专属模板）\n\n#### Phase 3：导出视图开发\n\n1. 新建`references/knowledge-view-templates/knowledge-graph.md`（知识图谱模板设计文档）\n2. 新建`references/knowledge-view-templates/knowledge-cards.md`（卡片式模板设计文档）\n3. 修改`business_blueprint/export_routes.py`，增加knowledge路由判断\n4. 开发knowledge视图渲染器（HTML/SVG输出）\n\n#### Phase 4：SKILL.md改造\n\n1. 在SKILL.md开头新增\"Blueprint Type Detection\"章节\n2. 修改\"Step 2: Extract entities\"章节，增加分支逻辑\n3. 新增\"Export Formats\"章节的knowledge视图说明\n4. 新增\"Industry Selection\"表的跨境电商、广告技术行业\n\n---\n\n## 改造清单\n\n### 必须改造的文件\n\n| 文件 | 改动内容 | 优先级 |\n|------|---------|--------|\n| `scripts/business_blueprint/templates/common/seed.json` | 新增meta.blueprintType字段 | P0 |\n| `references/entities-schema.md` | 新增knowledge块说明 | P0 |\n| 新建 `references/knowledge-schema.md` | 定义knowledge实体字段 | P0 |\n| `SKILL.md` | 新增Blueprint Type Detection章节 | P0 |\n| `scripts/business_blueprint/templates/retail/seed.json` | 新增knowledgeHints块 | P1 |\n| `scripts/business_blueprint/templates/finance/seed.json` | 新增knowledgeHints块 | P1 |\n| `scripts/business_blueprint/templates/manufacturing/seed.json` | 新增knowledgeHints块 | P1 |\n| 新建 `templates/cross-border-ecommerce/seed.json` | 跨境电商专属模板 | P1 |\n| 新建 `references/knowledge-view-templates/knowledge-graph.md` | 知识图谱视图设计 | P2 |\n| 新建 `references/knowledge-view-templates/knowledge-cards.md` | 卡片式视图设计 | P2 |\n| `scripts/business_blueprint/export_routes.py` | 新增knowledge路由逻辑 | P2 |\n\n### 可选改造（后续迭代）\n\n- 新建 `templates/ad-tech/seed.json`（广告技术行业模板）\n- 新建 `templates/logistics/seed.json`（物流行业模板）\n- 开发混合视图渲染器（architecture + knowledge并存）\n- 开发知识图谱交互式编辑器（点击节点展开详情）\n\n---\n\n## 验证测试用例\n\n### 测试1：向后兼容性\n\n输入：\n```\n生成企业管理系统的架构蓝图\n```\n\n预期：\n- blueprintType = \"architecture\"\n- 只填充library核心实体（capabilities/actors/flowSteps/systems）\n- 导出视图为现有模板（poster/swimlane/freeflow）\n- JSON schema验证通过\n\n### 测试2：纯knowledge蓝图\n\n输入：\n```\n生成跨境电商广告投放的领域know-how大图，包含痛点、策略、平台规则、数据指标\n```\n\n预期：\n- blueprintType = \"domain-knowledge\"\n- 只填充library.knowledge块（painPoints/strategies/rules/metrics/practices/pitfalls）\n- 导出视图为knowledge-graph或knowledge-cards\n- industry自动选择\"cross-border-ecommerce\"\n\n### 测试3：混合蓝图\n\n输入：\n```\n生成跨境电商广告投放方案，既要系统架构，又要业务策略know-how\n```\n\n预期：\n- blueprintType = \"hybrid\"\n- 同时填充architecture实体和knowledge实体\n- 导出视图为双页（第一页架构图，第二页知识图谱）\n- 或者单页分区域显示\n\n---\n\n## 风险评估\n\n### 低风险\n\n- schema向后兼容（默认blueprintType=\"architecture\"，现有调用不受影响）\n- hints模板扩展不影响现有行业模板\n- AI意图判断写在SKILL.md，不修改Python代码逻辑\n\n### 中风险\n\n- 导出视图路由逻辑需要修改export_routes.py（需要测试回归）\n- knowledge实体字段定义可能与capabilities产生混淆（需要在schema文档中明确区分）\n\n### 高风险\n\n- 无（方案C避免了双schema的维护成本，也没有破坏性改动）\n\n---\n\n## 时间估算\n\n- Phase 1（Schema扩展）：2-3小时\n- Phase 2（Hints模板）：3-4小时\n- Phase 3（导出视图）：8-10小时（需要开发新渲染器）\n- Phase 4（SKILL.md改造）：1-2小时\n\n总计：14-19小时（约2-3个工作日）\n\n---\n\n## 后续迭代建议\n\n1. **知识图谱编辑器**：让用户可以在HTML viewer中点击节点，展开详情卡片，添加新的know-how节点\n2. **行业know-how库**：沉淀各行业的know-how模板库（例如跨境电商的常见痛点、策略清单）\n3. **know-how版本管理**：支持know-how的演化记录（例如Facebook政策规则的历史变更）\n4. **know-how与架构联动**：在架构图中标注对应know-how（例如某个系统旁边显示\"规避XX风险的最佳实践\"）\n\nFile v0.15.0:references/domain-knowledge-design-adversarial-review.md\n\n# 对抗性评审报告：Domain-Knowledge实体扩展设计\n\n**评审日期**: 2026-04-28\n**评审者**: Claude Code（对抗性视角）\n**目标**: 系统性识别设计缺陷、矛盾、遗漏、风险，确保设计质量\n\n---\n\n## 一、核心假设脆弱性分析\n\n### 问题1：AI自动判断意图的可靠性假设\n\n**设计假设**：\n```\n用户需求包含\"know-how\"、\"领域知识\"、\"策略\"、\"痛点\" → blueprintType = \"domain-knowledge\"\n```\n\n**对抗性质疑**：\n- 用户输入模糊时，AI判断会出错吗？\n- 例如：用户说\"优化ROI策略\" → \"策略\"关键词触发domain-knowledge，但用户实际想看的是系统架构（优化ROI的系统设计）\n- 关键词匹配过于简单，缺乏上下文理解\n\n**发现缺陷**：\n- ❌ AI判断逻辑过于简单（关键词匹配），未考虑用户意图的语义理解\n- ❌ 未定义fallback机制：AI判断错误时，用户如何纠正blueprintType？\n\n**建议改进**：\n- 新增判断优先级：用户明确指定蓝图类型 > 关键词频率分析 > 默认值\n- 允许用户在JSON meta中手动设置blueprintType覆盖AI判断\n\n---\n\n### 问题2：\"强核心+弱扩展\"的可行性假设\n\n**设计假设**：\n```\nvalidator只校验核心字段（id/name/entityType），扩展字段直接放行\n```\n\n**对抗性质疑**：\n- 扩展字段真的能完全放行吗？\n- 用户可能在扩展字段中写入错误数据类型（如`severity: 123`而非字符串）\n- freeflow渲染器可能崩溃于复杂嵌套结构（如`{\"nested\": {\"deep\": {\"recursive\": \"object\"}}}`）\n\n**发现缺陷**：\n- ❌ validator完全放行扩展字段，可能导致下游工具（viewer/export）崩溃\n- ❌ 未定义扩展字段的数据类型约束：severity应该是枚举字符串，而非任意值\n- ❌ freeflow渲染器缺乏容错设计：复杂结构降级显示策略未定义\n\n**建议改进**：\n- 定义常见扩展字段的soft schema（如severity: string枚举，level: integer）\n- validator校验扩展字段时采用soft模式（警告而非报错）\n- freeflow渲染器增加容错：嵌套层级>3时降级为文本卡片\n\n---\n\n### 问题3：freeflow自适应渲染的技术可行性假设\n\n**设计假设**：\n```\nfreeflow足够灵活，只需定义视觉样式，无需开发独立knowledge-graph视图模板\n```\n\n**对抗性质疑**：\n- freeflow当前渲染逻辑基于system分层架构，knowledge实体没有layer/category字段\n- freeflow如何布局大量knowledge实体（例如50个痛点、30个策略）？\n- relations关系连线复杂时（多个solves、prevents交叉），freeflow能否正确渲染？\n\n**发现缺陷**：\n- ❌ freeflow布局算法未适配knowledge实体（无layer/category，无法自动分层）\n- ❌ 未定义knowledge实体的布局策略（中心发散？网格布局？自由布局？）\n- ❌ 大量实体场景下的性能问题未评估（100+实体时freeflow渲染速度）\n\n**建议改进**：\n- 定义knowledge布局策略：painPoints为中心，strategies围绕，其他实体外围\n- 新增布局算法：entityType-based clustering（按实体类型聚类）\n- 定义性能上限：超过50实体时分页渲染或简化连线\n\n---\n\n## 二、边界条件未覆盖\n\n### 问题4：混合蓝图的处理逻辑缺失\n\n**设计假设**：\n```\n两种类型互斥，不设计hybrid（避免复杂度）\n```\n\n**对抗性质疑**：\n- 用户实际需求可能真的需要混合蓝图（既要系统架构，又要know-how策略）\n- AI判断\"优先domain-knowledge\"的规则，会导致architecture实体被遗漏\n- relations跨类型关联（strategy → capability）在纯domain-knowledge蓝图中失效（capability不存在）\n\n**发现缺陷**：\n- ❌ 混合需求强制选择单一蓝图类型，丢失部分用户需求\n- ❌ 跨类型关联的实用性假设：如果blueprintType=domain-knowledge，用户不能添加capability实体，跨类型关联无法建立\n- ❌ 未定义混合蓝图的处理策略（是否允许？如何存储？）\n\n**建议改进**：\n- 允许hybrid蓝图类型（blueprintType=\"hybrid\"），同时填充architecture和knowledge实体\n- 定义hybrid蓝图的处理规则：relations必须明确区分跨类型关系和同类型关系\n- 或者：允许domain-knowledge蓝图中可选添加architecture实体（非强制）\n\n---\n\n### 问题5：用户自定义实体的边界模糊\n\n**设计假设**：\n```\n允许用户自定义实体类型数组（validator不校验数组名称）\n```\n\n**对抗性质疑**：\n- 用户自定义实体与预定义实体的命名冲突如何处理？（如用户自定义\"strategies\"数组）\n- 用户自定义实体类型命名不规范时，freeflow如何渲染？（如`\"MyCustomEntity\"`而非`\"myCustomEntity\"`）\n- 用户自定义实体如何建立关系？（entityType不在relations定义中）\n\n**发现缺陷**：\n- ❌ 未定义命名冲突处理策略：用户自定义数组名称与预定义实体类型冲突时，validator行为未明确\n- ❌ 用户自定义entityType的命名规范未定义（推荐camelCase？允许任意字符串？）\n- ❌ 用户自定义实体的relations关系类型未定义（如何建立custom → custom的关系？）\n\n**建议改进**：\n- 定义命名冲突策略：用户自定义数组名称优先级高于预定义（允许覆盖）\n- 定义entityType命名规范：推荐camelCase，validator校验格式（至少3字符，无特殊符号）\n- 新增通用关系类型：`relates`（任意实体之间的弱关联）\n\n---\n\n### 问题6：relations关系完整性约束缺失\n\n**设计假设**：\n```\nrelations数组表达实体关联，新增solves/prevents/measures等关系类型\n```\n\n**对抗性质疑**：\n- relations中的from/to ID不存在时，validator如何处理？\n- 循环依赖如何避免？（strategy → practice → strategy）\n- 用户可能建立不合理关系（如metric → pitfall，无语义意义）\n\n**发现缺陷**：\n- ❌ relations ID引用完整性未校验：from/to ID不存在时，validator不报错\n- ❌ 循环依赖检测缺失：AI或用户可能建立A→B→C→A的循环关系\n- ❌ 关系语义合理性未校验：measures只能metric→strategy，但用户可能写metric→pitfall\n\n**建议改进**：\n- validator校验relations ID引用完整性（from/to ID必须在library中存在）\n- validator检测循环依赖（A→B→C→A时报错）\n- 定义关系语义约束表（measures只能metric→strategy等），validator校验\n\n---\n\n## 三、内部矛盾和冲突\n\n### 问题7：决策3与决策1的矛盾\n\n**决策3**：\n```\nknowledge实体可单向关联architecture实体（单向关联）\n```\n\n**决策1**：\n```\nblueprintType互斥：architecture | domain-knowledge（无hybrid）\n```\n\n**矛盾点**：\n- 如果blueprintType=domain-knowledge，library中不存在architecture实体（capabilities等）\n- 此时跨类型关联（strategy → capability）无法建立（capability不存在）\n- 决策3的单向关联假设失效\n\n**发现矛盾**：\n- ❌ 决策3假设knowledge实体可以关联architecture实体，但决策1禁止混合蓝图\n- ❌ \"不强加architecture关联\"的补充说明，在纯domain-knowledge蓝图中等价于\"无法关联\"\n\n**建议改进**：\n- 修改决策1：允许hybrid蓝图类型，或允许domain-knowledge蓝图中可选添加architecture实体\n- 或修改决策3：删除跨类型关联定义，仅在用户明确需求时才建立跨类型关系\n\n---\n\n### 问题8：severity字段定义与实体类型定义表的矛盾\n\n**实体类型定义表**：\n```\n| strategies | \"strategy\" | level（可选） | - | 3-10 |\n```\n表格显示strategies无severity字段。\n\n**实体字段规范章节**：\n```\nstrategies可选字段未提及severity字段\n```\n\n**Relations关系类型定义**：\n```\n未提及strategy的severity字段，但pitfall有severity字段\n```\n\n**矛盾点**：\n- 实体类型定义表显示strategies无severity，但用户可能误用或自定义severity\n- severity统一为\"严重程度\"，但策略的\"严重程度\"语义不清晰（策略的有效性？策略的风险性？）\n\n**发现矛盾**：\n- ❌ 决策5统一severity字段，但实体类型定义表排除strategies的severity字段\n- ❌ severity语义不明确：painPoint的severity=痛点严重程度，strategy的severity=？（策略有效性？策略风险性？）\n\n**建议改进**：\n- 明确strategies的severity语义：策略风险等级（low=低风险策略，high=高风险策略）\n- 或删除strategies的severity字段定义，明确severity仅适用于painPoints/rules/pitfalls\n\n---\n\n### 问题9：向后兼容保证与schema扩展的冲突\n\n**向后兼容保证**：\n```\nblueprintType默认值\"architecture\"，现有JSON无需修改\n```\n\n**Schema扩展**：\n```\n新增meta.blueprintType字段，新增library.knowledge块\n```\n\n**冲突点**：\n- 现有JSON schema validator可能采用schema-first策略（严格校验所有字段）\n- 新增字段（blueprintType、knowledge）可能导致现有validator报错\"未知字段\"\n- 向后兼容保证依赖于validator的field-first策略（只校验已知字段，放行未知字段）\n\n**发现冲突**：\n- ❌ 设计假设validator采用field-first策略，但现有validator可能采用schema-first策略\n- ❌ 未检查现有validator的实现策略（需要代码审查）\n\n**建议改进**：\n- 检查现有schema_validator.py的实现策略（schema-first or field-first）\n- 如果schema-first，需要改造为field-first + whitelist模式（校验已知字段，放行白名单字段）\n\n---\n\n## 四、遗漏的关键细节\n\n### 问题10：entityType命名规范缺失\n\n**设计假设**：\n```\nentityType字段标识实体类型，validator不校验entityType名称\n```\n\n**遗漏细节**：\n- entityType命名规范未定义（推荐camelCase？允许任意字符串？允许中文？）\n- entityType与knowledge数组名称的映射关系未定义（如`entityType=\"painPoint\"`对应`painPoints`数组）\n- 用户自定义entityType时，AI如何匹配到对应的数组？\n\n**发现遗漏**：\n- ❌ entityType命名规范未定义（大小写、字符集、长度限制）\n- ❌ entityType与数组名称的映射规则未定义（`entityType=\"caseStudy\"`应放在哪个数组？）\n\n**建议改进**：\n- 定义entityType命名规范：camelCase，至少3字符，仅字母，推荐与数组名称匹配\n- 定义entityType与数组名称映射：`entityType=\"painPoint\"` → `painPoints`数组，用户自定义entityType → 对应数组名称需手动指定\n\n---\n\n### 问题11：hints模板的编写质量保证缺失\n\n**设计假设**：\n```\nhints模板包含checklist，AI从\"痛点：...\"描述中自动解析实体类型\n```\n\n**遗漏细节**：\n- hints模板编写质量如何保证？（checklist条目格式不规范时，AI解析出错）\n- hints模板的测试策略未定义（如何验证hints模板的有效性？）\n- 行业模板的覆盖度如何评估？（跨境电商模板是否覆盖关键痛点？）\n\n**发现遗漏**：\n- ❌ hints checklist条目格式规范未定义（\"痛点：...\"格式是唯一标准吗？）\n- ❌ hints模板的测试策略未定义（AI解析checklist时，提取准确率如何测试？）\n- ❌ hints模板覆盖度评估缺失（如何确保模板包含行业关键实体？）\n\n**建议改进**：\n- 定义checklist条目格式规范：`实体类型：具体条目1、条目2`，允许AI自动解析\n- 定义hints模板测试策略：生成10个测试蓝图，验证AI提取准确率（>80%）\n- 定义hints模板覆盖度评估：每个实体类型至少3个典型条目，覆盖率>90%\n\n---\n\n### 问题12：freeflow渲染器的降级策略缺失\n\n**设计假设**：\n```\nfreeflow渲染knowledge实体，定义视觉样式\n```\n\n**遗漏细节**：\n- freeflow渲染大量实体时的性能降级策略未定义（100+实体时如何处理？）\n- freeflow渲染复杂嵌套字段时的容错策略未定义（用户自定义字段嵌套层级>3时如何显示？）\n- freeflow渲染错误entityType时的fallback策略未定义（未知entityType如何显示？）\n\n**发现遗漏**：\n- ❌ 性能降级策略缺失：超过50实体时分页渲染或简化连线\n- ❌ 容错策略缺失：复杂嵌套字段降级为文本卡片，避免渲染崩溃\n- ❌ fallback策略缺失：未知entityType使用默认灰色样式\n\n**建议改进**：\n- 定义性能上限：超过50实体时简化渲染（隐藏次要连线，聚类显示）\n- 定义容错策略：嵌套字段>3层级时显示为`{...}`文本卡片\n- 定义fallback样式：未知entityType使用灰色默认样式 + generic图标\n\n---\n\n### 问题13：实施阶段的质量保证缺失\n\n**设计假设**：\n```\nPhase 1 → Phase 2 → Phase 3顺序实施，每个Phase完成后回归测试\n```\n\n**遗漏细节**：\n- Phase 1验收标准\"AI可参照提取\"如何量化？（提取准确率？）\n- Phase 2验收标准\"validator校验核心字段\"如何测试？（单元测试覆盖率？）\n- Phase 3验收标准\"freeflow渲染knowledge实体\"如何验证？（渲染质量评估？）\n\n**发现遗漏**：\n- ❌ Phase验收标准缺乏量化指标（准确率、覆盖率、渲染质量）\n- ❌ 回归测试的具体测试用例未定义（现有architecture蓝图的测试清单）\n- ❌ 跨Phase集成测试策略缺失（Phase 1 + Phase 2 + Phase 3集成后如何测试？）\n\n**建议改进**：\n- 定义量化验收标准：AI提取准确率>80%，validator单元测试覆盖率>90%，freeflow渲染质量评分>8/10\n- 定义回归测试清单：现有10个architecture蓝图必须通过validator，导出视图不变\n- 定义集成测试策略：生成5个domain-knowledge蓝图，完整流程验证（提取→校验→渲染→导出）\n\n---\n\n## 五、实施风险低估\n\n### 问题14：Phase 2工作量低估\n\n**设计估算**：\n```\nPhase 2：Validator改造（4-6小时）\n```\n\n**对抗性质疑**：\n- validator改造可能涉及现有架构重构（schema-first → field-first）\n- validator单元测试编写可能超出1-2小时（需要覆盖architecture、domain-knowledge、hybrid、用户自定义等场景）\n- validator集成到cli.py可能需要修改多个命令（`--plan`、`--validate`、`--export`）\n\n**发现风险**：\n- ❌ validator改造工作量可能低估（现有validator架构不明确，可能需要重构）\n- ❌ 单元测试编写工作量低估（需要覆盖10+测试场景）\n- ❌ 集成工作量低估（需要修改多个cli命令）\n\n**建议改进**：\n- 调整Phase 2工作量估算：validator改造（3-4小时），单元测试（2-3小时），cli集成（1-2小时），总计6-9小时\n- 新增Phase 2.5：validator架构审查（检查现有validator实现策略，0.5-1小时）\n\n---\n\n### 问题15：Phase 3技术难度低估\n\n**设计估算**：\n```\nPhase 3：导出引擎改造（6-8小时）\n```\n\n**对抗性质疑**：\n- freeflow渲染器改造可能涉及布局算法重构（从layer-based到entityType-based）\n- freeflow渲染knowledge实体需要新增样式系统（颜色、形状、图标、severity分级）\n- relations关系连线渲染需要新增箭头样式系统（实线、虚线、双向箭头）\n\n**发现风险**：\n- ❌ freeflow布局算法重构技术难度高（从layer-based改为entityType-based clustering）\n- ❌ 样式系统设计复杂（颜色映射、形状渲染、图标集成、severity分级）\n- ❌ 关系连线渲染复杂（不同关系类型的箭头样式、避免连线交叉）\n\n**建议改进**：\n- 调整Phase 3工作量估算：布局算法重构（3-4小时），样式系统（2-3小时），连线渲染（2-3小时），cli集成（1小时），总计8-11小时\n- 新增Phase 3.5：freeflow渲染器原型验证（验证knowledge实体渲染可行性，2小时）\n\n---\n\n### 问题16：向后兼容测试覆盖率不足\n\n**设计假设**：\n```\n所有现有architecture蓝图JSON必须通过validator校验\n```\n\n**对抗性质疑**：\n- 现有多少个architecture蓝图？（demos目录下的蓝图数量）\n- 回归测试清单未定义（具体测试哪些蓝图？）\n- 导出视图兼容性未测试（现有architecture蓝图的导出视图是否改变？）\n\n**发现风险**：\n- ❌ 现有architecture蓝图数量未明确，回归测试覆盖率不足\n- ❌ 导出视图兼容性未测试（freeflow渲染knowledge样式后，architecture实体的渲染是否受影响？）\n- ❌ 性能兼容性未测试（新增knowledge渲染逻辑后，architecture蓝图导出速度是否下降？）\n\n**建议改进**：\n- 定义回归测试清单：遍历demos目录所有architecture蓝图（预计10-15个），逐一测试validator + export\n- 定义导出视图兼容性测试：对比新旧导出结果（SVG diff），确保architecture视图不变\n- 定义性能基准测试：导出速度应保持不变（允许±10%波动）\n\n---\n\n## 六、质量问题\n\n### 问题17：文档结构不一致\n\n**发现**：\n- 实体字段规范章节详细（painPoints、strategies、rules等），但relations关系类型定义简略\n- 导出视图渲染设计章节详细（样式定义），但AI提取指南章节简略（提取流程）\n- Validator改造设计章节详细（代码示例），但实施路径章节简略（工作量估算）\n\n**建议改进**：\n- 补充relations关系类型详细定义（每个关系类型的语义、适用场景、错误示例）\n- 补充AI提取详细流程（实体提取顺序的详细步骤、错误处理、hints解析逻辑）\n- 补充实施路径详细清单（每个Phase的文件改动列表、测试用例清单、验收标准）\n\n---\n\n### 问题18：术语定义不一致\n\n**发现**：\n- \"domain-knowledge蓝图\"在不同章节表述不一致（有时称\"knowledge蓝图\"，有时称\"know-how蓝图\"，有时称\"领域知识图谱\"）\n- \"blueprintType\"字段名称与\"蓝图类型\"概念混用（文档未明确区分字段名和概念名）\n- \"severity\"字段在不同实体类型中语义不一致（painPoint的severity=痛点严重程度，strategy的severity=？）\n\n**建议改进**：\n- 统一术语：domain-knowledge蓝图（标准术语），knowledge蓝图（简写），禁止使用\"know-how蓝图\"、\"领域知识图谱\"\n- 统一字段名与概念名：blueprintType（字段名），蓝图类型（概念名），明确区分\n- 统一severity语义：severity=严重程度/风险等级，明确每个实体类型的severity语义\n\n---\n\n### 问题19：示例数据真实性不足\n\n**发现**：\n- 实体字段示例过于简单（如painPoint只有id/name/entityType，缺少真实业务上下文）\n- relations关系示例过于抽象（如\"测款节奏策略 → ROI不稳\"，缺少完整JSON示例）\n- 跨境电商hints模板的checklist过于简化（如\"痛点：ROI不稳\"，缺少具体业务场景描述）\n\n**建议改进**：\n- 补充完整JSON示例：包含10+实体的完整domain-knowledge蓝图JSON\n- 补充relations完整示例：包含from/to/type/label的完整relations数组\n- 补充跨境电商完整hints模板：包含业务上下文（如\"痛点：ROI不稳（欧美市场电商类目，ROAS目标>3.0但实际波动2.0-5.0）\")\n\n---\n\n## 七、对抗性评审总结\n\n### 高危问题（P0，必须修复）\n\n| 问题 | 影响 | 修复建议 |\n|------|------|---------|\n| 问题1：AI判断意图不可靠 | 用户需求被误解，生成错误蓝图类型 | 新增判断优先级 + 手动覆盖机制 |\n| 问题4：混合蓝图处理逻辑缺失 | 用户混合需求被强制简化，丢失部分需求 | 允许hybrid蓝图类型或可选architecture实体 |\n| 问题7：决策3与决策1矛盾 | 跨类型关联失效，无法建立strategy→capability关系 | 允许hybrid蓝图或删除跨类型关联定义 |\n| 问题9：向后兼容保证与schema扩展冲突 | 现有validator可能报错，向后兼容失效 | 检查现有validator实现策略 + 改造方案 |\n| 问题14：Phase 2工作量低估 | 实施延期，资源不足 | 调整工作量估算6-9小时 |\n\n### 中危问题（P1，应该修复）\n\n| 问题 | 影响 | 修复建议 |\n|------|------|---------|\n| 问题2：扩展字段完全放行 | 下游工具可能崩溃 | 定义soft schema + 容错设计 |\n| 问题3：freeflow布局算法未适配 | knowledge实体无法正确布局 | 定义布局策略 + clustering算法 |\n| 问题6：relations完整性约束缺失 | 循环依赖、不合理关系 | ID引用校验 + 循环依赖检测 + 语义约束 |\n| 问题10：entityType命名规范缺失 | 用户自定义实体命名混乱 | 定义命名规范 + 映射规则 |\n| 问题15：Phase 3技术难度低估 | 实施延期，质量不达标 | 调整工作量估算8-11小时 |\n| 问题16：向后兼容测试不足 | 现有蓝图导出视图可能受影响 | 定义回归测试清单 + diff对比 |\n\n### 低危问题（P2，建议修复）\n\n| 问题 | 影响 | 修复建议 |\n|------|------|---------|\n| 问题5：用户自定义实体边界模糊 | 命名冲突、关系类型不清 | 定义命名冲突策略 + 通用关系类型 |\n| 问题8：severity语义矛盾 | strategy的severity语义不清晰 | 明确strategy severity语义或删除定义 |\n| 问题11：hints编写质量保证缺失 | AI提取准确率低 | 定义格式规范 + 测试策略 + 覆盖度评估 |\n| 问题12：freeflow降级策略缺失 | 性能问题、渲染崩溃 | 定义性能上限 + 容错策略 + fallback样式 |\n| 问题13：实施质量保证缺失 | 验收标准模糊、测试覆盖不足 | 定义量化验收标准 + 测试清单 + 集成测试 |\n| 问题17：文档结构不一致 | 阅读困难、理解歧义 | 补充详细定义章节 |\n| 问题18：术语定义不一致 | 理解歧义 | 统一术语使用 |\n| 问题19：示例数据真实性不足 | 理解困难 | 补充完整JSON示例 |\n\n---\n\n## 八、修复优先级建议\n\n**立即修复（P0）**：\n- 问题1、4、7、9、14 → 这些问题直接影响设计可行性和实施成功率\n\n**短期内修复（P1）**：\n- 问题2、3、6、10、15、16 → 这些问题影响实施质量和稳定性\n\n**长期迭代修复（P2）**：\n- 问题5、8、11、12、13、17、18、19 → 这些问题影响使用体验和文档质量\n\n---\n\n## 九、对抗性评审结论\n\n**总体评价**：\n- 设计思路清晰，核心决策合理（强核心+弱扩展、freeflow渲染、单向关联）\n- 但存在5个高危问题，直接影响设计可行性和实施成功率\n- 中危问题影响实施质量和稳定性，需要在实施前修复\n- 低危问题可以在实施过程中迭代修复\n\n**修复建议**：\n- 修复P0问题后，重新审查设计文档\n- 补充缺失的关键细节（entityType命名规范、hints测试策略、freeflow降级策略）\n- 调整工作量估算（Phase 2: 6-9小时，Phase 3: 8-11小时）\n- 定义量化验收标准和回归测试清单\n\n**下一步**：\n- 修复高危问题\n- 补充缺失细节\n- 调整工作量估算\n- 重新提交设计文档审查\n\n---\n\n**对抗性评审完成日期**: 2026-04-28\n**评审者**: Claude Code（对抗性视角）\n\nArchive v0.14.1: 139 files, 396353 bytes\n\nFiles: demos/common.blueprint.json (23013b), demos/finance.blueprint.json (6005b), demos/manufacturing.blueprint.json (6161b), demos/retail.blueprint.json (5058b), demos/screenshots/retail-arch.svg (9274b), evals/defect-taxonomy.json (313b), evals/export-integrity-thresholds.json (145b), evals/export-scoring-schema.json (352b), evals/fixtures/route-architecture.json (359b), evals/fixtures/route-evolution.json (381b), evals/fixtures/route-freeflow.json (234b), evals/README.md (1064b), plans/2026-04-28-domain-knowledge-v2.md (56286b), PURE_SKILL_CLEANUP.md (11296b), README.md (18735b), README.zh-CN.md (16512b), REFACTOR_SUMMARY.md (6409b), references/architecture-design-system.md (6986b), references/architecture-diagram-design.md (11111b), references/architecture-templates/microservices.md (2441b), references/architecture-templates/serverless.md (2305b), references/authoring-rules.md (256b), references/blueprint-schema.md (231b), references/blueprint-skill-optimization-proposal.md (18110b), references/domain-knowledge-design-adversarial-review.md (22970b), references/domain-knowledge-design-v2.md (22113b), references/domain-knowledge-entities-extension-design.md (47457b), references/domain-knowledge-test-eval-design.md (29292b), references/entities-schema.md (5653b), references/implementation-plan.md (12463b), references/industry-packs.md (254b), references/knowledge-entities-schema.md (4017b), references/knowledge-self-check.md (2603b), references/layout-quality-check.md (2428b), references/prompt-orchestration-templates.md (8925b), references/schema-refactor-proposal.md (16318b), references/schema-refactor-v2-actionable.md (29130b), references/systems-schema.md (3162b), references/test-and-eval-strategy.md (34890b), references/theme-dark.md (4505b), references/visual-enhancement-plan.md (9770b), reports/phase0_final_report.json (1826b), reports/phase0_migration_report.json (215b), reports/phase1_accuracy_report_fixed.json (2806b), reports/phase1_accuracy_report.json (3622b), reports/phase3_ab_comparison_report.json (3744b), reports/schema-refactor-complete-final-report.md (11630b), reports/schema-refactor-final-evaluation-report.md (12349b), reports/schema-refactor-implementation-report.md (7092b), reports/score.txt (8b), reports/validate.json (29847b), reports/validate.report.md (9502b), scripts/business_blueprint/assets/viewer.html (28441b), scripts/business_blueprint/clarify.py (9747b), scripts/business_blueprint/cli.py (9373b), scripts/business_blueprint/diff_patcher.py (7370b), scripts/business_blueprint/export_drawio.py (644b), scripts/business_blueprint/export_excalidraw.py (710b), scripts/business_blueprint/export_html.py (11555b), scripts/business_blueprint/export_integrity.py (5225b), scripts/business_blueprint/export_knowledge.py (32098b), scripts/business_blueprint/export_mermaid.py (4153b), scripts/business_blueprint/export_routes.py (5332b), scripts/business_blueprint/export_svg.py (150450b), scripts/business_blueprint/export_text.py (2189b), scripts/business_blueprint/export_theme.py (4876b), scripts/business_blueprint/fixtures/baseline/common.svg (24513b), scripts/business_blueprint/fixtures/baseline/finance.svg (10434b), scripts/business_blueprint/fixtures/baseline/manufacturing.svg (10923b), scripts/business_blueprint/fixtures/baseline/retail.svg (9274b), scripts/business_blueprint/generate.py (4026b), scripts/business_blueprint/intent_resolver.py (6870b), scripts/business_blueprint/knowledge_self_check.py (6867b), scripts/business_blueprint/knowledge_validate.py (12699b), scripts/business_blueprint/migrations/v1_to_v2.py (4703b), scripts/business_blueprint/model.py (2131b), scripts/business_blueprint/normalize.py (2651b), scripts/business_blueprint/projection.py (6258b), scripts/business_blueprint/prompt_generator.py (3097b), scripts/business_blueprint/refine.py (6160b)\n\nFile v0.14.1:SKILL.md\n\n---\nname: kai-business-blueprint\ndescription: Use when turning presales requirements, meeting notes, or solution materials into editable business capability blueprints, swimlane flows, and application architecture diagrams. Use when generating blueprint JSON, static HTML viewers, or exporting to SVG, draw.io, Excalidraw, or Mermaid formats. When no standard export template applies, default to free-flow output.\n---\n\n# Business Blueprint Skill\n\nUse the Python scripts in this repository as the execution surface.\n\n## Output Directory\n\nAll generated files (blueprint JSON, viewers, exports) go into `projects/workspace/` — not the repository root.\n\n```bash\npython scripts/business_blueprint/cli.py --plan projects/workspace/solution.blueprint.json --from \"...\"\npython scripts/business_blueprint/cli.py --project projects/workspace/solution.blueprint.json\npython scripts/business_blueprint/cli.py --export projects/workspace/solution.blueprint.json\n```\n\n## Industry Selection\n\nChoose `--industry` from exactly one of: `\"common\"`, `\"finance\"`, `\"manufacturing\"`, `\"retail\"`. Select the closest match based on the user's domain and materials; do not invent other values.\n\n| Industry | Hints content |\n|----------|-------------|\n| `common` | No hints — generic domains |\n| `finance` | Risk control, credit, compliance, customer profile, etc. |\n| `manufacturing` | Production planning, quality, warehouse, supply chain, etc. |\n| `retail` | Store operations, membership, POS, order fulfillment, etc. |\n\n## How to Generate a Blueprint\n\nThe AI agent is responsible for entity extraction. The Python tool handles JSON writing, visualization, and export.\n\n### Step 1: Read industry hints\n\nRead the seed template at `business_blueprint/templates/{industry}/seed.json` and get the `industryHints.checklist`.\n\n### Step 2: Extract entities from source text\n\nUsing the user's source material AND the industry hints checklist, extract:\n- **capabilities**: business capability areas (name, description)\n- **actors**: roles/people involved (name)\n- **flowSteps**: business process steps (name, actorId, capabilityIds, stepType)\n- **systems**: IT systems that support capabilities\n - See `references/entities-schema.md` for all entity field definitions\n - See `references/systems-schema.md` for systems category/layer rules\n - See `scripts/business_blueprint/templates/common/seed.json` for field examples\n\n### Step 3: Write the blueprint JSON\n\nWrite the JSON file directly to the output path. Use this schema:\n\n```json\n{\n \"version\": \"1.0\",\n \"meta\": {\n \"title\": \"...\",\n \"industry\": \"retail\",\n \"revisionId\": \"rev-YYYYMMDD-NN\",\n \"parentRevisionId\": null,\n \"lastModifiedAt\": \"ISO8601\",\n \"lastModifiedBy\": \"ai\"\n },\n \"context\": {\n \"goals\": [],\n \"scope\": [],\n \"assumptions\": [],\n \"constraints\": [],\n \"sourceRefs\": [{\"type\": \"inline-text\", \"excerpt\": \"...\"}],\n \"clarifyRequests\": [],\n \"clarifications\": []\n },\n \"library\": {\n \"capabilities\": [\n {\"id\": \"cap-xxx\", \"name\": \"...\", \"level\": 1, \"description\": \"...\", \"ownerActorIds\": [], \"supportingSystemIds\": []}\n ],\n \"actors\": [\n {\"id\": \"actor-xxx\", \"name\": \"...\"}\n ],\n \"flowSteps\": [\n {\"id\": \"flow-xxx\", \"name\": \"...\", \"actorId\": \"actor-xxx\", \"capabilityIds\": [\"cap-xxx\"], \"systemIds\": [], \"stepType\": \"task\", \"inputRefs\": [], \"outputRefs\": []}\n ],\n \"systems\": [\n {\"id\": \"sys-xxx\", \"kind\": \"system\", \"name\": \"...\", \"aliases\": [], \"description\": \"...\", \"resolution\": {\"status\": \"canonical\", \"canonicalName\": \"...\"}, \"capabilityIds\": [\"cap-xxx\"]}\n ]\n },\n \"relations\": [\n {\"id\": \"rel-xxx\", \"type\": \"supports\", \"from\": \"sys-xxx\", \"to\": \"cap-xxx\", \"label\": \"支撑\"}\n ],\n \"views\": [],\n \"editor\": {\"fieldLocks\": {}, \"theme\": \"enterprise-default\"},\n \"artifacts\": {}\n}\n```\n\n### Step 4: Generate visualizations\n\n```bash\npython scripts/business_blueprint/cli.py --export \n```\n\nThis generates SVG + HTML viewer by default. Use `--format drawio|excalidraw|mermaid` for other formats.\n\n## Export View Selection Policy\n\nTreat export view choice as a routing decision, not a styling preference.\n\n- If a request matches a supported, standard export template, use that template.\n- If there is no standard export template for the requested diagram, fall back to `freeflow`.\n- Do **not** substitute `swimlane`, `matrix`, `product tree`, or other generic views just because they are available.\n- When embedding a blueprint diagram into a report or ad hoc analysis, `freeflow` is the safe default unless the user explicitly asks for a supported standard template.\n\n### Step 5: Generate downstream projection\n\n```bash\npython scripts/business_blueprint/cli.py --project \n```\n\nThis generates `solution.projection.json`, the canonical machine projection consumed by downstream report/slide workflows.\n\n## Workflow Decision Tree\n\n```\nUser provides raw requirements / meeting notes?\n → AI agent reads hints, extracts entities, writes blueprint JSON\n → Optionally run --project for downstream machine handoff\n → Then run --export for visualization\n\nUser needs diagram files (SVG, draw.io, etc.)?\n → --export (default: SVG + HTML viewer)\n\nUser unsure about blueprint quality?\n → --validate\n\nUser wants downstream report / slide generation?\n → --project\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `--plan --from ` | Generate empty blueprint JSON from source text (AI should prefer writing JSON directly) |\n| `--project ` | Generate canonical projection JSON for downstream skills |\n| `--export ` | Export SVG + HTML viewer (default), or use `--format` for other formats |\n| `--validate ` | Validate a blueprint and print JSON results |\n\n**Execution**: Run directly as scripts:\n```bash\npython scripts/business_blueprint/cli.py --plan ...\npython scripts/business_blueprint/cli.py --export ...\n```\n\n## Export Formats\n\n| Format | File | Use Case |\n|--------|------|----------|\n| `svg` (default) | `solution.exports/solution.svg` + HTML viewer | Quick preview, embedding |\n| `drawio` | `solution.exports/solution.drawio` | Editable diagrams |\n| `excalidraw` | `solution.exports/solution.excalidraw` | Whiteboard-style diagrams |\n| `mermaid` | `solution.exports/solution.mermaid.md` | GitHub-native rendering |\n\n## Collaboration Boundary\n\nThis skill produces **semantic intermediate artifacts**. Downstream skills consume them:\n\n- `report-creator` consumes `solution.projection.json` → assembles reports\n- `slide-creator` consumes `solution.projection.json` → assembles presentations\n- Other skills may consume `relations` → generate PlantUML or other diagram syntax\n- Downstream skills should **never directly edit** `solution.blueprint.json`\n- `solution.handoff.json` is viewer-only metadata, not a downstream narrative input\n\n## Sandbox Execution\n\nWhen running in an isolated Python sandbox (Jupyter, notebook, cloud REPL) that auto-installs dependencies:\n\n1. **The sandbox uses scripts directly.** Run execution scripts from the repository root:\n ```python\n import subprocess\n subprocess.run([\"python\", \"scripts/business_blueprint/cli.py\", \"--export\", \"solution.blueprint.json\"])\n ```\n - `sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))` — will raise NameError\n - `subprocess.run([\"business-blueprint\", ...])` — sandbox runs Python cells, not shell\n - `os.system()` — same reason\n\n## Architecture Diagram Generation\n\nWhen user requests an architecture diagram (keywords: \"架构图\", \"architecture diagram\", \"--export\", \"diagram\"):\n\n1. Read `references/architecture-design-system.md` for the complete design system.\n2. Read the appropriate template from `references/architecture-templates/` based on the user's domain:\n - AWS/Serverless/Lambda → `serverless.md`\n - Microservices/Kubernetes/微服务 → `microservices.md`\n - Other → use `serverless.md` as a structural reference\n3. Read the blueprint JSON to extract entities and flow steps.\n4. Generate a self-contained HTML file with inline SVG following the design system rules.\n5. Write the output file to the same directory as the blueprint JSON.\n\nIf the request does not match one of the supported standard templates above, stay on the default `freeflow` export path. Do not switch to another generic view type as a fallback.\nIf a standard template would create a squeezed, clipped, or overcrowded diagram, stop using the fixed template geometry and fall back to `freeflow` or a wrapped multi-row layout.\n\n### Route eligibility matrix\n\nUse an explicit route contract before rendering:\n\n| Route | Structural prerequisites | First fallback | Terminal behavior |\n|------|---------------------------|----------------|-------------------|\n| `freeflow` | Any valid blueprint with at least one renderable node or relation | None | If integrity still fails, export exits non-zero with a structural diagnostics payload |\n| `architecture-template` | Recognizable L→R architecture shape, categorized systems, limited per-layer density, and no route-breaking overflow risk | `freeflow` | Same as above |\n| `poster` | Clear layer/group structure with bounded peer density per row or wrapped-row support | wrapped poster or `freeflow` | Same as above |\n| `swimlane` | Actor-owned flow steps with meaningful lane grouping | `freeflow` | Same as above |\n| `hierarchy` | Stable tree/group relationship with low ambiguity in parent-child grouping | `freeflow` | Same as above |\n| `evolution` | Ordered chronological or staged progression data | `freeflow` | Same as above |\n\nDo not invent route heuristics ad hoc inside a renderer. Route eligibility must stay explicit and reviewable.\n\n### Generation Rules\n- Use dark mode by default (`#020617` bg + 40px grid). Only use light mode when the user explicitly asks for it.\n- L→R data flow: Clients(左) → Frontend → Backend → Database(右)\n- Map `systems[].category` to semantic colors from the design system\n- Map `systems[].properties.type == \"aws\"` → AWS Region boundary box\n- Map `systems[].properties.type == \"k8s\"` → Kubernetes Cluster boundary box\n- Use `flowSteps[].seqIndex` for L→R ordering\n- Component sizing: 0-1 cap = small(44px h), 2-4 = medium(80px h), 5+ = large(80px h)\n- Layout must be content-driven. Never force every node in a layer into one fixed row if that creates toothpaste-style squeezing.\n- When a layer has more than 3 peer nodes, or labels/features become tight, wrap into multiple rows or widen the canvas before shrinking the content.\n- Render users/actors as actor labels, badges, or lane headers by default. Do not render them as ordinary system cards unless the user explicitly asks for that visual treatment.\n- Legend must live in a bottom safe area and participate in canvas sizing. Never place the legend as a floating overlay in the top-right corner.\n- Final SVG/HTML height must be derived from the bottom-most node, legend, summary cards, and footer plus padding. Do not use fixed-height wrappers or `overflow: hidden` that can clip the last row.\n- Z-order: bg → grid → title → region → arrows → nodes → legend → cards → footer\n- Component border: `rx=\"8\"`, `stroke-width=\"2\"`\n- Region border: `rx=\"16\"`, `stroke-dasharray=\"8,4\"`, `opacity=\"0.4\"`\n- Geometry-sensitive integrity checks must use the numeric thresholds from `evals/export-integrity-thresholds.json`, not prose heuristics.\n\n### Output\n- Single HTML file: `{blueprint_stem}.html` alongside the blueprint JSON\n- No external dependencies (except Google Fonts CDN for JetBrains Mono)\n- Opens in any browser, printable to PDF\n\n## Error Handling\n\n- If `--validate` returns errors: fix structural issues before proceeding to `--export`.\n- If `--validate` returns only warnings: proceed but note the warnings in any handoff.\n- If Python version < 3.12: the package will refuse to install. Use `python3 -m business_blueprint.cli` with system Python as fallback.\n- If a specialized route fails integrity: fall back to its configured fallback route.\n- If `freeflow` also fails integrity: export exits non-zero with a structural diagnostics payload instead of emitting a silently broken artifact.\n\n## Cross-Platform Scope\n\nPhase 2 does not attempt full Windows terminal parity.\n\nKnown deferred cases:\n- PowerShell pipe quirks beyond documented CLI contract tests\n- console-default encoding issues outside explicit UTF-8 execution paths\n\nAccepted workaround for encoding-sensitive runs:\n# Use scripts directly (pure Skill, no package structure)\n subprocess.run([\"python\", \"scripts/business_blueprint/cli.py\", \"--export\", str(blueprint_path)])\n- set `PYTHONIOENCODING=utf-8` where needed\n\nFile v0.14.1:evals/README.md\n\n# Export Evals\n\nThis directory holds machine-readable export quality inputs, thresholds, and taxonomy data for `kai-business-blueprint`.\n\n## Files\n\n- `export-integrity-thresholds.json` — numeric thresholds for geometry-sensitive integrity checks\n- `defect-taxonomy.json` — canonical defect categories used by tests and eval fixtures\n- `export-scoring-schema.json` — minimal scoring/output schema for export eval runs\n\n## Fixtures\n\n- `fixtures/route-freeflow.json` — generic graph that should stay on `freeflow`\n- `fixtures/route-architecture.json` — categorized architecture graph that should resolve to `architecture-template`\n- `fixtures/route-evolution.json` — dated staged flow that should resolve to `evolution`\n\n## Usage\n\n- Route tests read these fixtures to keep export-family decisions stable.\n- Integrity tests should reference taxonomy ids instead of inventing one-off failure labels.\n- Human-readable failure maps, if needed later, should be generated from these files and test references rather than hand-maintained as the source of truth.\n\nFile v0.14.1:README.md\n\n# kai-business-blueprint\n\n> 售前需求、会议纪要、RFP 材料 → 可编辑的业务能力蓝图、泳道流程图、应用架构图。一份 canonical JSON IR，多个下游导出格式（SVG / draw.io / Excalidraw / Mermaid）。\n\nA [Claude Code](https://claude.ai/claude-code) skill that turns raw presales inputs into canonical business capability blueprints, with a static HTML viewer and multi-format diagram exports.\n\nEnglish | [简体中文](README.zh-CN.md)\n\n---\n\n## Demo\n\nRetail industry blueprint, exported as SVG:\n\n![retail-blueprint](demos/screenshots/retail-arch.svg)\n\nThe SVG is generated by `business-blueprint --export demos/retail.blueprint.json` — the source JSON is in `demos/retail.blueprint.json`, the viewer is `demos/solution.viewer.html`.\n\n---\n\n## Design Philosophy: IR-First Pipeline\n\n### 1. JSON as Canonical Intermediate Representation\n\nEvery workflow converges on `solution.blueprint.json` — the single source of truth. All other artifacts (viewer, SVG, draw.io) are deterministic projections from it.\n\n```\nRaw Text ──(--plan)──→ JSON ──(--generate)──→ Viewer HTML\n │\n ├──(--export)──→ SVG / draw.io / Excalidraw / Mermaid\n │\n └──(--edit)────→ JSON (patch logged) + Viewer refresh\n```\n\nThe IR is:\n- **Version-controllable** — standard JSON, diffs are meaningful\n- **AI-readable** — downstream skills parse `entities`, `relations`, `flowSteps` without HTML parsing\n- **Human-editable** — light fields (labels, names) can be edited without breaking structure\n\n### 2. Progressive Disclosure\n\nThe skill file (`SKILL.md`) is a routing layer — it tells Claude *which* file to read for *which* command. Heavy assets (industry packs, viewer HTML template, export engine) stay on disk until needed.\n\n```\n--plan → only model + generation rules; no CSS, no export engine\n--generate → one viewer.html template + one industry pack\n--export → only the requested export engine; other formats stay on disk\n--validate → schema + rules; no rendering code\n```\n\n### 3. Silicon-Carbon Collaboration\n\n**Input:** Humans write natural language (requirements, meeting notes, RFPs). AI parses into structured entities (Application Systems, Business Capabilities, Process Flows, Actors) and relations.\n\n**Output:** The viewer is a static HTML page — no build step, no JS framework, works offline. Every node is editable in-place, and edits are logged as a JSON patch trail (`solution.patch.jsonl`) for full traceability.\n\n---\n\n## Install\n\n### Claude Code\n\n```bash\ngit clone https://github.com/kaisersong/kai-business-blueprint ~/.claude/skills/kai-business-blueprint\n```\n\nThen: `cd kai-business-blueprint && pip install -e .`\n\n### OpenClaw\n\n```bash\ngit clone https://github.com/kaisersong/kai-business-blueprint ~/.openclaw/skills/kai-business-blueprint\ncd kai-business-blueprint && pip install -e .\n```\n\n---\n\n## Usage\n\n### CLI Commands\n\n| Flag | Purpose |\n|------|---------|\n| `--plan \"text\"` | Parse raw text into canonical blueprint JSON |\n| `--project ` | Derive canonical `solution.projection.json` for downstream skills |\n| `--generate ` | Generate JSON + static HTML viewer package |\n| `--edit ` | Refresh viewer for an existing blueprint (preserves human edits) |\n| `--export ` | Export diagrams (default: free-flow SVG + HTML viewer) |\n| `--export-auto ` | Alias for --export (free-flow SVG + HTML viewer) |\n| `--html ` | Generate self-contained HTML viewer with inline SVG |\n| `--validate ` | Validate blueprint structure, output errors/warnings |\n| `--refine ` | Refine an existing blueprint with `--feedback \"...\"` (LLM produces a structured diff that is applied to a new blueprint) |\n| `--from ` | Read source material from file path |\n| `--industry ` | Apply industry template pack (common, finance, manufacturing, retail, **cross-border-ecommerce**) |\n| `--theme ` | Color theme for output (default: dark) |\n| `--format ` | Export format: svg, drawio, excalidraw, mermaid, all |\n\n### Domain-Knowledge Blueprints (v0.14)\n\nBeyond the architecture-style blueprint (capabilities / actors / flowSteps / systems), the skill now produces **domain-knowledge blueprints** for know-how pitches: pain points, strategies, rules, metrics, practices, pitfalls — six entity types tied together by `solves` / `measures` / `enforces` / `requires` / `prevents` / `causes` relations.\n\nA domain-knowledge blueprint is selected by `meta.blueprintType: \"domain-knowledge\"` (set automatically when you choose a know-how-leaning industry such as `cross-border-ecommerce`, or by AI intent extraction). Three quality-driven mechanisms live in the pipeline:\n\n- **Clarification turn.** Validator rejects a domain-knowledge blueprint with fewer than 3 `clarifyRequests`, each pointing to a specific entity. The AI must surface what it is uncertain about before producing the chart.\n- **Per-entity self-check.** Every knowledge entity carries an optional `_selfCheck` field with `passed` / `questions` arrays. Entities with non-empty `questions` are rendered with a soft amber accent and a `?` glyph so reviewers can spot what still needs verification.\n- **Refine command.** `--refine blueprint.json --feedback \"...\"` asks the LLM to emit an `add` / `modify` / `delete` diff which is then applied to produce a new revision. The diff structure is JSON-Patch-like and can be filtered per-operation before applying.\n\nThe knowledge SVG renderer uses a three-band layout: rules across the top, a `pain → strategy → metric` triptych in the middle (rows aligned by `solves` / `measures` so the dominant lines stay near-horizontal), and `practices` + `pitfalls` capsules at the bottom. Cross-zone connections are cubic Bezier; relations are drawn at three opacity tiers so the primary `solves` / `measures` story stays readable even with 30+ relations.\n\n### Export Quality Contracts\n\n- Export routing is explicit: specialized views are only used when the blueprint structure clearly matches them; otherwise the exporter stays on `freeflow`.\n- SVG output now runs structural integrity checks for missing defs references and basic canvas overflow before an artifact is accepted.\n- Export thresholds and defect taxonomy live under [`evals/`](evals), so route and integrity behavior are backed by machine-readable fixtures rather than prose only.\n- Windows/terminal support is intentionally scoped: the canonical path is `python -m business_blueprint.cli`, and encoding-sensitive runs should use `PYTHONIOENCODING=utf-8` when needed.\n\n### Typical Workflows\n\n**From raw text:**\n```bash\n# Step 1: parse into canonical JSON\nbusiness-blueprint --plan \"ERP supports POS system...\" --from meeting-notes.md --industry retail\n\n# Step 2: generate viewer\nbusiness-blueprint --generate solution.blueprint.json\n\n# Step 3: export diagrams\nbusiness-blueprint --export solution.blueprint.json\n```\n\n**Edit existing blueprint:**\n```bash\n# Edit the JSON manually or let AI edit it\n# Then refresh the viewer (preserves human-edited fields via editor.fieldLocks)\nbusiness-blueprint --edit solution.blueprint.json\n```\n\n**Validate before export:**\n```bash\nbusiness-blueprint --validate solution.blueprint.json\n# Fix errors, then:\nbusiness-blueprint --export solution.blueprint.json\n```\n\n**Prepare downstream machine handoff:**\n```bash\nbusiness-blueprint --project solution.blueprint.json\n```\n\n---\n\n## Outputs\n\n| File | Role |\n|------|------|\n| `solution.blueprint.json` | Canonical IR — single source of truth |\n| `solution.projection.json` | Canonical downstream machine projection |\n| `solution.viewer.html` | Static viewer + light editor |\n| `solution.exports/` | SVG, draw.io, Excalidraw, Mermaid exports |\n| `solution.patch.jsonl` | Edit traceability log (JSON patches) |\n| `solution.handoff.json` | Viewer revision manifest |\n\n### SVG Architecture Export\n\nThe SVG export renders a free-flow L→R architecture diagram:\n\n- **Main flow chain** (center row) — systems connected via flow steps, left to right\n- **Auxiliary systems** (rows above/below) — placed by category (database, security, cloud)\n- **Entry node** (left) — auto-generated from blueprint actors\n- **Semantic arrows** — 4 types with distinct colors/markers: `supports` (green solid), `depends-on` (gray dashed), `flows-to` (blue solid), `owned-by` (yellow dotted)\n- **Semantic node shapes** — diamond for flow steps, left color strip for systems, rounded rects for capabilities, pill shapes for actors\n- **Industry themes** — accent color overlays for retail (orange), finance (blue), manufacturing (gray)\n\nThe layout engine computes positions dynamically with overlap resolution, horizontal alignment, and mid-y collision avoidance. The region boundary box and SVG canvas auto-expand to contain all arrow paths.\n\n---\n\n## Project Structure\n\n```\nkai-business-blueprint/\n├── SKILL.md # Skill definition (routing layer)\n├── business_blueprint/ # Python engine (zero external deps)\n│ ├── cli.py # CLI entry point\n│ ├── generate.py # Blueprint generation from text\n│ ├── model.py # Data model & top-level shape\n│ ├── projection.py # Downstream projection builder\n│ ├── validate.py # Machine-readable validation\n│ ├── clarify.py # Clarification request builder\n│ ├── normalize.py # Entity resolution & synonym merging\n│ ├── viewer.py # HTML viewer package writer\n│ ├── export_theme.py # Shared export theme tokens and semantic colors\n│ ├── export_text.py # Shared SVG text width + wrapping helpers\n│ ├── export_routes.py # Explicit export route resolution\n│ ├── export_integrity.py # Structural export integrity checks + diagnostics\n│ ├── export_svg.py # SVG exporter (two-pass layout, content router, free-flow)\n│ ├── export_drawio.py # draw.io exporter\n│ ├── export_excalidraw.py # Excalidraw exporter\n│ ├── export_mermaid.py # Mermaid markdown exporter\n│ ├── templates/ # Industry packs (common, retail, finance, manufacturing)\n│ ├── assets/ # viewer.html template\n│ └── specs/ # Blueprint schema definitions\n├── references/ # Schema, authoring rules, industry packs\n├── tests/ # Test suite\n├── demos/ # Demo blueprints & exports\n└── examples/ # Sample blueprint JSON\n```\n\n---\n\n## Architecture Rules\n\nThe engine enforces structural rules:\n\n| Rule | Description |\n|------|-------------|\n| **Every capability links to a system** | No orphaned capabilities |\n| **Every flow links to a capability** | No floating flow steps |\n| **Actor → System** | Actors must reference valid system IDs |\n| **No circular relations** | System → Capability → Flow must be DAG |\n\nRun `--validate` to check all rules. Warnings indicate potential issues (e.g., a system with no capabilities), errors block export.\n\n---\n\n## For AI Agents\n\nOther skills should consume blueprint artifacts through prompt orchestration, not through the viewer handoff manifest.\n\n```\n# 1. Prepare the machine artifacts\nbusiness-blueprint --plan solution.blueprint.json --from \"...\"\nbusiness-blueprint --project solution.blueprint.json\n\n# 2. Prompt report-creator with the blueprint/projection artifacts\n\"Use solution.blueprint.json and solution.projection.json to generate a report IR first. Do not render HTML yet.\"\n\n# 3. Prompt slide-creator with the blueprint/projection artifacts\n\"Use solution.blueprint.json and solution.projection.json to generate PLANNING.md first. Do not generate HTML yet.\"\n```\n\nSee [references/prompt-orchestration-templates.md](references/prompt-orchestration-templates.md) for copy-paste prompt templates.\n\n`solution.handoff.json` is only a viewer manifest. Do not use it as report/deck input.\n\n**Extracting structured data:**\n```python\nimport json\n\nwith open(\"solution.blueprint.json\") as f:\n bp = json.load(f)\n\n# Systems\nfor sys in bp[\"library\"].get(\"systems\", []):\n print(f\"System: {sys['name']}\")\n\n# Capabilities\nfor cap in bp[\"library\"].get(\"capabilities\", []):\n print(f\"Capability: {cap['name']}\")\n\n# Relations\nfor rel in bp[\"relations\"]:\n print(f\"{rel['from']} --{rel['type']}--> {rel['to']}\")\n```\n\n---\n\n## Requirements\n\n| Requirement | Version | Notes |\n|-------------|---------|-------|\n| **Python** | >= 3.12 | Zero external dependencies |\n\n---\n\n## Compatibility\n\n| Platform | Version | Install path |\n|----------|---------|--------------|\n| Claude Code | any | `~/.claude/skills/kai-business-blueprint/` |\n| OpenClaw | >= 0.9 | `~/.openclaw/skills/kai-business-blueprint/` |\n\n---\n\n## Version History\n\n**v0.14.0** — Domain-knowledge blueprints: add a second blueprint type for know-how pitches (pain points / strategies / rules / metrics / practices / pitfalls) on top of the existing architecture mode. Three quality-driven mechanisms — clarification turn (validator requires ≥3 entity-targeted clarifyRequests), per-entity self-check (entities surface their own uncertainty as a `?` glyph), and `--refine` command (LLM emits a structured diff that is applied to produce a new revision). New `cross-border-ecommerce` industry pack with depth-validated knowledgeHints; existing retail/finance/manufacturing packs gain `knowledgeHints` blocks marked `template-only-not-domain-validated` so AI must disclose the limitation. Knowledge SVG renderer uses a three-band layout (rules / pain-strategy-metric triptych / practices-pitfalls capsules) with row alignment by `solves` / `measures`, cubic Bezier connections, and three-tier opacity so the dominant story stays readable on dense graphs. Free-flow renderer also switches simple connections from straight lines to Bezier. 85 unit tests (67 new) lock the v2 behaviour.\n\n**v0.13.0** — Intent resolution & label overlap fix: integrate `IntentResolver` + `RuleEngine` into the SVG export pipeline so layer assignment becomes data-driven; resolve label-node overlap on free-flow output.\n\n**v0.10.0** — Quality hardening release: add explicit export route resolution and SVG integrity checks with structured fallback diagnostics; introduce machine-readable eval assets under `evals/` (thresholds, defect taxonomy, route fixtures, scoring schema); improve cross-platform CLI handling for spaced paths, CRLF input, and UTF-8 validation output; split shared export text/theme helpers out of `export_svg.py`; and refine the evolution timeline view so dark cards stay readable and wrapped system pills no longer overflow.\n\n**v0.9.0** — Canonical projection release: add `solution.projection.json` generation via `--project`; formalize prompt-native orchestration templates for report/slide downstream skills; strengthen export routing rules so non-standard diagram requests fall back to free-flow; and ship substantial SVG quality upgrades across poster, swimlane, hierarchy, and evolution views, including dark-theme fixes, label collision handling, width-aware title wrapping, centered card rows, and new regression coverage.\n\n**v0.8.0** — Skill rename: rebranded from `business-blueprint-skill` to `kai-business-blueprint`; updated all GitHub URLs, install paths, and documentation references.\n\n**v0.7.0** — Visual enhancements: 4 semantic arrow types (supports/depends-on/flows-to/owned-by) with distinct colors, dash patterns, and SVG markers; semantic node shapes (diamond for flowStep, left color strip for systems, rounded rects for capabilities, pill for actors); 3 industry theme overlays (retail=#F97316, finance=#3B82F6, manufacturing=#6B7280); HTML template-driven viewer generation (replaces 244 lines of f-strings); architecture layout fix — one column per unique capability; free-flow now renders full relation arrows from `blueprint.relations`; same-column arrow routing uses direct vertical paths; region box covers all system nodes; 46 new tests.\n\n**v0.6.1** — Layout engine genericization: remove all hardcoded company/product names (AWS service mappings, Kingdee product IDs, brand text) from layout and rendering code; `_categorize_system()` now uses language-agnostic keyword matching (Chinese + English); `_layout_layered()` assigns distinct colors per layer instead of category keyword lookup; dark theme node colors increased contrast (brighter fills, bolder strokes); legend rendered behind arrows and nodes (z-order fix) so overlaps never obscure content; product tree and capability matrix auto-derive segments from blueprint data instead of hardcoded IDs.\n\n**v0.6.0** — Free-flow layout engine overhaul: arrow routing with cross-row elbow paths and mid_y collision avoidance; dark theme as default; all user-facing labels in Chinese (legend, footer, summary cards); arrowheads shrunk (8×6px, stroke-width 1.5) for cleaner look; region boundary box and SVG canvas dynamically expand to contain arrow paths; rendering z-order fixed (arrows behind nodes); `--html` flag for standalone viewer; `--format` and `--theme` CLI flags; description section from blueprint context; download SVG button.\n\n**v0.5.0** — Content router & free-flow layout engine: `_content_router()` auto-selects views (architecture, capability map, swimlane, process chain) based on blueprint content; `_layout_free_flow()` computes free-form positions with domain grouping and auto-wrapping; `export_svg_auto()` combines routing + layout; `--export-auto` CLI flag; HTML viewer now dynamically shows tabs only for available views.\n\n**v0.4.0** — HTML viewer & layout fix: self-contained HTML viewer with three inline SVG views (architecture, capability map, swimlane), tab-based navigation, summary cards, dark theme support with grid background.\n\n**v0.3.1** — CLI fixes: `--from` long Chinese text no longer triggers `File name too long`, stdin pipe support for `--plan`, subprocess `text=True`/bytes compatibility guidance.\n\n**v0.2.0** — SVG layout engine: two-pass dynamic layer height, actor overflow fix, title/layer gap, header clipping fix, legend truncation fix.\n\n**v0.1.0** — Initial release: plan/generate/edit/export/validate pipeline, HTML viewer with in-place editing, SVG/draw.io/Excalidraw/Mermaid exports, industry template packs (common, retail, finance, manufacturing).\n\nFile v0.14.1:_meta.json\n\n{\n \"ownerId\": \"kn7bjv9d2ccsjqk1m4edthgtgx82fem8\",\n \"slug\": \"kai-business-blueprint\",\n \"version\": \"0.14.1\",\n \"publishedAt\": 1777539296371\n}\n\nFile v0.14.1:references/architecture-design-system.md\n\n# Architecture Diagram Design System\n\n本文件定义 Agent 生成架构图时使用的完整设计系统。所有颜色、字体、间距、布局规则必须严格遵循。\n\n## 1. 主题\n\n### 暗黑模式（默认）\n\n| Token | 值 | 用途 |\n|-------|-----|------|\n| `bg` | `#020617` | 页面背景（Slate-950） |\n| `canvas` | `#0F172A` | 卡片表面（Slate-900） |\n| `text_main` | `#E2E8F0` | 主文字 |\n| `text_sub` | `#94A3B8` | 副文字 |\n| `border` | `#1E293B` | 边框 |\n| `grid` | `#1E293B` | 网格线（40px pattern） |\n\n暗黑模式是默认输出。除非用户明确要求亮色模式，否则不得切换到亮色主题。\n\n### 亮色模式\n\n| Token | 值 | 用途 |\n|-------|-----|------|\n| `bg` | `#F8FAFC` | 页面背景 |\n| `canvas` | `#FFFFFF` | 卡片表面 |\n| `text_main` | `#0F172A` | 主文字 |\n| `text_sub` | `#64748B` | 副文字 |\n| `border` | `#CBD5E1` | 边框 |\n\n## 2. 字体\n\n- 主字体：`'JetBrains Mono', 'Fira Code', monospace`（Google Fonts CDN 引入）\n- 回退字体：`system-ui, -apple-system, sans-serif`\n\n| 层级 | 字号 | 字重 | 用途 |\n|------|------|------|------|\n| 标题 | 20px | 700 | SVG 主标题 |\n| 副标题 | 13px | 400 | 副标题/注解 |\n| 组件名 | 14px | 600 | 节点名称 |\n| 副标签 | 11px | 400 | 节点描述 |\n| 注解 | 9-10px | 400 | 标签、Legend |\n| Region 标签 | 12px | 600 | Region 名称 |\n\n## 3. 语义色\n\n7 种系统类别，每种定义 fill + stroke（暗黑模式值）：\n\n| 类别 | 填充色 | 描边色 | 用途 |\n|------|--------|--------|------|\n| `frontend` | `rgba(8,51,68,0.4)` | `#22d3ee` | Web、移动端、UI |\n| `backend` | `rgba(6,78,59,0.4)` | `#34d399` | Lambda、API、服务 |\n| `database` | `rgba(76,29,149,0.4)` | `#a78bfa` | DynamoDB、RDS |\n| `cloud` | `rgba(120,53,15,0.3)` | `#fbbf24` | Region 框、CloudFront |\n| `security` | `rgba(136,19,55,0.4)` | `#fb7185` | Security Group、WAF |\n| `message_bus` | `rgba(251,146,60,0.3)` | `#fb923c` | SQS、SNS、EventBridge |\n| `external` | `rgba(30,41,59,0.5)` | `#94a3b8` | 第三方 API、SaaS |\n\n无类别时回退到：fill `#1E293B`，stroke `#94A3B8`。\n\n## 4. 布局规则\n\n### 4.1 L→R 数据流\n\n```\nClients(左) → Frontend → Backend → Database(右)\n```\n\n- Clients 通常放在 Region 框外左侧\n- 其他组件按 `flowSteps[].seqIndex` 排序，从左到右排列\n- 水平间距 40-60px，垂直居中对齐\n\n### 4.2 组件尺寸\n\n根据 capabilities 数量决定：\n\n| 能力数 | 宽度 | 高度 | 用途 |\n|--------|------|------|------|\n| 0-1 | 140px | 44px | 简单组件（SQS 等） |\n| 2-4 | 150px | 80px | 中等组件（Lambda、S3） |\n| 5+ | 160px | 80px | 大组件（API Gateway、DynamoDB） |\n\n所有组件：`rx=\"8\"` 圆角，`stroke-width=\"2\"` 描边。\n\n如果文本、特征列表或标签超出上述尺寸，不得硬压缩成“牙膏图”。优先顺序是：\n1. 增大卡片宽度或高度\n2. 将同层节点换到多行\n3. 扩大画布\n4. 必要时回退到 `freeflow`\n\n禁止通过把整层强行塞成一行、把图例改成浮层、或让底部内容被裁切来维持模板外观。\n\n### 4.3 Region 边界\n\n- 矩形框：`rx=\"16\"`, `stroke-dasharray=\"8,4\"`, 琥珀色 `#F59E0B`, `opacity=\"0.4\"`\n- Region 标签放在框外上方（x=Region左边界+20, y=Region上边界-10）\n- 填充：`none`（仅描边）\n\n### 4.4 Summary Cards\n\n放在架构图底部，3 组卡片，响应式网格布局：\n\n| 卡片 | 颜色 | 内容 |\n|------|------|------|\n| Infrastructure | 琥珀色 `#F59E0B` | 基础设施列表 |\n| Compute | 翠绿色 `#34D399` | 计算资源描述 |\n| Data | 紫色 `#A78BFA` | 数据存储描述 |\n\n每张卡片：`rx=\"10\"`, fill `#0F172A`, stroke `#1E293B`, 宽 340-370px, 高 130px。\n\n### 4.5 分层布局约束\n\n- 分层图中的“层”是语义分组，不是强制单行容器。\n- 每层 `1-3` 个节点时可单行展示。\n- 每层 `4-6` 个节点时默认拆成两行，保持卡片尺寸可读。\n- 每层 `7+` 个节点时应扩大画布或直接回退到 `freeflow`，不要继续压缩。\n- Actor / User 角色默认渲染为边栏标签、badge 或 lane header，不应伪装成普通系统卡片。\n\n### 4.6 Legend 位置\n\n- Legend 默认放在左下或底部保留区。\n- Legend 必须参与整体高度计算，不能作为右上角悬浮遮罩。\n- 禁止将 legend 放在 top-right 覆盖标题区或内容区。\n\n### 4.7 画布尺寸与裁切\n\n- `viewBox` 和最终 `height` 必须覆盖：最底部节点、legend、summary cards、footer，再加至少 `32px` 底部留白。\n- 外层 HTML 容器不得使用固定高度裁切内容。\n- 禁止使用 `overflow: hidden` 裁掉最后一层、legend 或 summary cards。\n- 如果模板内容超出当前画布，应增加画布高度或改为多行布局，而不是截断。\n\n### 4.8 完整性阈值\n\n所有几何类完整性检查必须使用阈值配置，而不是凭渲染器里的临时经验判断。\n\n阈值来源：\n- `evals/export-integrity-thresholds.json`\n\n最小阈值集合：\n- `minLabelClearancePx`\n- `legendBottomMarginPx`\n- `legendContentGapPx`\n- `titleOverflowTolerancePx`\n- `cardTextInsetPx`\n\n只要是以下检查，都必须绑定到阈值：\n- label 与折线拐点、卡片边界的最小安全距离\n- legend 与底部/内容区的安全距离\n- 标题文本的溢出容忍度\n- 卡片正文与边框的内边距\n\n## 5. 视觉元素\n\n### 5.1 箭头\n\n```svg\n\n \n\n```\n\n- 实线箭头：`stroke=\"#64748B\"`, `stroke-width=\"2\"`, `marker-end=\"url(#arrow-solid)\"`\n- 虚线箭头（可选）：`stroke-dasharray=\"4,3\"`, `stroke=\"#475569\"`\n\n### 5.2 网格 Pattern\n\n```svg\n\n \n\n```\n\n### 5.3 节点结构\n\n```svg\n\n \n 名称\n 副标签\n\n```\n\n## 6. Z 序\n\n1. 背景（`#020617` rect）\n2. 网格 pattern\n3. 标题文字\n4. Region 框\n5. 箭头\n6. 节点（rect + text）\n7. Legend（底部保留区）\n8. Summary Cards\n9. Footer\n\n## 7. Blueprint 字段映射\n\n| 视觉概念 | Blueprint 字段 | 推导逻辑 |\n|---------|---------------|---------|\n| 组件色 | `systems[].category` | 直接映射到语义色 |\n| L→R 顺序 | `flowSteps[].seqIndex` | 按 seqIndex 排序 |\n| Region 框 | `systems[].properties.type` | `type == \"aws\"` → Region |\n| 组件大小 | `capabilities` 数量 | 0-1=小, 2-4=中, 5+=大 |\n| 副标签 | `systems[].description` | 取前 2-3 个特征 |\n| 箭头 | `flowSteps[].nextStepIds` | 从 nextStepIds 推导连接 |\n\nFile v0.14.1:references/architecture-diagram-design.md\n\n# Architecture Diagram Generator — Design Document (v2)\n\n## Context\n\n当前 `export_svg.py` 包含复杂的自动布局引擎（`_layout_free_flow`、`_content_router`、`_render_free_flow_svg`），产出却是网格堆叠的卡片，不是真正的架构图。更关键的是：**Python 代码太重，沙箱频繁出问题**——依赖链长、`importlib.metadata` 不稳定、`__file__` 在 Jupyter 中未定义。\n\n参考项目 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) 走了完全不同的路：**SKILL.md 定义设计系统，Claude 按规则直接生成 HTML+SVG，零 Python 依赖。**\n\n本文档设计 v2 重构方案：**核心架构图生成完全脱离 Python，由 Claude 读取 SKILL.md → 直接输出 HTML+SVG。Python 只做 JSON 校验和格式转换（draw.io/excalidraw/mermaid）。**\n\n## 核心决策\n\n### 1. Python 轻量化\n\n| 当前 | v2 |\n|------|-----|\n| `export_svg.py` 1500+ 行布局引擎 | 保留 300 行核心常量，移除自动布局 |\n| `export_html.py` 200+ 行内嵌 SVG 构建 | 改为直接输出预生成的 SVG |\n| `--export` 默认调 9 个 Python 函数 | Claude 生成 HTML+SVG（主），Python 格式转换（备） |\n| 依赖 `importlib.metadata`、`math`、`pathlib` | 只依赖 `json`、`pathlib`（stdlib） |\n| 沙箱需 `pip install kai-business-blueprint` | 沙箱只需 `json.load()` + 写文件，或 Claude 直接生成 |\n\n### 2. Claude 生成架构图的具体机制\n\n不是\"Claude 在对话中手写 SVG\"，而是：\n\n```\n1. Claude 读取 blueprint JSON（或用户自然语言描述）\n2. Claude 读取 SKILL.md 中的设计系统规范\n3. Claude 生成 HTML+SVG 文本 → 写入文件\n4. 输出：单个 .html 文件\n```\n\n**在沙箱环境中**，不需要 `pip install`：\n```python\n# 沙箱只需这两行——无第三方依赖\nimport json\nblueprint = json.load(open(\"solution.blueprint.json\"))\n# 然后 Claude 根据 blueprint 数据直接生成 HTML+SVG 字符串并写入文件\n```\n\n**Python 脚本完全退出架构图渲染**——它只做：\n- `--plan`：将用户需求写入 blueprint JSON\n- `--validate`：校验 blueprint 结构\n- `--format drawio/excalidraw/mermaid`：从 blueprint 生成对应格式（这些格式有成熟的 Python 库/字符串拼接即可）\n\n### 3. Blueprint Schema 适配\n\n当前 schema **已有足够字段**，不需要扩展：\n\n| 设计系统概念 | Blueprint 字段 | 映射方式 |\n|------------|---------------|---------|\n| 组件类型/颜色 | `systems[].category` | frontend/backend/database/cloud/security/external |\n| L→R 数据流 | `flowSteps[].seqIndex` + `nextStepIds` | 按 seqIndex 排序，L→R 排列 |\n| Region 边界 | `systems[].properties.type` | `type == \"aws\"` → 包在 AWS Region 框内 |\n| 消息总线 | `systems[].properties.service == \"sqs\"` 等 | SQS/EventBridge/SNS → MessageBus 颜色 |\n| 组件副标题 | `systems[].description` 或 `properties.features` | 取前 2-3 个特征 |\n| 组件大小 | 根据 `capabilities` 数量决定 | 0-1 cap → 小框(60px)，2-4 → 中框(80px)，5+ → 大框(120px) |\n\n**不需要新增字段。** 所有视觉决策都从现有字段推导。\n\n## 设计系统（从参考项目继承）\n\n### 颜色 Palette\n\n| 类型 | 填充色 | 边框色 | 用途 |\n|------|--------|--------|------|\n| Frontend | `rgba(8,51,68,0.4)` | `#22d3ee` | Web、移动端、UI |\n| Backend | `rgba(6,78,59,0.4)` | `#34d399` | Lambda、API Gateway、服务 |\n| Database | `rgba(76,29,149,0.4)` | `#a78bfa` | DynamoDB、RDS、S3 |\n| AWS/Cloud | `rgba(120,53,15,0.3)` | `#fbbf24` | Region 框、CloudFront |\n| Security | `rgba(136,19,55,0.4)` | `#fb7185` | Security Group、WAF |\n| MessageBus | `rgba(251,146,60,0.3)` | `#fb923c` | SQS、SNS、EventBridge |\n| External | `rgba(30,41,59,0.5)` | `#94a3b8` | 第三方 API、SaaS |\n\n### 字体\n- JetBrains Mono（Google Fonts CDN）\n- 组件名：14px / 600\n- 副标签：11px / 400\n- 注解：9px\n- Region 标签：10px / 600\n\n### 布局规则\n- L→R 数据流：Clients(左) → Frontend → Backend → Database(右)\n- Region 虚线框：`rx=\"12\"`, `stroke-dasharray=\"8,4\"`, 琥珀色\n- 组件圆角：`rx=\"6\"`, 1.5px 描边\n- Z 序：箭头 → 节点遮罩 → 节点样式 → 文字 → Legend\n\n## SKILL.md 结构\n\n遵循**渐进披露**原则，SKILL.md 本身不塞设计系统细节：\n\n```\nSKILL.md（路由层，<100行）\n ├── 何时触发架构生成（关键词：architecture diagram, 架构图, --export）\n ├── 读取 references/architecture-design-system.md（完整设计系统）\n ├── 读取 references/architecture-templates/serverless.md（模板）\n └── Claude 生成 HTML+SVG → 写入文件\n\nreferences/architecture-design-system.md（设计系统，~80行）\n ├── 颜色 Palette\n ├── 字体与间距\n ├── 视觉元素（Region框、组件框、箭头）\n └── Z 序规则\n\nreferences/architecture-templates/（模板库）\n ├── serverless.md（AWS Serverless 模板）\n ├── microservices.md（微服务模板）\n └── three-tier.md（三层架构模板）\n```\n\n## Python 代码改动\n\n### 删除（~900 行）\n\n| 文件 | 删除内容 |\n|------|---------|\n| `export_svg.py` | `_content_router()`、`_layout_free_flow()`、`_render_free_flow_svg()`、`export_svg_auto()` |\n| `export_html.py` | `_build_architecture_svg()` 整个函数 |\n\n### 保留（~600 行）\n\n| 文件 | 保留内容 |\n|------|---------|\n| `export_svg.py` | 设计常量（`C_LIGHT`、`C_DARK`、字体、尺寸）、箭头/节点渲染函数、`export_svg()` 三层布局（回退用）、`export_*_svg()` 专业视图 |\n| `export_drawio.py` | 完整保留 |\n| `export_excalidraw.py` | 完整保留 |\n| `export_mermaid.py` | 完整保留 |\n| `cli.py` | 简化：`--export` 默认触发 Claude 生成（见下），`--format drawio/excalidraw/mermaid/all` 调 Python |\n\n### `cli.py` 中 `--export` 新逻辑\n\n**关键设计：** `--export` 既要保证向后兼容（Python 产出基础文件），也要让 Agent 有机会生成增强版架构图。\n\n```python\nif args.export:\n blueprint_path = Path(args.export)\n blueprint = load_json(blueprint_path)\n stem = blueprint_path.stem\n export_dir = blueprint_path.parent / f\"{stem}.exports\"\n export_dir.mkdir(parents=True, exist_ok=True)\n \n fmt = args.export_format or \"svg\"\n \n if fmt == \"svg\":\n # Python 产出经典三层布局 SVG（向后兼容，确保有文件产出）\n export_svg(blueprint, export_dir / \"solution.svg\", theme=args.theme)\n # Agent 在沙箱外读取 blueprint → 按 SKILL.md 生成增强版 HTML+SVG\n # 这是 Agent 的下一步动作，不在 CLI 中执行\n return 0\n \n elif fmt == \"drawio\":\n export_drawio(blueprint, export_dir / \"solution.drawio\")\n elif fmt == \"excalidraw\":\n export_excalidraw(blueprint, export_dir / \"solution.excalidraw\")\n elif fmt == \"mermaid\":\n export_mermaid(blueprint, export_dir / \"solution.mermaid.md\")\n elif fmt == \"all\":\n # Python 产出所有格式（向后兼容）\n export_svg(blueprint, export_dir / \"solution.svg\", theme=args.theme)\n export_capability_map_svg(blueprint, export_dir / \"capability-map.svg\", theme=args.theme)\n export_swimlane_flow_svg(blueprint, export_dir / \"swimlane-flow.svg\", theme=args.theme)\n export_product_tree_svg(blueprint, export_dir / \"product-tree.svg\", theme=args.theme)\n export_matrix_svg(blueprint, export_dir / \"capability-matrix.svg\", theme=args.theme)\n export_drawio(blueprint, export_dir / \"solution.drawio\")\n export_excalidraw(blueprint, export_dir / \"solution.excalidraw\")\n export_mermaid(blueprint, export_dir / \"solution.mermaid.md\")\n # Agent 可在此基础上额外生成增强版架构图 HTML\n return 0\n```\n\n**Agent 的增强流程（CLI 之外）：**\n1. `--export` 完成后，Agent 读取 blueprint JSON\n2. Agent 按 SKILL.md 设计系统规范生成架构图 HTML+SVG\n3. 写入 `{stem}.html` 到同目录\n\n### 沙箱兼容\n\n沙箱不是独立运行的——调用链是 `用户 → Agent(Claude/OpenAI/GLM) → tool call → 沙箱执行Python`。\n\n沙箱中 Agent 始终可用，所以架构生成流程是：\n1. Agent 在沙箱中 `json.load()` 读取 blueprint\n2. Agent 读取 SKILL.md 设计系统规范\n3. Agent 生成 HTML+SVG 字符串 → 通过沙箱 `write_file` 或 `Path.write_text()` 写入\n4. 返回给用户\n\n沙箱不再需要 `pip install kai-business-blueprint`：\n```python\n# 极简沙箱用法——只需 stdlib\nimport json\nfrom pathlib import Path\n\nblueprint = json.loads(Path(\"solution.blueprint.json\").read_text())\n# Agent 根据 blueprint 数据 + SKILL.md 设计系统，直接生成 HTML+SVG 并写入文件\n```\n\n**Python 脚本在沙箱中的角色：JSON 加载 + 校验。** 架构图渲染完全由 Agent 承担。\n\n## 回退策略\n\n由于调用链中 Agent 始终存在（Agent → tool call → 沙箱 → Agent 继续），**不存在\"无 Agent 可用\"的回退场景**。但保留以下回退以防代码层面断裂：\n\n1. **`--export` 时 Python 仍产出 `solution.svg`（三层布局经典版）** — 确保 `--format all` 向后兼容\n2. **`export_html.py` 不再自己构建 SVG** — 改为接受预生成的 SVG 内容参数\n\n三个保障：\n- `--export` 至少产出 `solution.svg`（Python 经典布局）\n- Agent 可在此基础上额外生成 HTML+SVG 架构图\n- `drawio/excalidraw/mermaid` 格式由 Python 稳定产出\n\n## 实施阶段\n\n| 阶段 | 内容 | 可回滚？ |\n|------|------|---------|\n| **Phase 1** | 写 `references/architecture-design-system.md` + 模板 | ✅ 只加文件 |\n| **Phase 2** | 更新 SKILL.md 添加架构图生成路由 | ✅ 只改 SKILL.md |\n| **Phase 3** | 删除 `_content_router`、`_layout_free_flow`、`_render_free_flow_svg` | ⚠️ 需确认无外部依赖 |\n| **Phase 4** | 简化 `cli.py` 和 `export_html.py` | ⚠️ 需测试沙箱兼容 |\n| **Phase 5** | 测试 `aws-serverless.blueprint.json` 生成效果 | — |\n\n## 评审问题应对\n\n| Codex 评审问题 | 应对 |\n|---------------|------|\n| `export_html.py` 导入断裂 | **`export_html.py` 的 `_build_architecture_svg()` 不再自己构建 SVG**，改为接受预生成的 SVG 字符串参数，或回退到三层布局。删除对 `_content_router`、`_layout_free_flow`、`_render_free_flow_svg` 的 import |\n| \"CLI plans, Claude generates\" 无明确机制 | **CLI 产出基础文件（Python 经典布局），Agent 在此基础上生成增强版**。CLI 不返回 0 空文件 |\n| 非交互环境无 Claude | **调用链始终是 Agent → tool call → 沙箱 → Agent**。不存在离线调用场景 |\n| Blueprint 字段不够 | 所有视觉决策从现有字段推导，不需新增 schema |\n| SKILL.md 膨胀 | 设计系统放 `references/`，SKILL.md 只引用 |\n| `--format all` 其他导出 | **保留所有 Python SVG 导出器在 `--format all` 中**，确保向后兼容 |\n| 测试文件断裂 | Phase 3 删除 `test_content_router_and_layout.py` 或重写 |\n\nFile v0.14.1:references/architecture-templates/microservices.md\n\n# Microservices Architecture Template\n\n## 适用场景\n\n用户描述包含：微服务、microservices、service mesh、Kubernetes、K8s、分布式服务等关键词。\n\n## 布局结构\n\n```\nClients → API Gateway → [Service A, Service B, Service C] → [DB A, DB B, Cache, MQ]\n```\n\n这些坐标只是起始参考，不是必须照抄的固定布局。如果服务或数据节点超出当前模板容量：\n- 允许服务列或数据列拆成多行\n- 允许增大画布和 cluster 边界\n- 仍然拥挤时回退到 `freeflow`\n\n不要把所有服务和数据卡片硬塞进同一行，造成牙膏式排版。\n\n## 组件定义\n\n| 组件 | 类别 | x | y | 宽 | 高 | 特征 |\n|------|------|---|---|-----|-----|------|\n| Clients | external | 80 | 280 | 140 | 80 | Web/Mobile |\n| API Gateway | cloud | 310 | 280 | 150 | 80 | Routing, Auth |\n| Service A | backend | 540 | 160 | 150 | 80 | 业务服务 |\n| Service B | backend | 540 | 280 | 150 | 80 | 用户服务 |\n| Service C | backend | 540 | 400 | 150 | 80 | 订单服务 |\n| DB A | database | 780 | 160 | 140 | 80 | 业务数据 |\n| DB B | database | 780 | 280 | 140 | 80 | 用户数据 |\n| Cache | database | 780 | 400 | 140 | 44 | Redis/ElastiCache |\n| MQ | message_bus | 780 | 500 | 140 | 44 | RabbitMQ/Kafka |\n\n## 连接关系\n\n| 从 | 到 | 方向 |\n|----|----|------|\n| Clients | API Gateway | 水平 → |\n| API Gateway | Service A | 水平 → |\n| API Gateway | Service B | 水平 → |\n| API Gateway | Service C | 水平 → |\n| Service A | DB A | 水平 → |\n| Service B | DB B | 水平 → |\n| Service C | Cache | 水平 → |\n| Service C | MQ | 水平 → |\n\n## K8s Cluster Region\n\n- 虚线框：x=290, y=120, width=660, height=450, rx=16\n- 描边：`#FBBF24`, `stroke-dasharray=\"8,4\"`, `opacity=\"0.4\"`\n- 标签：`Kubernetes Cluster`（x=310, y=110）\n- Clients 在 Cluster 框外左侧\n\n## 图例与画布\n\n- Legend 放在左下或底部保留区，不放右上角。\n- 最终 SVG 高度必须包含最底部节点、legend、summary cards 和 footer。\n- 不得用固定高度容器或裁切把底部内容截断。\n\n## Summary Cards\n\n### Gateway (琥珀色)\n- API Gateway routing\n- Authentication & authorization\n- Rate limiting\n- Load balancing\n\n### Services (翠绿色)\n- Microservice A/B/C\n- Independent deployment\n- Service discovery\n- Health monitoring\n\n### Data (紫色)\n- Database per service\n- Redis caching layer\n- Message queue\n- Event-driven communication\n\nFile v0.14.1:references/architecture-templates/serverless.md\n\n# AWS Serverless Architecture Template\n\n## 适用场景\n\n用户描述包含：Lambda、API Gateway、DynamoDB、Serverless、无服务器等关键词。\n\n## 布局结构\n\n```\nClients → CloudFront → API Gateway → Lambda → DynamoDB\n → SQS\n → S3\n```\n\n这些坐标是结构参考，不是必须死守的固定像素模板。如果内容变多、标签变长、或增加额外节点：\n- 先扩容画布或调整节点位置\n- 再把相关节点拆成多行\n- 仍然放不下时回退到 `freeflow`\n\n不要为了维持这一版模板，把整张图挤成单行牙膏布局。\n\n## 组件定义\n\n| 组件 | 类别 | x | y | 宽 | 高 | 特征 |\n|------|------|---|---|-----|-----|------|\n| Clients | external | 80 | 230 | 140 | 80 | Web/Mobile |\n| CloudFront | cloud | 310 | 230 | 140 | 80 | CDN |\n| API Gateway | cloud | 500 | 230 | 160 | 80 | REST API, WebSocket, HTTPS |\n| Lambda | backend | 720 | 230 | 150 | 80 | Functions, Auto-scaling |\n| SQS | message_bus | 720 | 130 | 150 | 44 | Message Queue |\n| S3 | cloud | 720 | 360 | 150 | 80 | Object Storage |\n| DynamoDB | database | 930 | 230 | 160 | 80 | NoSQL, On-demand |\n\n## 连接关系\n\n| 从 | 到 | 方向 |\n|----|----|------|\n| Clients | CloudFront | 水平 → |\n| CloudFront | API Gateway | 水平 → |\n| API Gateway | Lambda | 水平 → |\n| Lambda | SQS | 垂直 ↑ |\n| Lambda | S3 | 垂直 ↓ |\n| Lambda | DynamoDB | 水平 → |\n\n## AWS Region\n\n- 虚线框：x=260, y=110, width=900, height=350, rx=16\n- 描边：`#F59E0B`, `stroke-dasharray=\"8,4\"`, `opacity=\"0.4\"`\n- 标签：`AWS Region: us-east-1`（x=280, y=100）\n- Clients 在 Region 框外左侧\n\n## 图例与画布\n\n- Legend 放在左下或底部保留区，不放右上角。\n- 最终 SVG 高度必须包含最底部节点、legend、summary cards 和 footer。\n- 不得用固定高度容器或裁切把底部内容截断。\n\n## Summary Cards\n\n### Infrastructure (琥珀色)\n- CloudFront CDN distribution\n- API Gateway REST endpoints\n- S3 static asset hosting\n- SQS message queues\n\n### Compute (翠绿色)\n- Lambda functions\n- Auto-scaling to zero\n- Pay-per-invocation\n- 15 min max execution\n\n### Data (紫色)\n- DynamoDB tables\n- On-demand capacity\n- Global secondary indexes\n- Point-in-time recovery\n\nFile v0.14.1:references/authoring-rules.md\n\n# Authoring Rules\n\n- The viewer save action must export a new canonical revision package.\n- `solution.patch.jsonl` records human edits.\n- `editor.fieldLocks` protects human-edited semantic fields.\n- Validation must run before downstream completion claims.\n\nFile v0.14.1:references/blueprint-schema.md\n\n# Blueprint Schema Reference\n\nThe canonical file contains:\n\n- `meta`\n- `context`\n- `library`\n- `relations`\n- `views`\n- `editor`\n- `artifacts`\n\nEntity collections in `library`:\n\n- `capabilities`\n- `actors`\n- `flowSteps`\n- `systems`\n\nFile v0.14.1:references/blueprint-skill-optimization-proposal.md\n\n# Business Blueprint Skill 优化方案\n\n## 问题诊断\n\n### 现状分析\n\n**现有skill定位**：系统架构蓝图生成器\n- 实体类型：capabilities（能力）、actors（角色）、flowSteps（流程）、systems（系统）\n- 输出形式：架构分层图、泳道流程图、系统支撑关系图\n- 适用场景：售前方案设计、IT系统规划、业务流程梳理\n\n**缺失需求**：业务领域know-how知识图谱\n- 痛点挑战、关键策略、平台规则、数据指标、最佳实践、常见误区\n- 用于展示\"我们懂这个领域\"的专业度\n- 客户pitch时需要业务洞察，而非技术架构\n\n### 根本原因\n\nskill设计时将\"业务蓝图\"等同于\"系统架构蓝图\"，实体定义固化在IT系统视角：\n- `systems` 实体强制映射到技术架构层（客户端层、网关层、业务服务层）\n- 缺失\"策略要素\"、\"行业规则\"、\"数据基准\"等业务洞察实体\n- AI只能按IT架构思维提取实体，无法生成领域知识图谱\n\n---\n\n## 设计方案对比\n\n### 方案A：扩展实体类型（最小改动）\n\n**改造思路**：\n在现有`library`中新增实体类型：\n```json\n{\n \"library\": {\n \"capabilities\": [],\n \"actors\": [],\n \"flowSteps\": [],\n \"systems\": [],\n // 新增实体类型\n \"painPoints\": [\n {\"id\": \"pain-001\", \"name\": \"ROI不稳\", \"description\": \"广告投放ROI波动大，缺乏稳定增长路径\", \"severity\": \"high\"}\n ],\n \"strategies\": [\n {\"id\": \"str-001\", \"name\": \"测款节奏\", \"description\": \"3天测款周期，预算分配策略\", \"applicableCapabilityIds\": [\"cap-004\"]}\n ],\n \"platformRules\": [\n {\"id\": \"rule-001\", \"name\": \"Facebook政策红线\", \"description\": \"禁止误导性宣传、过度夸大效果\", \"riskLevel\": \"critical\"}\n ],\n \"metrics\": [\n {\"id\": \"met-001\", \"name\": \"ROAS基准\", \"value\": \">3.0\", \"unit\": \"ratio\", \"benchmarkContext\": \"欧美市场\"}\n ],\n \"bestPractices\": [\n {\"id\": \"bp-001\", \"name\": \"素材迭代周期\", \"description\": \"每7天测试新素材版本，避免疲劳\"}\n ],\n \"pitfalls\": [\n {\"id\": \"pit-001\", \"name\": \"过度依赖单一平台\", \"description\": \"Facebook封号后业务瘫痪风险\", \"impact\": \"critical\"}\n ]\n }\n}\n```\n\n**优点**：\n- 兼容现有JSON schema和export逻辑，改动最小\n- 一个蓝图可以同时包含架构和know-how\n\n**缺点**：\n- 实体职责混淆，一个JSON既要画架构图又要画知识图谱\n- 导出视图选择复杂化（需要判断显示哪些实体类型）\n- 与现有schema文档的\"实体概览表\"冲突（需要重新编写schema文档）\n\n---\n\n### 方案B：引入蓝图类型区分（路由层改造）\n\n**改造思路**：\n在SKILL.md中引入显式的蓝图类型参数：\n```bash\npython scripts/business_blueprint/cli.py --plan blueprint.json --type architecture\npython scripts/business_blueprint/cli.py --plan blueprint.json --type domain-knowledge\n```\n\n两种类型使用不同的schema和hints：\n- `--type architecture`：使用现有实体体系（capabilities/actors/flowSteps/systems）\n- `--type domain-knowledge`：使用新的实体体系（painPoints/strategies/rules/metrics/practices/pitfalls）\n\n**优点**：\n- 职责清晰，互不干扰\n- 每种类型有独立的hints模板和导出视图\n- schema文档可以分别编写\n\n**缺点**：\n- 需要用户显式指定类型（增加使用门槛）\n- 需要双倍维护成本（两套schema、两套模板、两套导出逻辑）\n- 不符合skill的\"渐进式披露\"设计原则（AI应该自动判断意图）\n\n---\n\n### 方案C：轻量级schema扩展（推荐方案）\n\n**改造思路**：\n保持核心schema不变，新增可选的`knowledge`块：\n\n```json\n{\n \"version\": \"1.0\",\n \"meta\": {\n \"title\": \"...\",\n \"industry\": \"retail\",\n \"blueprintType\": \"architecture\", // 新增字段：默认\"architecture\"，可选\"domain-knowledge\"或\"hybrid\"\n \"revisionId\": \"...\",\n \"lastModifiedAt\": \"...\",\n \"lastModifiedBy\": \"ai\"\n },\n \"context\": {...},\n \"library\": {\n // 保留现有实体（架构类）\n \"capabilities\": [],\n \"actors\": [],\n \"flowSteps\": [],\n \"systems\": [],\n // 新增可选块（know-how类）\n \"knowledge\": {\n \"painPoints\": [],\n \"strategies\": [],\n \"rules\": [],\n \"metrics\": [],\n \"practices\": [],\n \"pitfalls\": []\n }\n },\n \"relations\": [],\n \"views\": [],\n \"editor\": {...},\n \"artifacts\": {}\n}\n```\n\n**AI意图判断逻辑**（写在SKILL.md）：\n```\n用户需求关键词匹配：\n- \"架构图\"、\"系统设计\"、\"IT规划\" → blueprintType = \"architecture\"，只填充library核心实体\n- \"know-how\"、\"领域知识\"、\"业务洞察\"、\"最佳实践\"、\"行业玩法\" → blueprintType = \"domain-knowledge\"，只填充knowledge块\n- 混合需求（同时提到架构和策略） → blueprintType = \"hybrid\"，同时填充两类实体\n```\n\n**导出视图路由逻辑**（在export_routes.py中）：\n```python\nif blueprintType == \"architecture\":\n 使用现有视图模板（poster/swimlane/freeflow）\nelif blueprintType == \"domain-knowledge\":\n 使用新的knowledge视图模板（knowledge-graph/knowledge-cards）\nelif blueprintType == \"hybrid\":\n 分页渲染（第一页架构图，第二页知识图谱）\n```\n\n**优点**：\n- 不破坏现有架构蓝图能力（向后兼容）\n- AI自动判断意图，无需用户显式参数（符合渐进式披露）\n- 同一个JSON schema，不同视图模板（维护成本低）\n- 可以支持混合蓝图（架构+know-how并存）\n\n**缺点**：\n- 需要新增knowledge块的schema文档\n- 需要开发新的导出视图模板\n\n---\n\n## 推荐方案C的详细设计\n\n### 一、schema扩展设计\n\n#### 1. meta字段扩展\n\n```json\n{\n \"meta\": {\n \"blueprintType\": \"architecture\" // 新增，枚举值：architecture | domain-knowledge | hybrid\n }\n}\n```\n\n#### 2. library.knowledge实体定义\n\n新增`knowledge`块，包含6类know-how实体：\n\n| 实体类型 | 定义 | 示例数量 | 必填字段 |\n|---------|------|---------|---------|\n| **painPoints** | 痛点挑战 | 3-8 | id, name, description, severity |\n| **strategies** | 关键策略 | 3-10 | id, name, description, applicableCapabilityIds |\n| **rules** | 平台/政策规则 | 3-8 | id, name, description, riskLevel |\n| **metrics** | 数据指标/基准 | 3-10 | id, name, value, unit, benchmarkContext |\n| **practices** | 最佳实践 | 3-10 | id, name, description |\n| **pitfalls** | 常见误区 | 3-8 | id, name, description, impact |\n\n#### 3. knowledge实体字段详细定义\n\n**painPoints（痛点）**\n```json\n{\n \"id\": \"pain-001\",\n \"name\": \"ROI不稳\",\n \"description\": \"广告投放ROI波动大，缺乏稳定增长路径\",\n \"severity\": \"high\", // 枚举：low | medium | high | critical\n \"relatedCapabilityIds\": [\"cap-004\", \"cap-005\"] // 可选，关联到能力\n}\n```\n\n**strategies（策略）**\n```json\n{\n \"id\": \"str-001\",\n \"name\": \"测款节奏策略\",\n \"description\": \"3天测款周期，预算分配70%测款+30%放量\",\n \"applicableCapabilityIds\": [\"cap-004\"], // 可选，应用到哪些能力\n \"prerequisites\": [\"数据分析能力\"] // 可选，前置条件\n}\n```\n\n**rules（规则）**\n```json\n{\n \"id\": \"rule-001\",\n \"name\": \"Facebook广告政策红线\",\n \"description\": \"禁止误导性宣传、过度夸大效果、虚假折扣\",\n \"riskLevel\": \"critical\", // 枚举：low | medium | high | critical\n \"platform\": \"Facebook Ads\", // 可选，适用平台\n \"penalty\": \"账户封禁\" // 可选，违规后果\n}\n```\n\n**metrics（指标）**\n```json\n{\n \"id\": \"met-001\",\n \"name\": \"ROAS基准\",\n \"value\": \">3.0\",\n \"unit\": \"ratio\",\n \"benchmarkContext\": \"欧美市场，电商类目\",\n \"calculationMethod\": \"GMV / Ad Spend\" // 可选，计算公式\n}\n```\n\n**practices（最佳实践）**\n```json\n{\n \"id\": \"bp-001\",\n \"name\": \"素材迭代周期\",\n \"description\": \"每7天测试新素材版本，CTR下降10%时立即更换\",\n \"frequency\": \"weekly\", // 可选，执行频率\n \"successMetric\": \"CTR提升15%\" // 可选，成功指标\n}\n```\n\n**pitfalls（误区）**\n```json\n{\n \"id\": \"pit-001\",\n \"name\": \"过度依赖单一平台\",\n \"description\": \"只投放Facebook，平台封号后业务瘫痪\",\n \"impact\": \"critical\", // 枚举：low | medium | high | critical\n \"avoidanceStrategy\": \"多平台分散投放，预算占比不超过60%\" // 可选，规避建议\n}\n```\n\n---\n\n### 二、hints模板扩展\n\n#### 1. 行业hints增加know-how checklist\n\n修改`templates/{industry}/seed.json`：\n\n```json\n{\n \"industryHints\": {\n \"title\": \"零售行业蓝图关注点\",\n \"checklist\": [...], // 现有的架构类hints\n \"knowledgeHints\": { // 新增块\n \"title\": \"零售行业know-how关注点\",\n \"checklist\": [\n \"痛点：库存积压、客流下滑、会员流失、POS效率低\",\n \"策略：会员分层运营、智能补货、导购赋能、全渠道融合\",\n \"规则：食品安全合规、价格欺诈风险、数据隐私法规\",\n \"指标：坪效基准、客单价目标、会员复购率、员工人效\",\n \"最佳实践：陈列迭代周期、促销节奏、会员召回时机\",\n \"误区：过度依赖促销、忽视会员运营、数据孤岛\"\n ]\n }\n }\n}\n```\n\n#### 2. 为跨境电商新建industry模板\n\n新建`templates/cross-border-ecommerce/seed.json`：\n\n```json\n{\n \"industryHints\": {\n \"title\": \"跨境电商广告投放know-how关注点\",\n \"checklist\": [], // 空列表，架构类hints可选\n \"knowledgeHints\": {\n \"title\": \"跨境电商广告投放know-how\",\n \"checklist\": [\n \"痛点：ROI不稳、素材疲劳、平台封号、库存积压、汇率风险\",\n \"策略：测款节奏、出价策略、受众分层、再营销触发时机、预算动态分配\",\n \"规则：Facebook政策红线、Google Quality Score、TikTok审核要点、Amazon合规要求\",\n \"指标：ROAS基准(>3.0)、CPA阈值、CTR基准(>1.5%)、LTV测算\",\n \"最佳实践：素材迭代周期(7天)、测款预算分配(70%测款)、再营销触发时机(浏览>3次)\",\n \"误区：过度依赖单一平台、忽视合规风险、数据孤岛、盲目放量、忽视LTV\"\n ]\n }\n }\n}\n```\n\n---\n\n### 三、导出视图设计\n\n#### 1. 新增knowledge视图模板\n\n新建`references/knowledge-view-templates/`目录：\n\n**knowledge-graph.md**：知识图谱视图\n- 布局：中心发散式，painPoints为核心节点\n- 连线：painPoints → strategies → practices → metrics\n- 视觉：按severity/riskLevel分级颜色（critical=红，high=橙，medium=黄，low=绿）\n- 交互：点击节点展开详细描述卡片\n\n**knowledge-cards.md**：卡片式视图\n- 布局：分6列（痛点/策略/规则/指标/实践/误区）\n- 每列内按severity排序\n- 每个卡片显示name + description + 关联信息\n- 支持导出为PPT单页\n\n#### 2. export_routes.py路由逻辑\n\n```python\ndef select_export_route(blueprint):\n blueprint_type = blueprint.get(\"meta\", {}).get(\"blueprintType\", \"architecture\")\n\n if blueprint_type == \"architecture\":\n # 现有路由逻辑\n return select_architecture_route(blueprint)\n elif blueprint_type == \"domain-knowledge\":\n # 新路由：knowledge优先\n return \"knowledge-graph\" # 或 \"knowledge-cards\"\n elif blueprint_type == \"hybrid\":\n # 混合路由：双视图\n return \"hybrid-view\"\n else:\n # fallback\n return \"freeflow\"\n```\n\n---\n\n### 四、SKILL.md改造\n\n#### 1. AI意图判断指南\n\n在SKILL.md的\"How to Generate a Blueprint\"章节前插入：\n\n```markdown\n## Blueprint Type Detection\n\nAI must detect user intent before entity extraction:\n\n| Intent keywords | Blueprint type | Entity focus |\n|----------------|---------------|-------------|\n| \"架构图\"、\"系统设计\"、\"IT规划\"、\"技术蓝图\" | `architecture` | capabilities, actors, flowSteps, systems |\n| \"know-how\"、\"领域知识\"、\"业务洞察\"、\"最佳实践\"、\"行业玩法\"、\"痛点\"、\"策略\" | `domain-knowledge` | knowledge块（painPoints/strategies/rules/metrics/practices/pitfalls） |\n| 混合需求（同时提到架构和策略） | `hybrid` | 两类实体同时提取 |\n\nDefault behavior:\n- If unclear, default to `architecture` (backward compatibility)\n- If industryHints contains `knowledgeHints`, hint AI to also extract knowledge entities\n```\n\n#### 2. Step 2改造\n\n```markdown\n### Step 2: Extract entities from source text\n\n**If blueprintType = \"architecture\"**:\nUsing the user's source material AND the industry hints checklist, extract:\n- capabilities, actors, flowSteps, systems\n - See `references/entities-schema.md` for definitions\n\n**If blueprintType = \"domain-knowledge\"**:\nUsing the user's source material AND the knowledge hints checklist, extract:\n- painPoints, strategies, rules, metrics, practices, pitfalls\n - See `references/knowledge-schema.md` for definitions\n\n**If blueprintType = \"hybrid\"**:\nExtract both architecture and knowledge entities\n```\n\n---\n\n### 五、实施步骤\n\n#### Phase 1：Schema扩展（向后兼容）\n\n1. 修改`scripts/business_blueprint/templates/common/seed.json`，新增`meta.blueprintType`字段（默认值\"architecture\"）\n2. 新建`references/knowledge-schema.md`，定义knowledge块6类实体\n3. 修改`references/entities-schema.md`，在\"实体概览表\"中新增knowledge块说明\n4. 修改JSON schema validator，允许`library.knowledge`可选块\n\n#### Phase 2：Hints模板扩展\n\n1. 修改所有industry seed.json（common/finance/manufacturing/retail），新增`industryHints.knowledgeHints`块\n2. 新建`templates/cross-border-ecommerce/seed.json`（跨境电商专属模板）\n3. 新建`templates/ad-tech/seed.json`（广告技术专属模板）\n\n#### Phase 3：导出视图开发\n\n1. 新建`references/knowledge-view-templates/knowledge-graph.md`（知识图谱模板设计文档）\n2. 新建`references/knowledge-view-templates/knowledge-cards.md`（卡片式模板设计文档）\n3. 修改`business_blueprint/export_routes.py`，增加knowledge路由判断\n4. 开发knowledge视图渲染器（HTML/SVG输出）\n\n#### Phase 4：SKILL.md改造\n\n1. 在SKILL.md开头新增\"Blueprint Type Detection\"章节\n2. 修改\"Step 2: Extract entities\"章节，增加分支逻辑\n3. 新增\"Export Formats\"章节的knowledge视图说明\n4. 新增\"Industry Selection\"表的跨境电商、广告技术行业\n\n---\n\n## 改造清单\n\n### 必须改造的文件\n\n| 文件 | 改动内容 | 优先级 |\n|------|---------|--------|\n| `scripts/business_blueprint/templates/common/seed.json` | 新增meta.blueprintType字段 | P0 |\n| `references/entities-schema.md` | 新增knowledge块说明 | P0 |\n| 新建 `references/knowledge-schema.md` | 定义knowledge实体字段 | P0 |\n| `SKILL.md` | 新增Blueprint Type Detection章节 | P0 |\n| `scripts/business_blueprint/templates/retail/seed.json` | 新增knowledgeHints块 | P1 |\n| `scripts/business_blueprint/templates/finance/seed.json` | 新增knowledgeHints块 | P1 |\n| `scripts/business_blueprint/templates/manufacturing/seed.json` | 新增knowledgeHints块 | P1 |\n| 新建 `templates/cross-border-ecommerce/seed.json` | 跨境电商专属模板 | P1 |\n| 新建 `references/knowledge-view-templates/knowledge-graph.md` | 知识图谱视图设计 | P2 |\n| 新建 `references/knowledge-view-templates/knowledge-cards.md` | 卡片式视图设计 | P2 |\n| `scripts/business_blueprint/export_routes.py` | 新增knowledge路由逻辑 | P2 |\n\n### 可选改造（后续迭代）\n\n- 新建 `templates/ad-tech/seed.json`（广告技术行业模板）\n- 新建 `templates/logistics/seed.json`（物流行业模板）\n- 开发混合视图渲染器（architecture + knowledge并存）\n- 开发知识图谱交互式编辑器（点击节点展开详情）\n\n---\n\n## 验证测试用例\n\n### 测试1：向后兼容性\n\n输入：\n```\n生成企业管理系统的架构蓝图\n```\n\n预期：\n- blueprintType = \"architecture\"\n- 只填充library核心实体（capabilities/actors/flowSteps/systems）\n- 导出视图为现有模板（poster/swimlane/freeflow）\n- JSON schema验证通过\n\n### 测试2：纯knowledge蓝图\n\n输入：\n```\n生成跨境电商广告投放的领域know-how大图，包含痛点、策略、平台规则、数据指标\n```\n\n预期：\n- blueprintType = \"domain-knowledge\"\n- 只填充library.knowledge块（painPoints/strategies/rules/metrics/practices/pitfalls）\n- 导出视图为knowledge-graph或knowledge-cards\n- industry自动选择\"cross-border-ecommerce\"\n\n### 测试3：混合蓝图\n\n输入：\n```\n生成跨境电商广告投放方案，既要系统架构，又要业务策略know-how\n```\n\n预期：\n- blueprintType = \"hybrid\"\n- 同时填充architecture实体和knowledge实体\n- 导出视图为双页（第一页架构图，第二页知识图谱）\n- 或者单页分区域显示\n\n---\n\n## 风险评估\n\n### 低风险\n\n- schema向后兼容（默认blueprintType=\"architecture\"，现有调用不受影响）\n- hints模板扩展不影响现有行业模板\n- AI意图判断写在SKILL.md，不修改Python代码逻辑\n\n### 中风险\n\n- 导出视图路由逻辑需要修改export_routes.py（需要测试回归）\n- knowledge实体字段定义可能与capabilities产生混淆（需要在schema文档中明确区分）\n\n### 高风险\n\n- 无（方案C避免了双schema的维护成本，也没有破坏性改动）\n\n---\n\n## 时间估算\n\n- Phase 1（Schema扩展）：2-3小时\n- Phase 2（Hints模板）：3-4小时\n- Phase 3（导出视图）：8-10小时（需要开发新渲染器）\n- Phase 4（SKILL.md改造）：1-2小时\n\n总计：14-19小时（约2-3个工作日）\n\n---\n\n## 后续迭代建议\n\n1. **知识图谱编辑器**：让用户可以在HTML viewer中点击节点，展开详情卡片，添加新的know-how节点\n2. **行业know-how库**：沉淀各行业的know-how模板库（例如跨境电商的常见痛点、策略清单）\n3. **know-how版本管理**：支持know-how的演化记录（例如Facebook政策规则的历史变更）\n4. **know-how与架构联动**：在架构图中标注对应know-how（例如某个系统旁边显示\"规避XX风险的最佳实践\"）\n\nFile v0.14.1:references/domain-knowledge-design-adversarial-review.md\n\n# 对抗性评审报告：Domain-Knowledge实体扩展设计\n\n**评审日期**: 2026-04-28\n**评审者**: Claude Code（对抗性视角）\n**目标**: 系统性识别设计缺陷、矛盾、遗漏、风险，确保设计质量\n\n---\n\n## 一、核心假设脆弱性分析\n\n### 问题1：AI自动判断意图的可靠性假设\n\n**设计假设**：\n```\n用户需求包含\"know-how\"、\"领域知识\"、\"策略\"、\"痛点\" → blueprintType = \"domain-knowledge\"\n```\n\n**对抗性质疑**：\n- 用户输入模糊时，AI判断会出错吗？\n- 例如：用户说\"优化ROI策略\" → \"策略\"关键词触发domain-knowledge，但用户实际想看的是系统架构（优化ROI的系统设计）\n- 关键词匹配过于简单，缺乏上下文理解\n\n**发现缺陷**：\n- ❌ AI判断逻辑过于简单（关键词匹配），未考虑用户意图的语义理解\n- ❌ 未定义fallback机制：AI判断错误时，用户如何纠正blueprintType？\n\n**建议改进**：\n- 新增判断优先级：用户明确指定蓝图类型 > 关键词频率分析 > 默认值\n- 允许用户在JSON meta中手动设置blueprintType覆盖AI判断\n\n---\n\n### 问题2：\"强核心+弱扩展\"的可行性假设\n\n**设计假设**：\n```\nvalidator只校验核心字段（id/name/entityType），扩展字段直接放行\n```\n\n**对抗性质疑**：\n- 扩展字段真的能完全放行吗？\n- 用户可能在扩展字段中写入错误数据类型（如`severity: 123`而非字符串）\n- freeflow渲染器可能崩溃于复杂嵌套结构（如`{\"nested\": {\"deep\": {\"recursive\": \"object\"}}}`）\n\n**发现缺陷**：\n- ❌ validator完全放行扩展字段，可能导致下游工具（viewer/export）崩溃\n- ❌ 未定义扩展字段的数据类型约束：severity应该是枚举字符串，而非任意值\n- ❌ freeflow渲染器缺乏容错设计：复杂结构降级显示策略未定义\n\n**建议改进**：\n- 定义常见扩展字段的soft schema（如severity: string枚举，level: integer）\n- validator校验扩展字段时采用soft模式（警告而非报错）\n- freeflow渲染器增加容错：嵌套层级>3时降级为文本卡片\n\n---\n\n### 问题3：freeflow自适应渲染的技术可行性假设\n\n**设计假设**：\n```\nfreeflow足够灵活，只需定义视觉样式，无需开发独立knowledge-graph视图模板\n```\n\n**对抗性质疑**：\n- freeflow当前渲染逻辑基于system分层架构，knowledge实体没有layer/category字段\n- freeflow如何布局大量knowledge实体（例如50个痛点、30个策略）？\n- relations关系连线复杂时（多个solves、prevents交叉），freeflow能否正确渲染？\n\n**发现缺陷**：\n- ❌ freeflow布局算法未适配knowledge实体（无layer/category，无法自动分层）\n- ❌ 未定义knowledge实体的布局策略（中心发散？网格布局？自由布局？）\n- ❌ 大量实体场景下的性能问题未评估（100+实体时freeflow渲染速度）\n\n**建议改进**：\n- 定义knowledge布局策略：painPoints为中心，strategies围绕，其他实体外围\n- 新增布局算法：entityType-based clustering（按实体类型聚类）\n- 定义性能上限：超过50实体时分页渲染或简化连线\n\n---\n\n## 二、边界条件未覆盖\n\n### 问题4：混合蓝图的处理逻辑缺失\n\n**设计假设**：\n```\n两种类型互斥，不设计hybrid（避免复杂度）\n```\n\n**对抗性质疑**：\n- 用户实际需求可能真的需要混合蓝图（既要系统架构，又要know-how策略）\n- AI判断\"优先domain-knowledge\"的规则，会导致architecture实体被遗漏\n- relations跨类型关联（strategy → capability）在纯domain-knowledge蓝图中失效（capability不存在）\n\n**发现缺陷**：\n- ❌ 混合需求强制选择单一蓝图类型，丢失部分用户需求\n- ❌ 跨类型关联的实用性假设：如果blueprintType=domain-knowledge，用户不能添加capability实体，跨类型关联无法建立\n- ❌ 未定义混合蓝图的处理策略（是否允许？如何存储？）\n\n**建议改进**：\n- 允许hybrid蓝图类型（blueprintType=\"hybrid\"），同时填充architecture和knowledge实体\n- 定义hybrid蓝图的处理规则：relations必须明确区分跨类型关系和同类型关系\n- 或者：允许domain-knowledge蓝图中可选添加architecture实体（非强制）\n\n---\n\n### 问题5：用户自定义实体的边界模糊\n\n**设计假设**：\n```\n允许用户自定义实体类型数组（validator不校验数组名称）\n```\n\n**对抗性质疑**：\n- 用户自定义实体与预定义实体的命名冲突如何处理？（如用户自定义\"strategies\"数组）\n- 用户自定义实体类型命名不规范时，freeflow如何渲染？（如`\"MyCustomEntity\"`而非`\"myCustomEntity\"`）\n- 用户自定义实体如何建立关系？（entityType不在relations定义中）\n\n**发现缺陷**：\n- ❌ 未定义命名冲突处理策略：用户自定义数组名称与预定义实体类型冲突时，validator行为未明确\n- ❌ 用户自定义entityType的命名规范未定义（推荐camelCase？允许任意字符串？）\n- ❌ 用户自定义实体的relations关系类型未定义（如何建立custom → custom的关系？）\n\n**建议改进**：\n- 定义命名冲突策略：用户自定义数组名称优先级高于预定义（允许覆盖）\n- 定义entityType命名规范：推荐camelCase，validator校验格式（至少3字符，无特殊符号）\n- 新增通用关系类型：`relates`（任意实体之间的弱关联）\n\n---\n\n### 问题6：relations关系完整性约束缺失\n\n**设计假设**：\n```\nrelations数组表达实体关联，新增solves/prevents/measures等关系类型\n```\n\n**对抗性质疑**：\n- relations中的from/to ID不存在时，validator如何处理？\n- 循环依赖如何避免？（strategy → practice → strategy）\n- 用户可能建立不合理关系（如metric → pitfall，无语义意义）\n\n**发现缺陷**：\n- ❌ relations ID引用完整性未校验：from/to ID不存在时，validator不报错\n- ❌ 循环依赖检测缺失：AI或用户可能建立A→B→C→A的循环关系\n- ❌ 关系语义合理性未校验：measures只能metric→strategy，但用户可能写metric→pitfall\n\n**建议改进**：\n- validator校验relations ID引用完整性（from/to ID必须在library中存在）\n- validator检测循环依赖（A→B→C→A时报错）\n- 定义关系语义约束表（measures只能metric→strategy等），validator校验\n\n---\n\n## 三、内部矛盾和冲突\n\n### 问题7：决策3与决策1的矛盾\n\n**决策3**：\n```\nknowledge实体可单向关联architecture实体（单向关联）\n```\n\n**决策1**：\n```\nblueprintType互斥：architecture | domain-knowledge（无hybrid）\n```\n\n**矛盾点**：\n- 如果blueprintType=domain-knowledge，library中不存在architecture实体（capabilities等）\n- 此时跨类型关联（strategy → capability）无法建立（capability不存在）\n- 决策3的单向关联假设失效\n\n**发现矛盾**：\n- ❌ 决策3假设knowledge实体可以关联architecture实体，但决策1禁止混合蓝图\n- ❌ \"不强加architecture关联\"的补充说明，在纯domain-knowledge蓝图中等价于\"无法关联\"\n\n**建议改进**：\n- 修改决策1：允\n\nArchive v0.14.0: 112 files, 330606 bytes\n\nFiles: demos/common.blueprint.json (23013b), demos/finance.blueprint.json (6005b), demos/manufacturing.blueprint.json (6161b), demos/retail.blueprint.json (5058b), demos/screenshots/retail-arch.svg (9274b), evals/defect-taxonomy.json (313b), evals/export-integrity-thresholds.json (145b), evals/export-scoring-schema.json (352b), evals/fixtures/route-architecture.json (359b), evals/fixtures/route-evolution.json (381b), evals/fixtures/route-freeflow.json (234b), evals/README.md (1064b), plans/2026-04-28-domain-knowledge-entities-extension.md (55183b), plans/2026-04-28-domain-knowledge-v2.md (56286b), README.md (18735b), README.zh-CN.md (16512b), REFACTOR_SUMMARY.md (6409b), references/architecture-design-system.md (6986b), references/architecture-diagram-design.md (11111b), references/architecture-templates/microservices.md (2441b), references/architecture-templates/serverless.md (2305b), references/authoring-rules.md (256b), references/blueprint-schema.md (231b), references/domain-knowledge-design-v2.md (22113b), references/domain-knowledge-entities-extension-design.md (47457b), references/domain-knowledge-test-eval-design.md (29292b), references/entities-schema.md (5653b), references/implementation-plan.md (12463b), references/industry-packs.md (254b), references/knowledge-entities-schema.md (4017b), references/knowledge-self-check.md (2603b), references/layout-quality-check.md (2428b), references/prompt-orchestration-templates.md (8925b), references/systems-schema.md (3162b), references/theme-dark.md (4505b), references/visual-enhancement-plan.md (9770b), scripts/business_blueprint/assets/viewer.html (28441b), scripts/business_blueprint/clarify.py (9747b), scripts/business_blueprint/cli.py (9373b), scripts/business_blueprint/diff_patcher.py (7370b), scripts/business_blueprint/export_drawio.py (644b), scripts/business_blueprint/export_excalidraw.py (710b), scripts/business_blueprint/export_html.py (11555b), scripts/business_blueprint/export_integrity.py (5225b), scripts/business_blueprint/export_knowledge.py (32098b), scripts/business_blueprint/export_mermaid.py (4153b), scripts/business_blueprint/export_routes.py (5332b), scripts/business_blueprint/export_svg.py (150450b), scripts/business_blueprint/export_text.py (2189b), scripts/business_blueprint/export_theme.py (4876b), scripts/business_blueprint/fixtures/baseline/common.svg (24513b), scripts/business_blueprint/fixtures/baseline/finance.svg (10434b), scripts/business_blueprint/fixtures/baseline/manufacturing.svg (10923b), scripts/business_blueprint/fixtures/baseline/retail.svg (9274b), scripts/business_blueprint/generate.py (4026b), scripts/business_blueprint/intent_resolver.py (6870b), scripts/business_blueprint/knowledge_self_check.py (6867b), scripts/business_blueprint/knowledge_validate.py (12699b), scripts/business_blueprint/migrations/v1_to_v2.py (4703b), scripts/business_blueprint/model.py (2131b), scripts/business_blueprint/normalize.py (2651b), scripts/business_blueprint/projection.py (6258b), scripts/business_blueprint/prompt_generator.py (3097b), scripts/business_blueprint/refine.py (6160b), scripts/business_blueprint/renderers.py (18799b), scripts/business_blueprint/rule_engine.py (10638b), scripts/business_blueprint/strategy_registry/overlays/finance-regulatory.json (732b), scripts/business_blueprint/strategy_registry/overlays/manufacturing-supply-chain.json (956b), scripts/business_blueprint/strategy_registry/perspectives/product-capability.json (2485b), scripts/business_blueprint/strategy_registry/perspectives/technical-architecture.json (1207b), scripts/business_blueprint/strategy_registry/registry.json (1229b), scripts/business_blueprint/templates/common/base_blueprint.json (440b), scripts/business_blueprint/templates/common/seed.json (1890b), scripts/business_blueprint/templates/cross-border-ecommerce/seed.json (1984b), scripts/business_blueprint/templates/finance/seed.json (2297b), scripts/business_blueprint/templates/html-viewer.html (9554b), scripts/business_blueprint/templates/manufacturing/seed.json (2225b), scripts/business_blueprint/templates/retail/seed.json (2223b), scripts/business_blueprint/tests/metrics.py (6679b), scripts/business_blueprint/tests/phase0_migration_test.py (6549b)\n\nArchive v0.12.0: 78 files, 197279 bytes\n\nFiles: business_blueprint/__init__.py (49b), business_blueprint/assets/viewer.html (28441b), business_blueprint/clarify.py (1820b), business_blueprint/cli.py (7781b), business_blueprint/export_drawio.py (641b), business_blueprint/export_excalidraw.py (707b), business_blueprint/export_html.py (8159b), business_blueprint/export_integrity.py (5225b), business_blueprint/export_mermaid.py (4153b), business_blueprint/export_routes.py (4375b), business_blueprint/export_svg.py (141531b), business_blueprint/export_text.py (2189b), business_blueprint/export_theme.py (4876b), business_blueprint/generate.py (3233b), business_blueprint/model.py (1590b), business_blueprint/normalize.py (2651b), business_blueprint/projection.py (6259b), business_blueprint/prompt_generator.py (3097b), business_blueprint/specs/__init__.py (18799b), business_blueprint/templates/common/base_blueprint.json (440b), business_blueprint/templates/common/seed.json (440b), business_blueprint/templates/finance/seed.json (1233b), business_blueprint/templates/html-viewer.html (9554b), business_blueprint/templates/manufacturing/seed.json (1244b), business_blueprint/templates/retail/seed.json (1278b), business_blueprint/validate.py (7093b), business_blueprint/viewer.py (2072b), demos/common.blueprint.json (23013b), demos/finance.blueprint.json (6005b), demos/manufacturing.blueprint.json (6161b), demos/retail.blueprint.json (5058b), demos/screenshots/retail-arch.svg (9274b), evals/defect-taxonomy.json (313b), evals/export-integrity-thresholds.json (145b), evals/export-scoring-schema.json (352b), evals/fixtures/route-architecture.json (359b), evals/fixtures/route-evolution.json (381b), evals/fixtures/route-freeflow.json (234b), evals/README.md (1064b), plans/2026-04-20-blueprint-cross-skill-handoff.md (12038b), plans/2026-04-20-blueprint-cross-skill-implementation.md (23473b), plans/2026-04-21-business-blueprint-quality-hardening-implementation.md (16718b), plans/2026-04-21-business-blueprint-quality-hardening.md (15267b), plans/2026-04-23-svg-animation-enhancement.md (7331b), pyproject.toml (510b), README.md (15372b), README.zh-CN.md (13370b), references/architecture-design-system.md (6986b), references/architecture-diagram-design.md (11111b), references/architecture-templates/microservices.md (2441b), references/architecture-templates/serverless.md (2305b), references/authoring-rules.md (256b), references/blueprint-schema.md (231b), references/implementation-plan.md (12463b), references/industry-packs.md (254b), references/layout-quality-check.md (2428b), references/prompt-orchestration-templates.md (8925b), references/theme-dark.md (4505b), references/visual-enhancement-plan.md (9770b), SKILL.md (12874b), tests/conftest.py (181b), tests/test_architecture_skill_contract.py (3601b), tests/test_cli_cross_platform.py (2897b), tests/test_cli_smoke.py (5825b), tests/test_e2e.py (5918b), tests/test_export_integrity.py (5261b), tests/test_export_routes.py (1935b), tests/test_exporters.py (16750b), tests/test_generate.py (3951b), tests/test_normalize.py (1434b), tests/test_projection.py (3788b), tests/test_prompt_generation.py (3472b), tests/test_svg_quality.py (17255b), tests/test_theme_and_cards.py (13423b), tests/test_validate.py (5659b), tests/test_viewer.py (4401b), tests/test_visual_enhancement.py (25882b), _meta.json (142b)\n\nArchive v0.10.0: 75 files, 186262 bytes\n\nFiles: business_blueprint/__init__.py (49b), business_blueprint/assets/viewer.html (28441b), business_blueprint/clarify.py (1820b), business_blueprint/cli.py (7473b), business_blueprint/export_drawio.py (641b), business_blueprint/export_excalidraw.py (707b), business_blueprint/export_html.py (8159b), business_blueprint/export_integrity.py (5225b), business_blueprint/export_mermaid.py (4153b), business_blueprint/export_routes.py (4375b), business_blueprint/export_svg.py (134052b), business_blueprint/export_text.py (2189b), business_blueprint/export_theme.py (4876b), business_blueprint/generate.py (3233b), business_blueprint/model.py (1590b), business_blueprint/normalize.py (2651b), business_blueprint/projection.py (6259b), business_blueprint/specs/__init__.py (18799b), business_blueprint/templates/common/base_blueprint.json (440b), business_blueprint/templates/common/seed.json (440b), business_blueprint/templates/finance/seed.json (1233b), business_blueprint/templates/html-viewer.html (4052b), business_blueprint/templates/manufacturing/seed.json (1244b), business_blueprint/templates/retail/seed.json (1278b), business_blueprint/validate.py (7093b), business_blueprint/viewer.py (2072b), demos/common.blueprint.json (23013b), demos/finance.blueprint.json (6005b), demo...","readmeExcerpt":"Skill: Business Blueprint Skill Owner: kaisersong Summary: Use when turning presales requirements, meeting notes, or solution materials into editable business capability blueprints, swimlane flows, and application ar... Tags: latest:0.15.0 Version history: v0.15.0 | 2026-04-30T14:17:32.981Z | user Domain-knowledge blueprints now produce product-grade strategy names (统一归因模型 vs 测款节奏). Adds namingHints to cross-border-e","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"python scripts/business_blueprint/cli.py --plan projects/workspace/solution.blueprint.json --from \"...\"\npython scripts/business_blueprint/cli.py --project projects/workspace/solution.blueprint.json\npython scripts/business_blueprint/cli.py --export projects/workspace/solution.blueprint.json"},{"language":"json","snippet":"{\n \"version\": \"1.0\",\n \"meta\": {\n \"title\": \"...\",\n \"industry\": \"retail\",\n \"revisionId\": \"rev-YYYYMMDD-NN\",\n \"parentRevisionId\": null,\n \"lastModifiedAt\": \"ISO8601\",\n \"lastModifiedBy\": \"ai\"\n },\n \"context\": {\n \"goals\": [],\n \"scope\": [],\n \"assumptions\": [],\n \"constraints\": [],\n \"sourceRefs\": [{\"type\": \"inline-text\", \"excerpt\": \"...\"}],\n \"clarifyRequests\": [],\n \"clarifications\": []\n },\n \"library\": {\n \"capabilities\": [\n {\"id\": \"cap-xxx\", \"name\": \"...\", \"level\": 1, \"description\": \"...\", \"ownerActorIds\": [], \"supportingSystemIds\": []}\n ],\n \"actors\": [\n {\"id\": \"actor-xxx\", \"name\": \"...\"}\n ],\n \"flowSteps\": [\n {\"id\": \"flow-xxx\", \"name\": \"...\", \"actorId\": \"actor-xxx\", \"capabilityIds\": [\"cap-xxx\"], \"systemIds\": [], \"stepType\": \"task\", \"inputRefs\": [], \"outputRefs\": []}\n ],\n \"systems\": [\n {\"id\": \"sys-xxx\", \"kind\": \"system\", \"name\": \"...\", \"aliases\": [], \"description\": \"...\", \"resolution\": {\"status\": \"canonical\", \"canonicalName\": \"...\"}, \"capabilityIds\": [\"cap-xxx\"]}\n ]\n },\n \"relations\": [\n {\"id\": \"rel-xxx\", \"type\": \"supports\", \"from\": \"sys-xxx\", \"to\": \"cap-xxx\", \"label\": \"支撑\"}\n ],\n \"views\": [],\n \"editor\": {\"fieldLocks\": {}, \"theme\": \"enterprise-default\"},\n \"artifacts\": {}\n}"},{"language":"bash","snippet":"python scripts/business_blueprint/cli.py --export "},{"language":"bash","snippet":"python scripts/business_blueprint/cli.py --project "},{"language":"text","snippet":"User provides raw requirements / meeting notes?\n → AI agent reads hints, extracts entities, writes blueprint JSON\n → Optionally run --project for downstream machine handoff\n → Then run --export for visualization\n\nUser needs diagram files (SVG, draw.io, etc.)?\n → --export (default: SVG + HTML viewer)\n\nUser unsure about blueprint quality?\n → --validate\n\nUser wants downstream report / slide generation?\n → --project"},{"language":"bash","snippet":"python scripts/business_blueprint/cli.py --plan ...\npython scripts/business_blueprint/cli.py --export ..."}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: kai-business-blueprint\ndescription: Use when turning presales requirements, meeting notes, or solution materials into editable business capability blueprints, swimlane flows, and application architecture diagrams. Use when generating blueprint JSON, static HTML viewers, or exporting to SVG, draw.io, Excalidraw, or Mermaid formats. When no standard export template applies, default to free-flow output.\n---\n\n# Business Blueprint Skill\n\nUse the Python scripts in this repository as the execution surface.\n\n## Output Directory\n\nAll generated files (blueprint JSON, viewers, exports) go into `projects/workspace/` — not the repository root.\n\n```bash\npython scripts/business_blueprint/cli.py --plan projects/workspace/solution.blueprint.json --from \"...\"\npython scripts/business_blueprint/cli.py --project projects/workspace/solution.blueprint.json\npython scripts/business_blueprint/cli.py --export projects/workspace/solution.blueprint.json\n```\n\n## Industry Selection\n\nChoose `--industry` from exactly one of: `\"common\"`, `\"finance\"`, `\"manufacturing\"`, `\"retail\"`. Select the closest match based on the user's domain and materials; do not invent other values.\n\n| Industry | Hints content |\n|----------|-------------|\n| `common` | No hints — generic domains |\n| `finance` | Risk control, credit, compliance, customer profile, etc. |\n| `manufacturing` | Production planning, quality, warehouse, supply chain, etc. |\n| `retail` | Store operations, membership, POS, order fulfillment, etc. |\n\n## How to Generate a Blueprint\n\nThe AI agent is responsible for entity extraction. The Python tool handles JSON writing, visualization, and export.\n\n### Step 1: Read industry hints\n\nRead the seed template at `business_blueprint/templates/{industry}/seed.json` and get the `industryHints.checklist`.\n\n### Step 2: Extract entities from source text\n\nUsing the user's source material AND the industry hints checklist, extract:\n- **capabilities**: business capability areas (name, description)\n- **actors**: roles/people involved (name)\n- **flowSteps**: business process steps (name, actorId, capabilityIds, stepType)\n- **systems**: IT systems that support capabilities\n - See `references/entities-schema.md` for all entity field definitions\n - See `references/systems-schema.md` for systems category/layer rules\n - See `scripts/business_blueprint/templates/common/seed.json` for field examples\n\n**Domain-knowledge mode** (when seed has `meta.blueprintType: \"domain-knowledge\"`,\ne.g. `cross-border-ecommerce`): entities go into `library.knowledge.*`\n(painPoints / strategies / rules / metrics / practices / pitfalls), not the\narchitecture buckets above. The seed's `industryHints.knowledgeHints.namingHints`\nsection, when present, dictates content granularity:\n- `strategy.name` must be a 4-10 字 product-grade noun phrase\n (e.g. \"统一归因模型\", \"AIGC 素材工厂\"), not an action (\"优化素材\") or a\n dimension (\"测款节奏\"). Reference the seed's `strategy_named_examples`.\n- `painPoint.audience` and `strategy.audience` are f"},{"path":"evals/README.md","content":"# Export Evals\n\nThis directory holds machine-readable export quality inputs, thresholds, and taxonomy data for `kai-business-blueprint`.\n\n## Files\n\n- `export-integrity-thresholds.json` — numeric thresholds for geometry-sensitive integrity checks\n- `defect-taxonomy.json` — canonical defect categories used by tests and eval fixtures\n- `export-scoring-schema.json` — minimal scoring/output schema for export eval runs\n\n## Fixtures\n\n- `fixtures/route-freeflow.json` — generic graph that should stay on `freeflow`\n- `fixtures/route-architecture.json` — categorized architecture graph that should resolve to `architecture-template`\n- `fixtures/route-evolution.json` — dated staged flow that should resolve to `evolution`\n\n## Usage\n\n- Route tests read these fixtures to keep export-family decisions stable.\n- Integrity tests should reference taxonomy ids instead of inventing one-off failure labels.\n- Human-readable failure maps, if needed later, should be generated from these files and test references rather than hand-maintained as the source of truth."},{"path":"README.md","content":"# kai-business-blueprint\n\n> 售前需求、会议纪要、RFP 材料 → 可编辑的业务能力蓝图、泳道流程图、应用架构图。一份 canonical JSON IR，多个下游导出格式（SVG / draw.io / Excalidraw / Mermaid）。\n\nA [Claude Code](https://claude.ai/claude-code) skill that turns raw presales inputs into canonical business capability blueprints, with a static HTML viewer and multi-format diagram exports.\n\nEnglish | [简体中文](README.zh-CN.md)\n\n---\n\n## Demo\n\nRetail industry blueprint, exported as SVG:\n\n![retail-blueprint](demos/screenshots/retail-arch.svg)\n\nThe SVG is generated by `business-blueprint --export demos/retail.blueprint.json` — the source JSON is in `demos/retail.blueprint.json`, the viewer is `demos/solution.viewer.html`.\n\n---\n\n## Design Philosophy: IR-First Pipeline\n\n### 1. JSON as Canonical Intermediate Representation\n\nEvery workflow converges on `solution.blueprint.json` — the single source of truth. All other artifacts (viewer, SVG, draw.io) are deterministic projections from it.\n\n```\nRaw Text ──(--plan)──→ JSON ──(--generate)──→ Viewer HTML\n │\n ├──(--export)──→ SVG / draw.io / Excalidraw / Mermaid\n │\n └──(--edit)────→ JSON (patch logged) + Viewer refresh\n```\n\nThe IR is:\n- **Version-controllable** — standard JSON, diffs are meaningful\n- **AI-readable** — downstream skills parse `entities`, `relations`, `flowSteps` without HTML parsing\n- **Human-editable** — light fields (labels, names) can be edited without breaking structure\n\n### 2. Progressive Disclosure\n\nThe skill file (`SKILL.md`) is a routing layer — it tells Claude *which* file to read for *which* command. Heavy assets (industry packs, viewer HTML template, export engine) stay on disk until needed.\n\n```\n--plan → only model + generation rules; no CSS, no export engine\n--generate → one viewer.html template + one industry pack\n--export → only the requested export engine; other formats stay on disk\n--validate → schema + rules; no rendering code\n```\n\n### 3. Silicon-Carbon Collaboration\n\n**Input:** Humans write natural language (requirements, meeting notes, RFPs). AI parses into structured entities (Application Systems, Business Capabilities, Process Flows, Actors) and relations.\n\n**Output:** The viewer is a static HTML page — no build step, no JS framework, works offline. Every node is editable in-place, and edits are logged as a JSON patch trail (`solution.patch.jsonl`) for full traceability.\n\n---\n\n## Install\n\n### Claude Code\n\n```bash\ngit clone https://github.com/kaisersong/kai-business-blueprint ~/.claude/skills/kai-business-blueprint\n```\n\nThen: `cd kai-business-blueprint && pip install -e .`\n\n### OpenClaw\n\n```bash\ngit clone https://github.com/kaisersong/kai-business-blueprint ~/.openclaw/skills/kai-business-blueprint\ncd kai-business-blueprint && pip install -e .\n```\n\n---\n\n## Usage\n\n### CLI Commands\n\n| Flag | Purpose |\n|------|---------|\n| `--plan \"text\"` | Parse raw text into canonical blueprint JSON |\n| `--project ` | Deriv"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7bjv9d2ccsjqk1m4edthgtgx82fem8\",\n \"slug\": \"kai-business-blueprint\",\n \"version\": \"0.15.0\",\n \"publishedAt\": 1777558652981\n}"},{"path":"references/architecture-design-system.md","content":"# Architecture Diagram Design System\n\n本文件定义 Agent 生成架构图时使用的完整设计系统。所有颜色、字体、间距、布局规则必须严格遵循。\n\n## 1. 主题\n\n### 暗黑模式（默认）\n\n| Token | 值 | 用途 |\n|-------|-----|------|\n| `bg` | `#020617` | 页面背景（Slate-950） |\n| `canvas` | `#0F172A` | 卡片表面（Slate-900） |\n| `text_main` | `#E2E8F0` | 主文字 |\n| `text_sub` | `#94A3B8` | 副文字 |\n| `border` | `#1E293B` | 边框 |\n| `grid` | `#1E293B` | 网格线（40px pattern） |\n\n暗黑模式是默认输出。除非用户明确要求亮色模式，否则不得切换到亮色主题。\n\n### 亮色模式\n\n| Token | 值 | 用途 |\n|-------|-----|------|\n| `bg` | `#F8FAFC` | 页面背景 |\n| `canvas` | `#FFFFFF` | 卡片表面 |\n| `text_main` | `#0F172A` | 主文字 |\n| `text_sub` | `#64748B` | 副文字 |\n| `border` | `#CBD5E1` | 边框 |\n\n## 2. 字体\n\n- 主字体：`'JetBrains Mono', 'Fira Code', monospace`（Google Fonts CDN 引入）\n- 回退字体：`system-ui, -apple-system, sans-serif`\n\n| 层级 | 字号 | 字重 | 用途 |\n|------|------|------|------|\n| 标题 | 20px | 700 | SVG 主标题 |\n| 副标题 | 13px | 400 | 副标题/注解 |\n| 组件名 | 14px | 600 | 节点名称 |\n| 副标签 | 11px | 400 | 节点描述 |\n| 注解 | 9-10px | 400 | 标签、Legend |\n| Region 标签 | 12px | 600 | Region 名称 |\n\n## 3. 语义色\n\n7 种系统类别，每种定义 fill + stroke（暗黑模式值）：\n\n| 类别 | 填充色 | 描边色 | 用途 |\n|------|--------|--------|------|\n| `frontend` | `rgba(8,51,68,0.4)` | `#22d3ee` | Web、移动端、UI |\n| `backend` | `rgba(6,78,59,0.4)` | `#34d399` | Lambda、API、服务 |\n| `database` | `rgba(76,29,149,0.4)` | `#a78bfa` | DynamoDB、RDS |\n| `cloud` | `rgba(120,53,15,0.3)` | `#fbbf24` | Region 框、CloudFront |\n| `security` | `rgba(136,19,55,0.4)` | `#fb7185` | Security Group、WAF |\n| `message_bus` | `rgba(251,146,60,0.3)` | `#fb923c` | SQS、SNS、EventBridge |\n| `external` | `rgba(30,41,59,0.5)` | `#94a3b8` | 第三方 API、SaaS |\n\n无类别时回退到：fill `#1E293B`，stroke `#94A3B8`。\n\n## 4. 布局规则\n\n### 4.1 L→R 数据流\n\n```\nClients(左) → Frontend → Backend → Database(右)\n```\n\n- Clients 通常放在 Region 框外左侧\n- 其他组件按 `flowSteps[].seqIndex` 排序，从左到右排列\n- 水平间距 40-60px，垂直居中对齐\n\n### 4.2 组件尺寸\n\n根据 capabilities 数量决定：\n\n| 能力数 | 宽度 | 高度 | 用途 |\n|--------|------|------|------|\n| 0-1 | 140px | 44px | 简单组件（SQS 等） |\n| 2-4 | 150px | 80px | 中等组件（Lambda、S3） |\n| 5+ | 160px | 80px | 大组件（API Gateway、DynamoDB） |\n\n所有组件：`rx=\"8\"` 圆角，`stroke-width=\"2\"` 描边。\n\n如果文本、特征列表或标签超出上述尺寸，不得硬压缩成“牙膏图”。优先顺序是：\n1. 增大卡片宽度或高度\n2. 将同层节点换到多行\n3. 扩大画布\n4. 必要时回退到 `freeflow`\n\n禁止通过把整层强行塞成一行、把图例改成浮层、或让底部内容被裁切来维持模板外观。\n\n### 4.3 Region 边界\n\n- 矩形框：`rx=\"16\"`, `stroke-dasharray=\"8,4\"`, 琥珀色 `#F59E0B`, `opacity=\"0.4\"`\n- Region 标签放在框外上方（x=Region左边界+20, y=Region上边界-10）\n- 填充：`none`（仅描边）\n\n### 4.4 Summary Cards\n\n放在架构图底部，3 组卡片，响应式网格布局：\n\n| 卡片 | 颜色 | 内容 |\n|------|------|------|\n| Infrastructure | 琥珀色 `#F59E0B` | 基础设施列表 |\n| Compute | 翠绿色 `#34D399` | 计算资源描述 |\n| Data | 紫色 `#A78BFA` | 数据存储描述 |\n\n每张卡片：`rx=\"10\"`, fill `#0F172A`, stroke `#1E293B`, 宽 340-370px, 高 130px。\n\n### 4.5 分层布局约束\n\n- 分层图中的“层”是语义分组，不是强制单行容器。\n- 每层 `1-3` 个节点时可单行展示。\n- 每层 `4-6` 个节点时默认拆成两行，保持卡片尺寸可读。\n- 每层 `7+` 个节点时应扩大画布或直接回退到 `freeflow`，不要继续压缩。\n- Actor / User 角色默认渲染为边栏标签、badge 或 lane header，不应伪装成普通系统卡片。\n\n### 4.6 Legend 位置\n\n- Legend 默认放在左下或底部保留区。\n- Legend 必须参与整体高度计算，不能作为右上角悬浮遮罩。\n- 禁止将 legend 放在 top-right 覆盖标题区或内容区。\n\n### 4.7 画布尺寸与裁切\n\n- `viewBox` 和最终 `height` 必须覆盖：最底部节点、legen"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Use when turning presales requirements, meeting notes, or solution materials into editable business capability blueprints, swimlane flows, and application ar... Skill: Business Blueprint Skill Owner: kaisersong Summary: Use when turning presales requirements, meeting notes, or solution materials into editable business capability blueprints, swimlane flows, and application ar... Tags: latest:0.15.0 Version history: v0.15.0 | 2026-04-30T14:17:32.981Z | user Domain-knowledge blueprints now produce product-grade strategy names (统一归因模型 vs 测款节奏). Adds namingHints to cross-border-e","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1534,"uniquenessScore":56,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T10:37:35.978Z","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-11T10:37:35.978Z","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-11T14:17:03.787Z","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"}]}}}