{
"canonical_name": "BrettNye/stoa",
"compilation_id": "pack_92607aaa10754b54bc669940ab08d9f0",
"created_at": "2026-05-15T06:14:47.576345+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npm i -g @stoa-mcp/cli` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npm i -g @stoa-mcp/cli",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_9df9c94e383d498885b8f47aad4919c9"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_c7c903fcacde9176328e27721533e764",
"canonical_name": "BrettNye/stoa",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/BrettNye/stoa",
"slug": "stoa",
"source_packet_id": "phit_654a6c2a8b454d8aac3cf50908f376cb",
"source_validation_id": "dval_413b9b2eea374cd085b8ac7ceb0dd907"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 mcp_host的用户",
"github_forks": 0,
"github_stars": 0,
"one_liner_en": "Persistent shared memory for AI coding agents (MCP server + CLI)",
"one_liner_zh": "Persistent shared memory for AI coding agents (MCP server + CLI)",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:code, coding, git"
},
"target_user": "使用 mcp_host, claude, claude_code 等宿主 AI 的用户",
"title_en": "stoa",
"title_zh": "stoa 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_654a6c2a8b454d8aac3cf50908f376cb",
"page_model": {
"artifacts": {
"artifact_slug": "stoa",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npm i -g @stoa-mcp/cli",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/BrettNye/stoa#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Persistent shared memory for AI coding agents (MCP server + CLI)"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude, claude_code",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1229401738 | https://github.com/BrettNye/stoa | host_targets=mcp_host, claude, claude_code"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1229401738 | https://github.com/BrettNye/stoa | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1229401738 | https://github.com/BrettNye/stoa | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1229401738 | https://github.com/BrettNye/stoa | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1,
"forks": 0,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 0
},
"source_url": "https://github.com/BrettNye/stoa",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Persistent shared memory for AI coding agents (MCP server + CLI)",
"title": "stoa 能力包",
"trial_prompt": "# stoa - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 stoa 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Persistent shared memory for AI coding agents (MCP server + CLI) 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. concepts：核心概念。围绕“核心概念”模拟一次用户任务，不展示安装或运行结果。\n3. architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. eventbus：事件总线系统。围绕“事件总线系统”模拟一次用户任务，不展示安装或运行结果。\n5. recall-system：召回与检索系统。围绕“召回与检索系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. concepts\n输入：用户提供的“核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. eventbus\n输入：用户提供的“事件总线系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. recall-system\n输入：用户提供的“召回与检索系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / concepts：Step 2 必须围绕“核心概念”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / eventbus：Step 4 必须围绕“事件总线系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / recall-system：Step 5 必须围绕“召回与检索系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/BrettNye/stoa\n- https://github.com/BrettNye/stoa#readme\n- README.md\n- package.json\n- src/config.ts\n- src/core/wikis.ts\n- src/core/claims.ts\n- src/core/pages.ts\n- src/core/profiles.ts\n- src/core/scope-hash.ts\n- src/cli/index.ts\n- src/core/index.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 stoa 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。",
"items": [],
"status": "待发现 Agent 补证",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Persistent shared memory for AI coding agents (MCP server + CLI)",
"effort": "安装已验证",
"forks": 0,
"icon": "code",
"name": "stoa 能力包",
"risk": "需复核",
"slug": "stoa",
"stars": 0,
"tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/BrettNye/stoa 项目说明书\n\n生成时间：2026-05-13 16:44:51 UTC\n\n## 目录\n\n- [项目概述](#overview)\n- [核心概念](#concepts)\n- [系统架构](#architecture)\n- [传输层实现](#transport)\n- [事件总线系统](#eventbus)\n- [召回与检索系统](#recall-system)\n- [Wiki管理](#wiki-management)\n- [任务协作系统](#task-coordination)\n- [Claims与Evolution系统](#claims-evolution)\n- [CLI命令参考](#cli-commands)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [核心概念](#concepts)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/index.ts](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts)\n- [src/core/pages.ts](https://github.com/BrettNye/stoa/blob/main/src/core/pages.ts)\n- [src/core/wikilinks.ts](https://github.com/BrettNye/stoa/blob/main/src/core/wikilinks.ts)\n- [src/core/synthesize.ts](https://github.com/BrettNye/stoa/blob/main/src/core/synthesize.ts)\n- [src/core/syntheses.ts](https://github.com/BrettNye/stoa/blob/main/src/core/syntheses.ts)\n- [src/core/family.ts](https://github.com/BrettNye/stoa/blob/main/src/core/family.ts)\n- [src/core/frontmatter.ts](https://github.com/BrettNye/stoa/blob/main/src/core/frontmatter.ts)\n- [src/transport/stdio.ts](https://github.com/BrettNye/stoa/blob/main/src/transport/stdio.ts)\n- [src/core/skills-platform.ts](https://github.com/BrettNye/stoa/blob/main/src/core/skills-platform.ts)\n- [src/core/lint-checks/synthesis-debt.ts](https://github.com/BrettNye/stoa/blob/main/src/core/lint-checks/synthesis-debt.ts)\n \n\n# 项目概述\n\n## 项目简介\n\n**stoa** 是一个基于 Markdown 文件系统的知识库管理系统（Knowledge Vault System），通过结构化的组织方式管理包含前端matter 的 markdown 文件。该系统提供了页面索引、维基链接解析、合成页面生成、语法检查、CLI 命令工具以及 MCP（Model Context Protocol）服务等核心功能。\n\n系统的核心设计理念是将知识以标准化的页面形式存储在文件系统中，通过索引和工具层实现高级的知识管理操作，如跨页面引用、批量合成、部署漂移检测等。\n\n## 核心架构\n\n### 系统层次结构\n\nstoa 采用分层架构设计，主要包含以下层次：\n\n```mermaid\ngraph TD\n A[CLI 层] --> B[工具层]\n B --> C[核心业务层]\n C --> D[传输层]\n D --> E[文件系统]\n \n F[lint-checks] --> C\n G[index] --> C\n H[pages] --> C\n I[synthesize] --> C\n```\n\n### 目录结构\n\n项目源码按功能模块组织：\n\n| 目录 | 职责 |\n|------|------|\n| `src/core/` | 核心业务逻辑，包含索引、页面操作、合成、链接解析等 |\n| `src/tools/` | MCP 工具实现，如 profile-register 等 |\n| `src/cli/` | 命令行接口实现 |\n| `src/transport/` | 传输层实现，如 stdio 服务器 |\n| `src/core/lint-checks/` | 各种语法检查规则实现 |\n\n## 核心模块\n\n### 页面管理（pages）\n\n页面是 stoa 的基本存储单元，每个页面对应一个 markdown 文件。\n\n```mermaid\ngraph LR\n A[page id] --> B[pathForPage]\n B --> C[文件系统路径]\n D[readPage] --> E[返回页面对象]\n F[writePage] --> G[持久化到磁盘]\n```\n\n页面对象包含以下字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 页面唯一标识符 |\n| `path` | string | 文件系统路径 |\n| `frontmatter` | Record | YAML 前端配置 |\n| `body` | string | markdown 正文内容 |\n| `updated` | string | ISO 日期格式的更新时间 |\n\n资料来源：[src/core/pages.ts:1-50]()\n\n页面读取时会解析文件的前端matter，提取元数据并规范化更新时间为 ISO 格式：\n\n```typescript\nconst raw = readFileSync(path, \"utf8\");\nconst { frontmatter, body } = parseFrontmatter(raw);\nreturn {\n id, path, frontmatter, body,\n updated: toIsoDate(frontmatter.updated ?? frontmatter.created)\n};\n```\n\n资料来源：[src/core/pages.ts:20-27]()\n\n### 索引系统（index）\n\n索引系统是 stoa 的核心组件，负责维护页面元数据的索引以支持高效查询。\n\n```mermaid\ngraph TD\n A[VaultIndex] --> B[pages]\n A --> C[wikis]\n A --> D[links]\n A --> E[profiles]\n A --> F[tokens]\n```\n\n索引数据结构 `VaultIndex` 包含以下子索引：\n\n| 索引 | 用途 |\n|------|------|\n| `pages` | 所有页面的元数据数组 |\n| `wikis` | wiki 列表及其配置 |\n| `links` | 页面间链接关系 |\n| `profiles` | profile 相关数据 |\n| `tokens` | 全文搜索令牌索引 |\n\n查询支持多维度过滤：\n\n```typescript\nif (f.wiki && wikiSet && !wikiSet.has(p.wiki)) return false;\nif (f.type && p.type !== f.type) return false;\nif (f.channel && p.channel !== f.channel) return false;\nif (f.layer && f.layer !== \"all\") {\n const set = f.layer === \"knowledge\" ? KNOWLEDGE_TYPES : EXECUTION_TYPES;\n if (!set.includes(p.type)) return false;\n}\n```\n\n资料来源：[src/core/index.ts:1-50]()\n\n### 维基链接解析（wikilinks）\n\n维基链接是 stoa 实现页面间关联的核心机制，支持 `[[wikis///(|alias)]]` 格式的链接。\n\n```mermaid\ngraph TD\n A[markdown 内容] --> B[wikilinkExtractor]\n B --> C{代码块检查}\n C -->|顶层代码块| D[跳过]\n C -->|普通内容| E[正则匹配]\n E --> F[WikilinkRef]\n \n F --> G[body]\n F --> H[frontmatter]\n```\n\n解析结果 `WikilinkRef` 接口定义：\n\n| 字段 | 类型 | 说明 | 来源 |\n|------|------|------|------|\n| `raw` | string | 原始链接文本 | body 或 frontmatter |\n| `wiki` | string | wiki 名称 | 路径解析 |\n| `type` | string | 页面类型 | 路径解析 |\n| `id` | string | 页面 ID | 路径解析 |\n| `alias` | string? | 可选别名 | 管道后文本 |\n| `source` | \"body\" \\| \"frontmatter\" | 链接来源位置 | 提取位置 |\n\n资料来源：[src/core/wikilinks.ts:1-40]()\n\n代码块感知：顶层代码块（行首的 ``` ）内的链接会被跳过，但嵌套在列表项中的缩进代码块不会被剥离。\n\n### 合成系统（synthesize）\n\n合成功能用于将多个相关页面聚合成一篇综合性的 synthesis 页面。\n\n```mermaid\ngraph TD\n A[输入: topic/by_agent] --> B[查询候选页面]\n B --> C[按类型过滤]\n C --> D[构建 synthesis 元数据]\n D --> E[生成 summary]\n E --> F[写入 synthesis 页面]\n```\n\n合成的页面元数据包含：\n\n| 字段 | 示例值 |\n|------|--------|\n| `type` | synthesis |\n| `wiki` | 目标 wiki |\n| `status` | draft |\n| `tags` | 根据作用域确定 |\n| `sources` | 来源页面的 wikilink 数组 |\n| `last_compiled` | ISO 日期 |\n| `scope` | \"memory\"（可选） |\n\n资料来源：[src/core/synthesize.ts:1-80]()\n\n### 合成陈旧度追踪（syntheses）\n\n系统追踪合成页面的陈旧程度，基于 `last_compiled` 时间戳计算滞后期。\n\n```mermaid\ngraph TD\n A[所有 synthesis 页面] --> B[读取 last_compiled]\n B --> C{时间戳存在?}\n C -->|是| D[计算 lag_days]\n D --> E{超过 min_lag_days?}\n E -->|是| F[加入结果集]\n C -->|否| G[标记为从未编译]\n E -->|否| H[过滤掉]\n```\n\n陈旧度数据结构 `SynthesisStaleness` 包含：\n\n- `pageId`: 页面标识\n- `wiki`: 所属 wiki\n- `lastCompiled`: ISO 日期或 null\n- `lagDays`: 自上次编译以来的天数或 null\n\n资料来源：[src/core/syntheses.ts:1-60]()\n\n### Family 解析（family）\n\nFamily 是 wiki 的上层组织单元，支持多 wiki 的批量操作。\n\n```mermaid\ngraph TD\n A[FamilyResolveCtx] --> B{解析优先级}\n B --> C[1. 显式 familyArg]\n B --> D[2. ctx.defaultFamily]\n B --> E[3. .active-family 文件]\n B --> F[4. 返回 null]\n \n C --> G{类型检查}\n G -->|wikiArg 存在| H[FamilyMismatchError]\n G -->|仅 familyArg| I[返回 familyArg]\n```\n\n解析上下文 `FamilyResolveCtx`：\n\n```typescript\ninterface FamilyResolveCtx {\n vaultPath: string;\n defaultFamily?: string;\n}\n```\n\n资料来源：[src/core/family.ts:1-50]()\n\n### 语法检查系统（lint-checks）\n\nlint 系统提供多维度的页面质量检查。\n\n#### 主要检查规则\n\n| 检查规则 | 严重程度 | 说明 |\n|----------|----------|------|\n| SYNTHESIS_DEBT | warn | 标记缺乏对应 synthesis 的硬知识聚类 |\n| CLAIM_WITH_NO_SCOPE | warn | 标记无作用域的 claim 页面 |\n| ACTIVE_WIKI_DIVERGENCE | info | 提示 defaultWiki 与 .active-wiki 不一致 |\n\n#### SYNTHESIS_DEBT 详解\n\n该检查识别满足以下条件的硬知识聚类：\n\n1. 至少 N 个（默认 3）页面共享同一 tag\n2. 这些页面都属于\"硬知识\"类型（concept、decision、spec）\n3. 该 wiki 下没有任何 synthesis 页面使用该 tag\n\n```typescript\nconst HARD_KNOWLEDGE_TYPES = new Set([\"concept\", \"decision\", \"spec\"]);\nconst DEFAULT_MIN_CLUSTER_SIZE = 3;\n```\n\n资料来源：[src/core/lint-checks/synthesis-debt.ts:1-50]()\n\n### 前端matter 模式（frontmatter）\n\n系统定义了严格的前端matter 验证模式。\n\n#### 页面类型（NoteType）\n\n```typescript\nexport const NoteType = z.enum([\n \"concept\", \"guide\", \"decision\", \"source\",\n \"idea\", \"question\", \"journal\", \"move\",\n \"claim\", \"map\", \"synthesis\"\n]);\n```\n\n#### 页面状态（PageStatus）\n\n```typescript\nexport const PageStatus = z.enum([\n \"draft\", \"active\", \"accepted\", \"superseded\", \"archived\"\n]);\n```\n\n#### 置信度（Confidence）\n\n```typescript\nexport const Confidence = z.enum([\"high\", \"medium\", \"low\"]);\n```\n\n#### 编排优先级（CurationPriority）\n\n用于标记需要人工关注的草案页面：\n\n```typescript\nexport const CurationPriority = z.enum([\"high\", \"medium\", \"low\"]);\n```\n\n资料来源：[src/core/frontmatter.ts:1-50]()\n\n### 技能平台（skills-platform）\n\n技能平台管理技能的部署和漂移检测。\n\n```mermaid\ngraph TD\n A[DriftDeployment] --> B[detectDriftAt]\n B --> C{文件状态}\n C -->|canonical 缺失| D[抛出错误]\n C -->|deployed 缺失| E[kind: missing]\n C -->|哈希不匹配| F[kind: hash-mismatch]\n C -->|哈希匹配| G[无报告]\n```\n\n检测规则：\n\n| 情况 | 处理方式 |\n|------|----------|\n| canonical 缺失 | 抛出异常（vault 完整性问题） |\n| deployed 缺失 | 报告 `kind: \"missing\"` |\n| 哈希不匹配 | 报告 `kind: \"hash-mismatch\"` |\n| 哈希匹配 | 不报告 |\n\n技能文件路径约定：\n\n- **canonical**: `/wikis/_agents/moves//SKILL.md`\n- **deployed**: `//SKILL.md`\n\n资料来源：[src/core/skills-platform.ts:1-60]()\n\n### MCP 服务（transport/stdio）\n\nMCP 服务通过 stdio 传输层提供工具接口。\n\n```mermaid\ngraph TD\n A[stdio 输入] --> B[JSON-RPC 解析]\n B --> C[工具路由]\n C --> D[profile-register]\n C --> E[其他工具]\n D --> F[StadiumClient]\n F --> G[平台 API]\n D --> H[更新 frontmatter]\n C --> I[返回 JSON-RPC 响应]\n```\n\n服务启动时通过 `walkInitablePaths` 预热状态缓存：\n\n```typescript\nfunction walkInitablePaths(vaultPath: string): string[] {\n // 递归遍历 wikis/ 目录\n // 返回所有 .md 文件路径\n // 用于构建初始状态\n}\n```\n\n资料来源：[src/transport/stdio.ts:1-60]()\n\n### 状态缓存（eventbus/state-cache）\n\n状态缓存为事件处理提供内存状态存储。\n\n```typescript\nclass StateCache {\n private states = new Map();\n \n private key(source: string, wiki: string, id: string): string {\n return `${source}:${wiki}:${id}`;\n }\n}\n```\n\n缓存键格式：`source:wiki:id`，支持按源、wiki、ID 三维定位状态。\n\n资料来源：[src/core/eventbus/state-cache.ts:1-30]()\n\n### 工具注册（tools/profile-register）\n\nprofile-register 工具将 profile 页面注册到 Stadium 平台。\n\n流程：\n\n1. 读取 `wikis//profiles/.md`\n2. 提取 `pokemon` 或 `species_name` 字段\n3. POST 到 `/profiles/register`\n4. 更新文件的 `platform_profile_id` 和 `platform_stats`\n\n资料来源：[src/tools/profile-register.ts:1-50]()\n\n## CLI 命令\n\n系统通过 commander 提供命令行接口：\n\n| 命令 | 功能 |\n|------|------|\n| `new-wiki ` | 创建新 wiki，需指定 `--mode` 和 `--scope` |\n\n创建 wiki 时的模式选项：\n\n- `idea-map`\n- `project-doc`\n- `learning`\n- `mixed`\n\n资料来源：[src/cli/commands/new-wiki.ts:1-30]()\n\n## 页面类型对应文件命名\n\n| 类型 | 文件命名规则 |\n|------|-------------|\n| concept, guide, source, idea, question, claim, synthesis | `-.md` |\n| decision | `decision-YYYY-MM-DD-.md` |\n| journal | `journal-YYYY-MM-DD-HHMM-.md` |\n| move | `/SKILL.md`（目录） |\n| map | `map.md`（固定名称） |\n\n资料来源：[src/core/ids.ts:1-30]()\n\n## 总结\n\nstoa 是一个功能完备的知识库管理系统，其核心价值在于：\n\n1. **文件系统优先**：所有数据以标准 markdown 文件存储，便于版本控制和人工编辑\n2. **结构化索引**：通过前端matter 和索引提供高效的元数据查询\n3. **链接驱动**：通过 wikilink 实现页面间的语义关联\n4. **质量保障**：多层 lint 检查确保知识库的一致性\n5. **工具扩展**：MCP 架构支持与其他系统的集成\n\n系统的设计遵循单一职责原则，各模块边界清晰，便于维护和扩展。\n\n---\n\n\n\n## 核心概念\n\n### 相关页面\n\n相关主题：[项目概述](#overview), [Wiki管理](#wiki-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/index.ts](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts)\n- [src/core/pages.ts](https://github.com/BrettNye/stoa/blob/main/src/core/pages.ts)\n- [src/core/frontmatter.ts](https://github.com/BrettNye/stoa/blob/main/src/core/frontmatter.ts)\n- [src/core/wikilinks.ts](https://github.com/BrettNye/stoa/blob/main/src/core/wikilinks.ts)\n- [src/core/channel.ts](https://github.com/BrettNye/stoa/blob/main/src/core/channel.ts)\n- [src/core/family.ts](https://github.com/BrettNye/stoa/blob/main/src/core/family.ts)\n- [src/core/synthesize.ts](https://github.com/BrettNye/stoa/blob/main/src/core/synthesize.ts)\n- [src/core/syntheses.ts](https://github.com/BrettNye/stoa/blob/main/src/core/syntheses.ts)\n \n\n# 核心概念\n\nStoa 是一个知识管理 MCP (Model Context Protocol) 服务器，旨在对笔记库 (vault) 进行索引、检索和一致性检查。以下文档详细介绍其核心概念与架构。\n\n## 页面类型系统\n\nStoa 采用结构化的页面类型体系，每种类型具有特定语义和存储约定。\n\n### 页面类型定义\n\n根据 `src/core/frontmatter.ts` 的定义，核心页面类型包括：\n\n| 类型 | 语义 | 文件命名规则 |\n|------|------|-------------|\n| `concept` | 概念性知识 | `concept-.md` |\n| `decision` | 决策记录 | `decision-YYYY-MM-DD-.md` |\n| `journal` | 日志条目 | `journal-YYYY-MM-DD-HHMM-.md` |\n| `guide` | 操作指南 | `guide-.md` |\n| `source` | 外部引用 | `source-.md` |\n| `idea` | 想法 | `idea-.md` |\n| `question` | 问题 | `question-.md` |\n| `spec` | 规格说明 | `spec-.md` |\n| `synthesis` | 综合页面 | `synthesis-.md` |\n| `move` | 技能移动 | `move-/SKILL.md` (目录结构) |\n| `map` | 维基地图 | `map.md` (固定文件名) |\n\n资料来源：[src/core/frontmatter.ts:1-30]()\n\n### 页面状态\n\n页面状态使用枚举定义：\n\n```typescript\nexport const PageStatus = z.enum([\n \"draft\", \"active\", \"accepted\", \"superseded\", \"archived\"\n]);\n```\n\n- **draft**: 草稿状态\n- **active**: 活跃状态\n- **accepted**: 已接受\n- **superseded**: 已替代\n- **archived**: 已归档\n\n资料来源：[src/core/frontmatter.ts:35-37]()\n\n### 置信度等级\n\n```typescript\nexport const Confidence = z.enum([\"high\", \"medium\", \"low\"]);\n```\n\n资料来源：[src/core/frontmatter.ts:39-40]()\n\n### 整理优先级\n\n用于标记草稿页面的整理优先级，帮助人类注意力分配：\n\n```typescript\nexport const CurationPriority = z.enum([\"high\", \"medium\", \"low\"]);\n```\n\n资料来源：[src/core/frontmatter.ts:48-49]()\n\n## 维基与家族体系\n\n### Wiki 结构\n\nStoa 使用多 Wiki 架构，每个 Wiki 存储在 `vaultPath/wikis//` 目录下。\n\n### 家族解析顺序\n\n`src/core/family.ts` 定义了家族 (family) 解析的优先级：\n\n1. 显式 `familyArg` 参数\n2. MCP CLI 参数 `--default-family`\n3. `vaultPath/.active-family` 文件\n4. `null` → 回退到单 Wiki 解析\n\n```typescript\nexport function resolveFamily(\n ctx: FamilyResolveCtx,\n familyArg?: string,\n wikiArg?: string,\n knownWikis?: Record\n): string | null\n```\n\n资料来源：[src/core/family.ts:38-58]()\n\n### Wiki 与家族校验\n\n当同时提供 `familyArg` 和 `wikiArg` 时，系统会校验 Wiki 所属家族是否匹配：\n\n```typescript\nif (wikiFamily !== familyArg) {\n throw new FamilyMismatchError(\n `wiki '${wikiArg}' has family '${wikiFamily ?? \"(none)\"}' which does not match requested family '${familyArg}'`\n );\n}\n```\n\n资料来源：[src/core/family.ts:47-51]()\n\n## Wiki 链接系统\n\n### Wikilink 格式\n\nWiki 链接采用标准化格式：\n\n```\n[[wikis///(|alias)?]]\n```\n\n例如：`[[wikis/_meta/concepts/concept-trust-gradient-axes]]`\n\n### Wikilink 提取器\n\n`src/core/wikilinks.ts` 提供了结构化的链接引用接口：\n\n```typescript\nexport interface WikilinkRef {\n raw: string;\n wiki: string;\n type: string;\n id: string;\n alias?: string;\n source: \"body\" | \"frontmatter\";\n}\n```\n\n资料来源：[src/core/wikilinks.ts:22-29]()\n\n### 代码块感知\n\nWikilink 提取器具有代码块感知能力：\n\n- 顶层 fenced 代码块 (` ``` `) 内的链接会被跳过\n- 缩进代码块（如列表项内的 4 空格缩进）**不会**被剥离\n- 内联单反引号代码 span **不会**被剥离\n\n资料来源：[src/core/wikilinks.ts:24-34]()\n\n### Wikilink 职责分离\n\n- **提取职责** (`wikilinks.ts`)：仅提取结构化链接引用\n- **完整性检查** (`lint-checks/cross-wiki-link-broken.ts`)：检查目标页面是否存在\n\n资料来源：[src/core/wikilinks.ts:14-16]()\n\n## 页面索引与查询\n\n### VaultIndex 结构\n\n索引文件 `_index/pages.json` 存储所有页面的元数据：\n\n```typescript\ninterface VaultIndex {\n pages: IndexedPage[];\n wikis: IndexedWiki[];\n}\n```\n\n资料来源：[src/core/index.ts:1-50]()\n\n### 页面查询\n\n使用 `queryPages` 函数进行多条件过滤：\n\n```typescript\nexport function queryPages(\n idx: VaultIndex,\n f: PageFilter\n): IndexedPage[]\n```\n\n支持的过滤条件：\n\n| 过滤器字段 | 说明 |\n|-----------|------|\n| `wiki` | Wiki 名称精确匹配 |\n| `wikis` | Wiki 名称集合 |\n| `type` | 页面类型精确匹配 |\n| `channel` | 频道名称精确匹配 |\n| `status` | 页面状态精确匹配 |\n| `layer` | `\"knowledge\"` 或 `\"execution\"` 或 `\"all\"` |\n\n资料来源：[src/core/index.ts:80-95]()\n\n### 全文搜索\n\n`upsertTokenize` 函数使用 Porter Stemmer 进行词干提取和停用词过滤：\n\n```typescript\nconst UPSERT_STOP_WORDS = new Set([\n \"the\",\"and\",\"of\",\"a\",\"an\",\"in\",\"to\",\"is\",\"for\",\"on\",\n \"with\",\"as\",\"at\",\"by\",\"or\",\"be\",\"this\",\"that\",\"it\",\n \"from\",\"are\",\"was\",\"were\",\"not\",\"but\",\"if\"\n]);\n```\n\n资料来源：[src/core/index.ts:65-67]()\n\n## 页面读写操作\n\n### 读取页面\n\n`readPage` 函数根据 ID 解析页面路径：\n\n```typescript\nexport function readPage(\n vaultPath: string,\n wiki: string,\n id: string\n): ReadPageResult\n```\n\n路径解析顺序：\n1. `wikis///.md` (按类型遍历)\n2. `map-.md` 或 `map.md`\n\n资料来源：[src/core/pages.ts:40-80]()\n\n### 写入页面\n\n```typescript\nexport interface WritePageInput {\n id: string;\n type: NoteType;\n wiki: string;\n frontmatter: Record;\n body: string;\n expectedUpdated?: string; // 乐观锁\n}\n\nexport function writePage(\n vaultPath: string,\n input: WritePageInput\n): WritePageResult\n```\n\n**乐观锁机制**：若提供 `expectedUpdated`，系统会验证现有文件的 updated 时间戳，防止并发覆盖。\n\n资料来源：[src/core/pages.ts:82-100]()\n\n## 频道系统\n\n### 频道日志\n\n频道 (channel) 用于聚合 `journal` 类型页面的活动摘要：\n\n```typescript\ninterface ChannelSummary {\n name: string;\n wiki: string;\n lastEntry: ChannelEntry | null;\n count24h: number;\n}\n```\n\n资料来源：[src/core/channel.ts:20-24]()\n\n### 频道条目\n\n```typescript\ninterface ChannelEntry {\n id: string;\n channel: string;\n wiki: string;\n author: string;\n ts: string;\n excerpt: string; // 前 240 字符\n pageId: string;\n}\n```\n\n资料来源：[src/core/channel.ts:26-33]()\n\n## 综合页面 (Synthesis)\n\n### Synthesis 创建\n\n`synthesize` 命令生成综合页面：\n\n```typescript\nconst fm: Record = {\n id,\n title: `${input.topic} — synthesis`,\n type: \"synthesis\",\n wiki,\n status: \"draft\",\n created: today,\n updated: today,\n summary: `Synthesis of ${inputIds.length} pages on \"${input.topic}\".`,\n tags: [],\n last_compiled: today,\n sources: inputIds.map(i => `[[wikis/${wiki}/${typeFolderForId(i)}/${i}]]`)\n};\n```\n\n资料来源：[src/core/synthesize.ts:60-75]()\n\n### Synthesis 陈旧度检测\n\n`detectSynthesisStaleness` 函数计算页面\"过时\"程度：\n\n```typescript\nif (lastCompiled) {\n const compiledMs = new Date(lastCompiled).getTime();\n lagDays = Math.floor((now - compiledMs) / MS_PER_DAY);\n}\n```\n\n资料来源：[src/core/syntheses.ts:55-58]()\n\n### Synthesis 债务检测\n\n当同标签的硬知识页面聚类缺少对应的综合页面时，触发警告：\n\n```typescript\nexport const DEFAULT_MIN_CLUSTER_SIZE = 3;\n\nconst HARD_KNOWLEDGE_TYPES = new Set([\n \"concept\", \"decision\", \"spec\"\n]);\n```\n\n资料来源：[src/core/synthesize.ts:30-40]()\n\n## 标记渲染系统\n\n### 托管区域契约\n\nMarker 系统用于在文档中维护\"托管区域\"：\n\n- **起始标记**: ``\n- **结束标记**: ``\n- **幂等性**: 相同输入产生字节级相同的输出\n\n```typescript\nexport interface MarkerOptions {\n renderedDate?: string; // ISO 日期\n halfLifeDays?: number; // 半衰期（天）\n}\n```\n\n资料来源：[src/core/marker-render.ts:20-24]()\n\n### 使用场景\n\n- **Claims 汇总** (`synthesize`)\n- **技能/代理文档补丁** (`sync-skills`, `bootstrap-repo`)\n\n资料来源：[src/core/marker-render.ts:6-10]()\n\n## 状态缓存\n\n`StateCache` 提供简单的内存状态缓存：\n\n```typescript\nexport class StateCache {\n private states = new Map();\n\n private key(source: string, wiki: string, id: string): string {\n return `${source}:${wiki}:${id}`;\n }\n\n get(source: string, wiki: string, id: string): T | undefined;\n set(source: string, wiki: string, id: string, state: T): void;\n has(source: string, wiki: string, id: string): boolean;\n size(): number;\n}\n```\n\n资料来源：[src/core/eventbus/state-cache.ts:1-25]()\n\n### MCP 预热机制\n\n`walkInitablePaths` 函数在接收变更事件前预热状态缓存：\n\n```typescript\nfunction walkInitablePaths(vaultPath: string): string[] {\n // 遍历 wikis/ 目录，收集所有 .md 文件路径\n}\n```\n\n资料来源：[src/core/stdio.ts:50-75]()\n\n## 命名规范\n\n### ID 格式\n\n| 类型 | ID 格式要求 |\n|------|-------------|\n| 普通页面 | 小写字母、数字、连字符 `^[a-z0-9-]+$` |\n| Channel | 小写 kebab-case `^[a-z0-9]+(-[a-z0-9]+)*$` |\n| 日期 | ISO 格式 `^\\d{4}-\\d{2}-\\d{2}$` |\n\n资料来源：[src/core/frontmatter.ts:41-44]()\n\n## 架构总览\n\n```mermaid\ngraph TD\n subgraph \"MCP 接口层\"\n STDIO[STDIO 传输]\n MCP[MCP 服务器]\n end\n\n subgraph \"核心处理层\"\n IDX[索引系统]\n QUERY[查询引擎]\n LINT[Lint 检查]\n SYNC[同步引擎]\n end\n\n subgraph \"存储层\"\n PAGES[Pages 读写]\n FRONT[Frontmatter 解析]\n WIKI[Wikilinks]\n CHAN[Channel]\n end\n\n subgraph \"文件系统\"\n VAULT[Vault 目录]\n WIKIS[wikis/ 目录]\n INDEX[_index/ 目录]\n end\n\n STDIO --> MCP\n MCP --> IDX\n IDX --> QUERY\n IDX --> LINT\n SYNC --> PAGES\n PAGES --> FRONT\n PAGES --> WIKI\n IDX --> CHAN\n QUERY --> INDEX\n IDX --> VAULT\n VAULT --> WIKIS\n IDX --> INDEX\n```\n\n## 术语表\n\n| 术语 | 定义 |\n|------|------|\n| **Vault** | 根目录下的笔记库，包含 wikis/ 和 _index/ |\n| **Wiki** | 某个主题领域的页面集合，位于 `wikis//` |\n| **Family** | Wiki 的分组，用于批量操作 |\n| **Synthesis** | 综合页面，聚合多个同标签页面的内容 |\n| **Hard Knowledge** | 核心知识类型 (concept, decision, spec) |\n| **Soft Knowledge** | 非核心类型 (guide, source, idea, question) |\n| **Marker** | 托管区域的边界标记 |\n| **Channel** | 聚合日志条目的频道 |\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[传输层实现](#transport), [事件总线系统](#eventbus), [项目概述](#overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/index.ts](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts)\n- [src/core/start.ts](https://github.com/BrettNye/stoa/blob/main/src/core/start.ts)\n- [src/core/pages.ts](https://github.com/BrettNye/stoa/blob/main/src/core/pages.ts)\n- [src/core/synthesize.ts](https://github.com/BrettNye/stoa/blob/main/src/core/synthesize.ts)\n- [src/core/family.ts](https://github.com/BrettNye/stoa/blob/main/src/core/family.ts)\n- [src/core/lint.ts](https://github.com/BrettNye/stoa/blob/main/src/core/lint.ts)\n- [src/core/frontmatter.ts](https://github.com/BrettNye/stoa/blob/main/src/core/frontmatter.ts)\n- [src/transport/stdio.ts](https://github.com/BrettNye/stoa/blob/main/src/transport/stdio.ts)\n- [src/core/skills-platform.ts](https://github.com/BrettNye/stoa/blob/main/src/core/skills-platform.ts)\n- [src/core/rewrite-links.ts](https://github.com/BrettNye/stoa/blob/main/src/core/rewrite-links.ts)\n \n\n# 系统架构\n\n## 概述\n\nStoa 是一个基于 Model Context Protocol (MCP) 的知识库管理系统，通过 STDIO 传输层与 LLM 代理进行通信。其核心功能围绕**页面索引**、**合成（Synthesis）管理**、**代码检查（Lint）** 和**技能平台**四大模块展开。系统采用 vault 结构的 Markdown 文件存储，页面之间通过 wikilink 互相引用，形成一个自包含的知识图谱。资料来源：[src/transport/stdio.ts:30-35]()\n\n## 核心设计理念\n\nStoa 采用单职责原则设计，各模块职责明确划分：\n\n| 模块 | 职责 | 核心文件 |\n|------|------|----------|\n| 索引系统 | 页面元数据提取、全文搜索、token 管理 | `src/core/index.ts` |\n| 页面操作 | 页面读写、路径解析、版本控制 | `src/core/pages.ts` |\n| 合成引擎 | 多页面聚合、摘要生成、来源追踪 | `src/core/synthesize.ts` |\n| Lint 系统 | 规则检查、诊断报告、错误修复 | `src/core/lint.ts` |\n| 技能平台 | 技能部署、漂移检测、版本管理 | `src/core/skills-platform.ts` |\n| 家族解析 | 多 wiki 聚合、家族范围查询 | `src/core/family.ts` |\n\n资料来源：[src/core/index.ts:1-50]()\n\n## 系统层次架构\n\n```mermaid\ngraph TD\n subgraph 传输层[\"传输层 (Transport)\"]\n STDIO[STDIO Server Transport]\n end\n \n subgraph 服务层[\"服务层 (Service)\"]\n MCP[MCP Server]\n Tools[Tools Layer]\n end\n \n subgraph 核心业务[\"核心业务 (Core)\"]\n Index[索引系统]\n Pages[页面管理]\n Synthesize[合成引擎]\n Lint[代码检查]\n Skills[技能平台]\n Family[家族解析]\n end\n \n subgraph 数据层[\"数据层 (Data)\"]\n Vault[Vault 存储]\n IndexFiles[_index 索引文件]\n Frontmatter[Frontmatter 元数据]\n end\n \n STDIO --> MCP\n MCP --> Tools\n Tools --> Index\n Tools --> Pages\n Tools --> Synthesize\n Tools --> Lint\n Tools --> Skills\n Tools --> Family\n \n Index --> IndexFiles\n Pages --> Vault\n Synthesize --> Index\n Lint --> Index\n```\n\n## 索引系统\n\n### 索引数据结构\n\n系统维护多个索引文件用于快速查询：\n\n```mermaid\ngraph LR\n subgraph _index[\"_index/ 目录\"]\n PagesIdx[_index/pages.json]\n TokensIdx[_index/tokens.json]\n LinksIdx[_index/links.json]\n WikisIdx[_index/wikis.json]\n ProfilesIdx[_index/profiles.json]\n end\n \n subgraph 源数据[\"Vault 源文件\"]\n Markdown[*.md 文件]\n Frontmatter[Frontmatter]\n end\n \n Markdown -->|解析| Frontmatter\n Frontmatter -->|提取| PagesIdx\n Frontmatter -->|分词| TokensIdx\n Frontmatter -->|链接提取| LinksIdx\n WikisIdx -->|Wiki 配置| ProfilesIdx\n```\n\n索引系统通过 `VaultIndex` 接口提供统一的数据访问：\n\n```typescript\nexport interface VaultIndex {\n pages: IndexedPage[];\n wikis: IndexedWiki[];\n profiles: IndexedProfile[];\n links: IndexedLink[];\n tokens: Record;\n}\n```\n\n资料来源：[src/core/index.ts:1-30]()\n\n### 页面类型体系\n\nStoa 定义了严格的页面类型系统：\n\n| 类型 | 说明 | 文件命名规范 |\n|------|------|-------------|\n| `concept` | 概念页面 | `concept-.md` |\n| `decision` | 决策记录 | `decision-YYYY-MM-DD-.md` |\n| `guide` | 操作指南 | `guide-.md` |\n| `source` | 外部引用 | `source-.md` |\n| `idea` | 想法记录 | `idea-.md` |\n| `question` | 问题记录 | `question-.md` |\n| `journal` | 日志条目 | `journal-YYYY-MM-DD-HHMM-.md` |\n| `move` | 技能移动 | `move-/SKILL.md` |\n| `map` | 地图页面 | `map.md` (固定命名) |\n| `synthesis` | 合成页面 | 自动生成 |\n\n资料来源：[src/core/ids.ts:1-25]()\n\n### 搜索与查询\n\n系统支持多维度查询过滤：\n\n```typescript\nexport interface PageFilter {\n wiki?: string;\n type?: NoteType;\n channel?: string;\n status?: PageStatus;\n layer?: \"knowledge\" | \"execution\" | \"all\";\n}\n```\n\n全文搜索使用 Porter Stemmer 算法进行词干提取，支持停用词过滤：\n\n```typescript\nfunction upsertTokenize(text: string): string[] {\n return text.toLowerCase()\n .replace(/[^a-z0-9\\s]/g, \" \")\n .split(/\\s+/)\n .filter(t => t.length > 1 && !UPSERT_STOP_WORDS.has(t))\n .map(t => upsertStemmer.stem(t));\n}\n```\n\n资料来源：[src/core/index.ts:35-50]()\n\n## 页面管理系统\n\n### 页面读写流程\n\n```mermaid\ngraph TD\n A[请求读写页面] --> B{页面是否存在}\n B -->|不存在| C[新建页面]\n B -->|存在| D{是否有 expectedUpdated}\n D -->|有| E[乐观锁检查]\n E -->|版本匹配| F[写入文件]\n E -->|版本不匹配| G[抛出错误]\n D -->|无| F\n C --> H[生成路径]\n F --> I[更新索引]\n H --> I\n```\n\n### 页面路径解析\n\n路径生成遵循以下规则：\n\n| 页面类型 | 路径模板 |\n|----------|----------|\n| 普通页面 | `wikis/{wiki}/{type}/{id}.md` |\n| 地图页面 | `wikis/{wiki}/map.md` |\n| 技能移动 | `wikis/_agents/moves/{id}/SKILL.md` |\n| 技能档案 | `wikis/_agents/profiles/{id}.md` |\n\n资料来源：[src/core/pages.ts:1-60]()\n\n## Frontmatter 验证\n\n### 验证模式\n\n系统使用 Zod 进行运行时验证：\n\n```typescript\nconst draftSchema = z.object({\n id: z.string().regex(/^[a-z0-9-]+$/),\n title: z.string().min(1),\n type: NoteType,\n created: z.string().regex(ISO_DATE),\n channel: z.string().regex(KEBAB).optional(),\n});\n\nexport const PageStatus = z.enum([\n \"draft\", \"active\", \"accepted\", \"superseded\", \"archived\"\n]);\n\nexport const Confidence = z.enum([\"high\", \"medium\", \"low\"]);\n\nexport const CurationPriority = z.enum([\"high\", \"medium\", \"low\"]);\n```\n\n资料来源：[src/core/frontmatter.ts:1-50]()\n\n### 状态流转\n\n| 状态 | 说明 | 允许的转换 |\n|------|------|------------|\n| `draft` | 草稿状态 | `active` |\n| `active` | 活跃状态 | `accepted`, `archived` |\n| `accepted` | 已接受 | `superseded`, `archived` |\n| `superseded` | 已废弃 | 无 |\n| `archived` | 归档 | 无 |\n\n## 合成引擎\n\n### 合成类型\n\n系统支持两种合成模式：\n\n| 模式 | 说明 | 生成条件 |\n|------|------|----------|\n| `topic` | 主题合成 | 按标签聚合相关页面 |\n| `memory` | 记忆合成 | 按代理聚合其 authored 页面 |\n\n### 合成数据结构\n\n```mermaid\ngraph TD\n subgraph 合成输入[\"合成输入\"]\n Topic[Topic 标签]\n Tags[多个 Tag]\n Pages[源页面列表]\n end\n \n subgraph 合成过程[\"合成过程\"]\n Extract[提取引用]\n Generate[生成摘要]\n Render[渲染标记区域]\n end\n \n subgraph 合成输出[\"合成输出\"]\n Synthesis[Synthesis 页面]\n Sources[Sources 列表]\n Markers[标记区域]\n end\n \n Topic --> Extract\n Tags --> Extract\n Pages --> Extract\n Extract --> Generate\n Generate --> Render\n Render --> Synthesis\n```\n\n合成页面的 frontmatter 结构：\n\n```yaml\nid: \ntitle: \"{topic} — synthesis\"\ntype: synthesis\nwiki: \nstatus: draft\ncreated: \nupdated: \nsummary: \"Synthesis of {count} pages on \\\"{topic}\\\".\"\ntags: []\nlast_compiled: \nsources: [wikilinks to source pages]\n```\n\n资料来源：[src/core/synthesize.ts:1-80]()\n\n### 合成陈旧度检测\n\n系统可检测长时间未重新编译的合成页面：\n\n```typescript\nexport interface SynthesisStaleness {\n id: string;\n wiki: string;\n lag_days: number | null;\n last_compiled: string | null;\n}\n```\n\n陈旧度计算基于 `last_compiled` 字段与当前时间的差值：\n\n```typescript\nif (lastCompiled) {\n const compiledMs = new Date(lastCompiled).getTime();\n lagDays = Math.floor((now - compiledMs) / MS_PER_DAY);\n}\n```\n\n资料来源：[src/core/syntheses.ts:1-60]()\n\n## Lint 检查系统\n\n### 检查规则体系\n\n```mermaid\ngraph LR\n subgraph 规则类型[\"规则分类\"]\n Error[Error 级规则]\n Warning[Warning 级规则]\n Info[Info 级规则]\n end\n \n subgraph 检查范围[\"检查范围\"]\n Frontmatter[Frontmatter 检查]\n Content[内容检查]\n Filename[文件名检查]\n Links[链接检查]\n CrossWiki[跨 Wiki 检查]\n end\n \n Frontmatter -->|验证| Error\n Content -->|验证| Warning\n Filename -->|验证| Warning\n Links -->|验证| Info\n```\n\n### 核心检查规则\n\n| 规则代码 | 严重级别 | 说明 |\n|----------|----------|------|\n| `FILENAME_ID_MISMATCH` | warning | 文件名与 ID 不匹配 |\n| `BAD_CHANNEL_FORMAT` | warning | Channel 格式非法（需 kebab-case） |\n| `CLAIM_WITH_NO_SCOPE` | warn | Claim 无作用域定义 |\n| `SYNTHESIS_DEBT` | info | 存在未合成的知识集群 |\n| `SNIPPET_NO_IMPLEMENTATION` | warning | 代码片段缺少实现引用 |\n| `CROSS_WIKI_LINK_BROKEN` | error | 跨 Wiki 链接目标不存在 |\n| `MISSING_CURATION_PRIORITY` | info | Agent 创作的草稿缺少整理优先级 |\n\n资料来源：[src/core/lint.ts:1-100]()\n\n### 特定 Wiki 检查\n\n针对 `_agents` wiki 有专门的检查逻辑：\n\n- **Profile 检查**：验证 profile 页面存在且格式正确\n- **Move 检查**：验证 move 目录结构符合规范（需包含 `SKILL.md`）\n- **别名漂移检查**（ALIAS_DRIFT）：检测 agent 别名与实际页面的不一致\n\n## 技能平台\n\n### 技能部署架构\n\n```mermaid\ngraph TD\n subgraph 源端[\"Vault 源端\"]\n Canonical[Canonical SKILL.md]\n MoveDir[move-{id} 目录]\n end\n \n subgraph 部署端[\"Deployment 端\"]\n DeployDir[部署目录]\n Deployed[Deployed SKILL.md]\n end\n \n subgraph 检测机制[\"漂移检测\"]\n Hash1[源文件哈希]\n Hash2[部署文件哈希]\n Compare[比较结果]\n end\n \n Canonical --> Hash1\n Deployed --> Hash2\n Hash1 --> Compare\n Hash2 --> Compare\n Compare -->|匹配| OK[无需更新]\n Compare -->|不匹配| Drift[报告漂移]\n Compare -->|缺失| Missing[报告缺失]\n```\n\n### 漂移报告类型\n\n| 类型 | 说明 | 触发条件 |\n|------|------|----------|\n| `missing` | 部署端缺失 | 部署目录中无对应 SKILL.md |\n| `hash-mismatch` | 哈希不匹配 | 源文件与部署文件内容不一致 |\n\n```typescript\nexport interface DriftReport {\n move_id: string;\n kind: \"missing\" | \"hash-mismatch\";\n actual_hash: string | undefined;\n}\n```\n\n资料来源：[src/core/skills-platform.ts:1-60]()\n\n## 家族解析系统\n\n### 家族解析优先级\n\n系统按以下顺序解析家族范围：\n\n```mermaid\ngraph TD\n A{是否有显式 family 参数?} -->|是| B[使用显式参数]\n A -->|否| C{是否有 defaultFamily?}\n C -->|是| D[使用 defaultFamily]\n C -->|否| E{是否有 .active-family 文件?}\n E -->|是| F[使用文件内容]\n E -->|否| G[返回 null, 单 Wiki 解析]\n```\n\n### 家族不匹配检测\n\n当同时提供 `family` 和 `wiki` 参数时，系统会验证一致性：\n\n```typescript\nif (wikiFamily !== familyArg) {\n throw new FamilyMismatchError(\n `wiki '${wikiArg}' has family '${wikiFamily}' which does not match requested family '${familyArg}'`\n );\n}\n```\n\n资料来源：[src/core/family.ts:1-50]()\n\n## Wikilink 处理\n\n### 链接格式规范\n\n系统支持 vault-root 绝对路径格式的 wikilink：\n\n```\n[[wikis/{wiki}/{type}/{id}(|alias)?]]\n```\n\n### 链接提取规则\n\n| 场景 | 是否提取 |\n|------|----------|\n| 顶层代码块内链接 | ❌ 跳过 |\n| 嵌套代码块内链接 | ✅ 提取（v1.6 Phase 1 限制） |\n| 单反引号行内代码 | ✅ 提取 |\n| Frontmatter related 数组 | ✅ 提取 |\n\n```typescript\nexport interface WikilinkRef {\n raw: string;\n wiki: string;\n type: string;\n id: string;\n alias?: string;\n source: \"body\" | \"frontmatter\";\n}\n```\n\n资料来源：[src/core/wikilinks.ts:1-30]()\n\n### 链接重写\n\n支持批量前缀重写，保持语义一致性：\n\n```typescript\nexport interface RewriteScope {\n body: boolean;\n frontmatter: boolean;\n}\n\nexport interface PageRewrite {\n page_id: string;\n links_rewritten: number;\n new_body: string;\n new_related: string[] | undefined;\n}\n```\n\n资料来源：[src/core/rewrite-links.ts:1-40]()\n\n## 传输层\n\n### STDIO 服务器\n\n系统通过 STDIO 与 MCP 客户端通信：\n\n```mermaid\ngraph LR\n subgraph MCP客户端[\"MCP Client (LLM Agent)\"]\n JSONRPC[JSON-RPC Requests]\n end\n \n subgraph STDIO传输[\"STDIO Transport\"]\n Stdin[stdin]\n Stdout[stdout]\n Stderr[stderr (日志)]\n end\n \n JSONRPC -->|输入| Stdin\n Stdout -->|输出| JSONRPC\n Stderr -->|诊断| Console\n```\n\n服务器初始化输出：\n\n```\nvault-mcp stdio server ready (vault={path}, default-wiki={wiki}, default-family={family})\n```\n\n资料来源：[src/transport/stdio.ts:1-60]()\n\n## 配置与扩展\n\n### 运行时配置\n\n| 配置项 | 说明 | 来源 |\n|--------|------|------|\n| `vaultPath` | Vault 根目录路径 | 必需参数 |\n| `defaultWiki` | 默认 Wiki 名称 | CLI 参数 |\n| `defaultFamily` | 默认家族名称 | CLI 参数 |\n\n### 扩展机制\n\n- **Marker 渲染**：支持在文件中维护可编辑区域，工具与人类共同编辑\n- **Zod 验证**：所有输入通过 schema 验证，确保类型安全\n- **模块化检查**：Lint 规则以插件形式注册\n\n## 关键技术栈\n\n| 技术 | 用途 |\n|------|------|\n| TypeScript | 核心开发语言 |\n| Zod | 运行时 schema 验证 |\n| Node.js fs 模块 | 文件系统操作 |\n| MCP SDK | 模型上下文协议实现 |\n| Porter Stemmer | 全文搜索分词 |\n\n## 总结\n\nStoa 的系统架构体现了以下设计原则：\n\n1. **单一职责**：每个模块只负责一个明确的领域\n2. **数据与逻辑分离**：索引系统与业务逻辑解耦\n3. **可验证性**：通过 Zod schema 确保数据完整性\n4. **幂等性**：所有写操作均可安全重试\n5. **可观测性**：Lint 系统提供诊断能力\n\n整个系统以 vault 目录为数据源，通过 MCP STDIO 传输层对外提供服务，形成了完整的知识管理闭环。\n\n---\n\n\n\n## 传输层实现\n\n### 相关页面\n\n相关主题：[系统架构](#architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/transport/stdio.ts](https://github.com/BrettNye/stoa/blob/main/src/transport/stdio.ts)\n- [src/core/eventbus/state-cache.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/state-cache.ts)\n- [src/core/index.ts](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts)\n- [src/core/pages.ts](https://github.com/BrettNye/stoa/blob/main/src/core/pages.ts)\n \n\n# 传输层实现\n\n## 概述\n\nStoa 的传输层是 MCP（Model Context Protocol）服务器与外部客户端之间的通信桥梁，负责处理请求的接收、路由和响应返回。该层采用插件化架构，支持多种传输协议，当前实现包括 STDIO 标准输入输出传输和 HTTP 传输两种模式。\n\n传输层的核心职责：\n\n- 初始化并管理 MCP 服务器连接\n- 预热状态缓存以支持增量事件处理\n- 处理文件系统变化事件并维护索引一致性\n- 提供可插拔的传输适配器接口\n\n资料来源：[src/transport/stdio.ts:1-20]()\n\n## 架构设计\n\n### 传输类型概览\n\n| 传输类型 | 用途 | 特点 |\n|---------|------|------|\n| STDIO | 本地 CLI 集成 | 进程间通信，低延迟，适合桌面工具 |\n| HTTP | 远程服务 | 支持网络访问，适合服务器部署 |\n| UI Routes | Web 界面 | 提供读写路由的 HTTP 端点 |\n\n### 状态缓存机制\n\n传输层依赖 `StateCache` 类实现内存状态缓存，用于在处理文件系统变更事件时提供基准状态对比。\n\n```mermaid\ngraph TD\n A[文件系统变更] --> B{StateCache.has?}\n B -->|是| C[获取历史状态]\n B -->|否| D[返回 undefined]\n C --> E[计算差异]\n E --> F[触发增量更新]\n D --> G[处理初始事件]\n```\n\n**StateCache 关键方法：**\n\n| 方法 | 签名 | 说明 |\n|------|------|------|\n| get | `(source, wiki, id) => T \\| undefined` | 按复合键获取缓存状态 |\n| set | `(source, wiki, id, state) => void` | 存储状态到缓存 |\n| has | `(source, wiki, id) => boolean` | 检查键是否存在 |\n| size | `() => number` | 返回缓存条目总数 |\n\n复合键格式：`${source}:${wiki}:${id}`，确保不同来源、维基和页面的状态隔离。\n\n资料来源：[src/core/eventbus/state-cache.ts:1-30]()\n\n## STDIO 传输实现\n\n### 工作流程\n\nSTDIO 传输是 Stoa 的主要本地通信方式，通过标准输入/输出流与 MCP 客户端交互。\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Server as StdioServerTransport\n participant Cache as StateCache\n participant Vault as 文件系统\n\n Client->>Server: 连接建立\n Server->>Vault: walkInitablePaths()\n Server->>Cache: 预热缓存\n Note over Cache: 加载历史状态\n Client->>Server: 请求消息\n Server->>Cache: 查询/更新状态\n Server->>Client: 响应消息\n```\n\n### 缓存预热机制\n\n在接收实时事件前，传输层会遍历 `wikis/` 目录结构，将现有文件路径加载到状态缓存中，确保第一次变更事件有有效的基准状态可供对比。\n\n```typescript\nfunction walkInitablePaths(vaultPath: string): string[] {\n const root = join(vaultPath, \"wikis\");\n if (!existsSync(root)) return [];\n \n let entries: Array<{\n isFile(): boolean;\n name: string;\n parentPath?: string;\n path?: string;\n }>;\n \n entries = readdirSync(root, { recursive: true, withFileTypes: true });\n \n const paths: string[] = [];\n for (const e of entries) {\n if (!e.isFile()) continue;\n if (!e.name.endsWith(\".md\")) continue;\n // ... 收集有效路径\n }\n return paths;\n}\n```\n\n**预热流程说明：**\n\n1. 定位 `wikis/` 根目录\n2. 递归遍历目录结构获取所有条目\n3. 过滤仅保留 `.md` 扩展名文件\n4. 将有效路径存入缓存\n\n资料来源：[src/transport/stdio.ts:25-55]()\n\n### 类型兼容性处理\n\n代码对 Node.js v22 的类型定义进行了显式处理：\n\n```typescript\n// @types/node 22 声明 Dirent 作为默认值\n// 'name' 在运行时是字符串，但类型表现为 buffer-like\nlet entries: Array<{\n isFile(): boolean;\n name: string;\n parentPath?: string;\n path?: string;\n}>;\n\nentries = readdirSync(root, { recursive: true, withFileTypes: true }) \n as unknown as typeof entries;\n```\n\n此处的类型断言确保了运行时字符串类型与 TypeScript 类型定义的一致性。\n\n资料来源：[src/transport/stdio.ts:40-45]()\n\n## HTTP 传输\n\nHTTP 传输层通过 Web 服务器方式暴露 MCP 服务，支持远程客户端连接。该传输方式适用于将 Stoa 作为独立服务部署的场景。\n\n**HTTP 传输的核心能力：**\n\n- 接受外部 HTTP 请求\n- 路由到对应的工具处理器\n- 返回 JSON 格式响应\n\n> 注：详细 HTTP 传输实现请参考 `src/transport/http.ts`。\n\n## UI 路由层\n\nUI 路由层提供基于 HTTP 的读写接口，供 Web 前端或其他 HTTP 客户端使用。\n\n| 路由文件 | 职责 |\n|---------|------|\n| `routes-read.ts` | 页面读取操作 |\n| `routes-write.ts` | 页面写入操作 |\n| `index.ts` | 路由聚合与中间件 |\n\n> 注：详细路由实现请参考 `src/transport/ui/` 目录。\n\n## 页面路径解析\n\n传输层与核心页面模块协作，将页面 ID 解析为实际文件系统路径：\n\n```typescript\nexport function pathForPage(\n vaultPath: string, \n id: string, \n type: NoteType, \n wiki: string\n): string {\n // 特殊页面类型处理\n if (id === `map-${wiki}` || id === \"map\") {\n return join(vaultPath, \"wikis\", wiki, \"map.md\");\n }\n // 标准页面路径\n return join(vaultPath, \"wikis\", wiki, typeFolderForId(id), `${id}.md`);\n}\n```\n\n资料来源：[src/core/pages.ts:40-55]()\n\n## 索引与缓存协同\n\n传输层的事件处理依赖底层的写穿式索引更新机制：\n\n```mermaid\ngraph LR\n A[变更事件] --> B[upsertPage]\n B --> C[解析 frontmatter]\n C --> D[更新 pages.json]\n D --> E[更新 tokens.json]\n E --> F[StateCache 同步]\n```\n\n索引更新是原子操作，保证了在并发访问下的数据一致性。\n\n资料来源：[src/core/index.ts:80-100]()\n\n## 配置参数\n\n| 参数 | 来源 | 说明 |\n|------|------|------|\n| `vaultPath` | CLI `--vault=` 或 `STOA_VAULT_PATH` | 保险库根目录 |\n| `defaultWiki` | CLI `--default-wiki=` | 默认维基名称 |\n| `defaultFamily` | CLI `--default-family=` | 默认家族名称 |\n\n服务器启动时会输出配置确认信息到 stderr：\n\n```\nvault-mcp stdio server ready (vault=/path/to/vault, default-wiki=, default-family=)\n```\n\n资料来源：[src/transport/stdio.ts:20-25]()\n\n## 错误处理\n\n传输层的错误处理策略：\n\n| 场景 | 处理方式 |\n|------|---------|\n| 目录不存在 | 返回空数组 |\n| 读取失败 | 吞没异常并返回空结果 |\n| 文件损坏 | 交由调用方处理 |\n| 状态缓存未命中 | 返回 undefined |\n\n这种防御性编程确保了传输层在异常情况下的健壮性，不会因单个文件问题导致整个服务中断。\n\n## 扩展传输类型\n\nStoa 的传输层设计支持添加新的传输适配器。实现新传输类型的步骤：\n\n1. 实现传输类，实现 `connect` 方法\n2. 注册传输处理器到 MCP 服务器\n3. 在入口文件选择合适的传输类型\n4. 添加对应的启动日志输出\n\n当前支持的传输类型已覆盖本地集成（STDIO）和远程访问（HTTP）两种主要场景。\n\n---\n\n\n\n## 事件总线系统\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [召回与检索系统](#recall-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/eventbus/bus.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/bus.ts)\n- [src/core/eventbus/match.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/match.ts)\n- [src/core/eventbus/registry.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/registry.ts)\n- [src/core/eventbus/event-deriver.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/event-deriver.ts)\n- [src/core/eventbus/handle-wait.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/handle-wait.ts)\n- [src/core/eventbus/types.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/types.ts)\n- [src/core/eventbus/matchers/task.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/matchers/task.ts)\n \n\n# 事件总线系统\n\n## 概述\n\n事件总线系统是 stoa 项目的核心基础设施之一，提供基于文件系统观察的发布-订阅事件处理机制。该系统使 MCP 工具能够以**阻塞等待**（push 原语）而非轮询的方式响应 vault 中的文件变更，实现了实时事件驱动的工具调用模式。\n\n事件总线在以下场景中发挥关键作用：\n\n- 任务状态变更检测（status/owner 变化）\n- wiki 内容变更监听\n- 通道（channel）消息通知\n- 跨实例协调通信\n\n资料来源：[src/core/eventbus/types.ts]()\n\n## 核心架构\n\n### 模块结构\n\n事件总线系统由以下子模块组成：\n\n| 模块 | 文件 | 职责 |\n|------|------|------|\n| 类型定义 | `types.ts` | 定义 `VaultEvent`、`VaultEventFilter`、事件派生器接口 |\n| 事件总线 | `bus.ts` | 核心事件发布-订阅引擎，文件系统监视器集成 |\n| 匹配器 | `match.ts` | 过滤器匹配逻辑，实现事件筛选条件 |\n| 注册表 | `registry.ts` | 管理事件监听器订阅和取消订阅 |\n| 事件派生器 | `event-deriver.ts` | 从原始文件事件派生语义化 vault 事件 |\n| 等待处理 | `handle-wait.ts` | 实现 `wait-for` 系列阻塞原语 |\n| 内置匹配器 | `matchers/task.ts` | 任务状态变更检测匹配器 |\n\n```mermaid\ngraph TD\n subgraph \"文件系统层\"\n FS[文件系统观察者]\n end\n \n subgraph \"事件总线核心\"\n EB[EventBus]\n REG[Registry]\n DER[EventDeriver]\n MATCH[Matcher]\n end\n \n subgraph \"等待原语\"\n WF[wait-for]\n WFA[wait-for-any]\n WFL[wait-for-all]\n WFM[wait-for-many]\n end\n \n FS -->|原始文件变更| EB\n EB --> REG\n EB --> DER\n DER --> MATCH\n MATCH -->|过滤后事件| WF\n MATCH -->|过滤后事件| WFA\n MATCH -->|过滤后事件| WFL\n MATCH -->|过滤后事件| WFM\n \n REG -->|订阅管理| EB\n```\n\n资料\nError with Openai API: output new_sensitive (1027)\n\nPlease check that you have set the OPENAI_API_KEY environment variable with a valid API key.\n\n---\n\n\n\n## 召回与检索系统\n\n### 相关页面\n\n相关主题：[Wiki管理](#wiki-management), [事件总线系统](#eventbus)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/index.ts](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts) - 页面索引与查询核心逻辑\n- [src/core/claim-render.ts](https://github.com/BrettNye/stoa/blob/main/src/core/claim-render.ts) - Claims 渲染与排序\n- [src/core/synthesize.ts](https://github.com/BrettNye/stoa/blob/main/src/core/synthesize.ts) - 综合页面合成\n- [src/core/syntheses.ts](https://github.com/BrettNye/stoa/blob/main/src/core/syntheses.ts) - 综合页面状态管理\n- [src/core/channel.ts](https://github.com/BrettNye/stoa/blob/main/src/core/channel.ts) - 频道摘要与查询\n\n> ⚠️ 以下文件在请求上下文中不可用，无法纳入本文档：\n> - `src/core/recall.ts`\n> - `src/core/claims-index.ts`\n> - `src/core/recall-filter.ts`\n> - `src/tools/recall.ts`\n> - `src/tools/read.ts`\n \n\n# 召回与检索系统\n\n## 概述\n\n召回与检索系统是 stoa 知识库系统的核心基础设施，负责从结构化索引中高效定位符合查询条件的页面、Claims 和综合文档。该系统采用**写穿透（Write-Through）索引更新**策略，确保索引数据与文件系统保持同步，同时将完整性检查（目标页面是否存在、Wiki 是否存在）的职责委托给上层消费者。\n\n核心设计原则：\n\n- **单一职责**：召回模块仅负责提取结构化链接引用，不进行完整性验证 资料来源：[src/core/wikilinks.ts:11-12](https://github.com/BrettNye/stoa/blob/main/src/core/wikilinks.ts#L11-L12)\n- **幂等性**：重新渲染相同输入产生字节级相同的输出 资料来源：[src/core/marker-render.ts:19-21](https://github.com/BrettNye/stoa/blob/main/src/core/marker-render.ts#L19-L21)\n- **分层架构**：索引管理层与工具层分离，索引层负责数据持久化，工具层负责业务逻辑编排\n\n## 核心数据模型\n\n### 索引页面结构（IndexedPage）\n\n```typescript\ninterface IndexedPage {\n id: string;\n wiki: string;\n type: string;\n path?: string;\n channel?: string;\n status?: string;\n title?: string;\n tags?: string[];\n created?: string; // ISO日期 YYYY-MM-DD\n updated?: string; // ISO日期 YYYY-MM-DD\n last_validated?: string;\n confidence?: Confidence;\n authored_by?: string;\n}\n```\n\n### VaultIndex 主索引结构\n\n```typescript\ninterface VaultIndex {\n pages: IndexedPage[];\n wikis: IndexedWiki[];\n profiles: IndexedProfile[];\n links: LinkEdge[];\n tokens: TokenIndex;\n}\n```\n\n## 页面查询系统\n\n### queryPages 函数\n\n`queryPages` 是页面查询的核心入口，支持多维度过滤 资料来源：[src/core/index.ts:40-52](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts#L40-L52)：\n\n```typescript\nexport function queryPages(idx: VaultIndex, f: PageFilter): IndexedPage[] {\n return idx.pages.filter(p => {\n if (f.wiki && wikiSet && !wikiSet.has(p.wiki)) return false;\n if (f.type && p.type !== f.type) return false;\n if (f.channel && p.channel !== f.channel) return false;\n if (f.status && p.status !== f.status) return false;\n if (f.layer && f.layer !== \"all\") {\n const set = f.layer === \"knowledge\" ? KNOWLEDGE_TYPES : EXECUTION_TYPES;\n if (!set.includes(p.type)) return false;\n }\n return true;\n });\n}\n```\n\n### 查询过滤器参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `wiki` | `string \\| undefined` | 按 Wiki 名称过滤 |\n| `type` | `string \\| undefined` | 按页面类型过滤 |\n| `channel` | `string \\| undefined` | 按协调频道过滤 |\n| `status` | `string \\| undefined` | 按状态过滤（draft/active/accepted 等） |\n| `layer` | `\"knowledge\" \\| \"execution\" \\| \"all\" \\| undefined` | 按知识层过滤 |\n| `id` | `string \\| undefined` | 按页面 ID 精确匹配 |\n\n### 页面类型分层\n\n系统将页面类型划分为两个知识层：\n\n| 知识层 | 包含类型 | 说明 |\n|--------|----------|------|\n| `KNOWLEDGE_TYPES` | concept, decision, spec, process, capability, domain, support | 持久化、可蒸馏的知识 |\n| `EXECUTION_TYPES` | guide, source, idea, question | 执行层面的文档 |\n\n> 注意：`guide`、`source`、`idea`、`question` 被排除在知识层之外，因为它们是程序性或外部引用性质，不符合\"持久化、可蒸馏\"知识的标准 资料来源：[src/core/lint-checks/synthesis-debt.ts:26-34](https://github.com/BrettNye/stoa/blob/main/src/core/lint-checks/synthesis-debt.ts#L26-L34)\n\n## 索引更新机制\n\n### 写穿透索引（Write-Through Index）\n\n`upsertPage` 函数负责单页面的索引更新：\n\n```typescript\nexport function upsertPage(pagePath: string): void {\n // 读取文件 → 解析 frontmatter → 更新 pages.json 和 tokens.json\n // 注意：不重新生成 links.json, wikis.json, profiles.json\n}\n```\n\n该函数执行以下操作：\n\n1. 读取页面文件内容\n2. 解析 frontmatter 元数据\n3. 向 `_index/pages.json` 添加/替换条目\n4. 向 `_index/tokens.json` 添加分词数据\n5. **不重新生成** `_index/{links,wikis,profiles}.json`（这些是聚合文件）\n\n> 聚合索引文件的重新生成由 `vault.reindex` 工具单独处理 资料来源：[src/core/index.ts:78-82](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts#L78-L82)\n\n### 分词与停用词过滤\n\n```typescript\nconst UPSERT_STOP_WORDS = new Set([\n \"the\",\"and\",\"of\",\"a\",\"an\",\"in\",\"to\",\"is\",\"for\",\"on\",\"with\",\"as\",\"at\",\"by\",\"or\",\"be\",\n \"this\",\"that\",\"it\",\"from\",\"are\",\"was\",\"were\",\"not\",\"but\",\"if\"\n]);\n\nfunction upsertTokenize(text: string): string[] {\n return text.toLowerCase()\n .replace(/[^a-z0-9\\s]/g, \" \")\n .split(/\\s+/)\n .filter(t => t.length > 1 && !UPSERT_STOP_WORDS.has(t))\n .map(t => upsertStemmer.stem(t)); // 使用 Porter Stemmer\n}\n```\n\n| 处理步骤 | 说明 |\n|----------|------|\n| 转小写 | 统一大小写 |\n| 去除非字母数字字符 | 保留单词边界 |\n| 停用词过滤 | 移除高频无意义词 |\n| Porter 词干提取 | 词形归一化 |\n\n## Claims 检索与排序\n\n### 有效置信度计算\n\nClaims 采用**半衰期衰减模型**计算有效置信度 资料来源：[src/core/claim-render.ts:52-62](https://github.com/BrettNye/stoa/blob/main/src/core/claim-render.ts#L52-L62)：\n\n```typescript\nfunction effectiveConfidence(\n claim: { confidence: Confidence; last_validated?: string; status?: string },\n today: Date,\n config: ClaimsConfig,\n): number {\n const base = BASE_CONFIDENCE[claim.confidence ?? \"medium\"];\n const ageMs = today.getTime() - new Date(claim.last_validated ?? today).getTime();\n const halfLives = ageMs / MS_PER_DAY / config.half_life_days;\n const decayed = base * Math.pow(0.5, halfLives);\n const eff = Math.max(decayed, config.effective_floor);\n \n // 被撤回的 Claims 有效置信度归零\n if (claim.status === \"retracted\") return 0;\n \n return eff;\n}\n```\n\n### 置信度基础值\n\n| 置信度级别 | 基础值 | 半衰期衰减后最小值 |\n|------------|--------|-------------------|\n| `high` | 0.9 | 由 `effective_floor` 决定 |\n| `medium` | 0.6 | 由 `effective_floor` 决定 |\n| `low` | 0.3 | 由 `effective_floor` 决定 |\n\n### Claims 排序策略\n\n排序得分公式：\n\n```\nscore(claim) = effective_confidence + (profile_match ? 0.1 : 0)\n```\n\n| 排序因素 | 说明 |\n|----------|------|\n| 有效置信度 | 半衰期衰减后的当前置信度 |\n| Profile 加成 | 当部署 Profile ID 在 claim 的 profile 数组中时加 0.1 |\n\n## 综合文档检索\n\n### 综合文档查询\n\n`syntheses.ts` 提供综合文档的查询与陈旧度分析 资料来源：[src/core/syntheses.ts:40-75](https://github.com/BrettNye/stoa/blob/main/src/core/syntheses.ts#L40-L75)：\n\n```typescript\n// 过滤出 synthesis 类型的页面\nconst syntheses = allPages.filter(p => {\n if (p.type !== \"synthesis\") return false;\n if (opts.wiki && p.wiki !== opts.wiki) return false;\n return true;\n});\n\n// 从文件 frontmatter 读取 last_compiled\nif (synthPath && existsSync(synthPath)) {\n const raw = readFileSync(synthPath, \"utf8\");\n const { frontmatter } = parseFrontmatter(raw);\n const rawLc = frontmatter.last_compiled;\n // 计算距今天数\n lagDays = Math.floor((now - compiledMs) / MS_PER_DAY);\n}\n```\n\n### 综合文档陈旧度指标\n\n| 指标 | 说明 |\n|------|------|\n| `last_compiled` | 上次编译日期，来自 frontmatter |\n| `lag_days` | 距今天数 |\n| `staleness` | 可配置的陈旧度阈值（默认 30 天） |\n\n## 频道摘要检索\n\n`channel.ts` 提供协调频道的实时摘要 资料来源：[src/core/channel.ts:24-45](https://github.com/BrettNye/stoa/blob/main/src/core/channel.ts#L24-L45)：\n\n```typescript\nexport function channelTail(vaultPath: string, opts: ChannelTailOptions): ChannelSummary[] {\n // 查询所有 journal 类型页面\n const pages = queryPages(idx, { type: \"journal\", wiki: opts.wiki });\n \n // 按 wiki::channel 聚合\n const byKey = new Map();\n for (const p of pages) {\n const key = `${p.wiki}::${p.channel}`;\n // 统计 24 小时内的条目数\n if (p.created >= sinceIso) summary.count24h++;\n // 记录最新条目\n if (!summary.lastEntry || p.created > summary.lastEntry.ts) {\n // 读取文件获取摘要和作者\n excerpt = body.trim().slice(0, 240);\n author = String(fm.author ?? \"unknown\");\n }\n }\n}\n```\n\n### 频道摘要数据结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `name` | `string` | 频道名称 |\n| `wiki` | `string` | 所属 Wiki |\n| `count24h` | `number` | 24 小时内条目数 |\n| `lastEntry` | `ChannelEntry \\| null` | 最新条目详情 |\n\n## 检索流程图\n\n```mermaid\ngraph TD\n A[用户查询请求] --> B{查询类型}\n B -->|页面查询| C[queryPages]\n B -->|Claims 查询| D[查询 + 置信度计算]\n B -->|综合文档| E[过滤 synthesis 类型]\n B -->|频道摘要| F[channelTail 聚合]\n \n C --> G[应用过滤器]\n D --> H[计算 effective_confidence]\n E --> I[读取 last_compiled]\n F --> J[统计 count24h]\n \n G --> K[返回 IndexedPage[]]\n H --> L[按 score 排序]\n I --> M[计算 lag_days]\n J --> N[返回 ChannelSummary[]]\n \n L --> O[返回排序后 Claims]\n M --> P[返回 SynthesisStaleness[]]\n```\n\n## 架构设计要点\n\n### 索引与文件系统同步\n\n| 操作 | 索引更新范围 |\n|------|--------------|\n| `upsertPage` | `pages.json` + `tokens.json` |\n| `vault.reindex` | 全部索引文件 |\n| 文件删除 | 需手动触发重建 |\n\n### Wiki 解析器\n\n```typescript\nexport function queryWikis(idx: VaultIndex): IndexedWiki[] {\n return idx.wikis;\n}\n```\n\n### 过滤器组合\n\n页面过滤器支持**多维度组合过滤**，各维度之间为 AND 关系：\n\n```mermaid\ngraph LR\n A[Wiki 过滤] -->|AND| Z[最终结果]\n B[Type 过滤] -->|AND| Z\n C[Channel 过滤] -->|AND| Z\n D[Status 过滤] -->|AND| Z\n E[Layer 过滤] -->|AND| Z\n```\n\n## 配置参数\n\n### Claims 渲染配置\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `half_life_days` | `number` | 30 | 置信度半衰期（天） |\n| `effective_floor` | `number` | 0.1 | 有效置信度下限 |\n\n### 综合文档配置\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `min_lag_days` | `number \\| null` | null | 最小陈旧天数阈值 |\n| `stale_after_days` | `number` | 30 | 标记为陈旧的天数 |\n\n## 相关工具\n\n| 工具名称 | 功能 |\n|----------|------|\n| `vault.reindex` | 重新生成全部索引文件 |\n| `vault.synthesize` | 编译或刷新综合页面 |\n| `vault.channel-tail` | 拉取协调频道的最新条目 |\n| `vault.recall` | 根据条件召回相关页面 |\n\n---\n\n*本文档基于 stoa 仓库的可用源码生成。部分检索系统核心文件（`recall.ts`、`claims-index.ts` 等）在当前上下文不可用，完整功能描述需待源码补充后更新。*\n\n---\n\n\n\n## Wiki管理\n\n### 相关页面\n\n相关主题：[召回与检索系统](#recall-system), [核心概念](#concepts)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/wikis.ts](https://github.com/BrettNye/stoa/blob/main/src/core/wikis.ts)\n- [src/core/frontmatter.ts](https://github.com/BrettNye/stoa/blob/main/src/core/frontmatter.ts)\n- [src/core/wikilinks.ts](https://github.com/BrettNye/stoa/blob/main/src/core/wikilinks.ts)\n- [src/core/synthesize.ts](https://github.com/BrettNye/stoa/blob/main/src/core/synthesize.ts)\n- [src/tools/new-wiki.ts](https://github.com/BrettNye/stoa/blob/main/src/tools/new-wiki.ts)\n- [src/tools/set-active.ts](https://github.com/BrettNye/stoa/blob/main/src/tools/set-active.ts)\n- [src/tools/synthesize.ts](https://github.com/BrettNye/stoa/blob/main/src/tools/synthesize.ts)\n \n\n# Wiki管理\n\n## 概述\n\nWiki管理是Stoa系统的核心功能之一，负责管理知识库中的wiki空间、页面组织、链接解析以及内容综合。Stoa采用vault-root结构，所有wiki内容位于`wikis/`目录下，每个wiki是独立的内容空间，支持多wiki架构和跨wiki引用。\n\nWiki管理的核心职责包括：\n\n- 创建和配置新的wiki\n- 管理wiki的活动状态和默认上下文\n- 解析和验证wiki间的链接关系\n- 驱动内容综合（synthesis）机制\n- 维护wiki索引和元数据\n\n资料来源：[README.md]()\n\n---\n\n## Wiki核心概念\n\n### 架构分层\n\nStoa的知识库采用分层架构：\n\n```mermaid\ngraph TD\n A[\"vault root\"] --> B[\"wikis/\"]\n B --> C[\"/\"]\n C --> D[\"concept/\"]\n C --> E[\"decision/\"]\n C --> E2[\"source/\"]\n C --> E3[\"guide/\"]\n C --> E4[\"journal/\"]\n C --> E5[\"claim/\"]\n C --> E6[\"synthesis/\"]\n C --> E7[\"move/\"]\n C --> F[\"map.md\"]\n C --> G[\"index.md\"]\n C --> H[\"_meta/\"]\n```\n\n每个wiki包含多种页面类型，每种类型对应不同的知识处理模式。\n\n### 页面类型体系\n\n| 类型 | 说明 | 文件命名规则 |\n|------|------|-------------|\n| `concept` | 概念页面 | `concept-.md` |\n| `decision` | 决策记录 | `decision-YYYY-MM-DD-.md` |\n| `source` | 外部引用 | `source-.md` |\n| `guide` | 操作指南 | `guide-.md` |\n| `journal` | 日志条目 | `journal-YYYY-MM-DD-HHMM-.md` |\n| `claim` | 断言声明 | `claim-.md` |\n| `synthesis` | 综合页面 | `synthesis-.md` |\n| `move` | 技能移动 | `move-/SKILL.md` |\n| `map` | 地图页面 | `map.md` |\n\n资料来源：[src/core/ids.ts]()\n\n---\n\n## Wiki创建与初始化\n\n### newWiki函数\n\n`newWiki`函数负责在vault中创建新的wiki空间，包含完整的目录结构和初始配置文件。\n\n```typescript\nfunction newWiki(\n vaultPath: string,\n opts: NewWikiOptions\n): NewWikiResult\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `vaultPath` | `string` | 是 | vault根目录路径 |\n| `opts.name` | `string` | 是 | wiki名称 |\n| `opts.mode` | `WikiMode` | 是 | wiki模式：idea-map、project-doc、learning、mixed |\n| `opts.scope` | `string` | 是 | wiki作用域描述 |\n\n**返回值：**\n\n```typescript\ninterface NewWikiResult {\n name: string;\n path: string;\n files_created: string[];\n}\n```\n\n创建过程中会生成以下基础文件：\n\n- `wikis//map.md` — wiki导航地图\n- `wikis//index.md` — wiki首页\n- `wikis//CLAUDE.md` — wiki级别的AI上下文配置\n- `wikis//_meta/` — 元数据目录\n\n资料来源：[src/tools/new-wiki.ts]()\n\n### Wiki模式\n\nWiki支持四种创建模式，每种模式预设不同的内容结构和初始标签：\n\n| 模式 | 用途 | 典型内容 |\n|------|------|---------|\n| `idea-map` | 头脑风暴和概念映射 | 大量concept页面 |\n| `project-doc` | 项目文档管理 | guide、decision为主 |\n| `learning` | 学习和知识积累 | source、concept交替 |\n| `mixed` | 混合用途 | 均衡各类内容 |\n\n资料来源：[src/core/wikis.ts]()\n\n---\n\n## 活动Wiki管理\n\n### setActiveWiki机制\n\n系统维护一个\"活动wiki\"的概念，作为命令执行的默认上下文。活动wiki的解析遵循优先级链：\n\n```mermaid\ngraph LR\n A[\"explicit wikiArg\"] --> B{\"已知wiki?\"}\n B -->|是| C[\"返回wikiArg\"]\n B -->|否| D[\"抛出错误\"]\n E[\"无explicit参数\"] --> F{\".active-family文件?\"}\n F -->|存在| G[\"读取文件内容\"]\n F -->|不存在| H[\"CLI --default-family\"]\n H --> I{\".active-family文件?\"}\n I -->|存在| J[\"读取文件内容\"]\n I -->|不存在| K[\"返回null - 单wiki解析\"]\n```\n\n**解析优先级（高到低）：**\n\n1. 显式传入的`wikiArg`参数\n2. `ctx.defaultFamily` — CLI的`--default-family`参数\n3. `/.active-family`文件内容\n4. `null` — 回退到单wiki解析模式\n\n资料来源：[src/core/family.ts]()\n\n### FamilyMismatchError\n\n当显式传入的`family`和`wiki`参数不匹配时，系统抛出结构化错误：\n\n```typescript\nthrow new FamilyMismatchError(\n `wiki '${wikiArg}' has family '${wikiFamily ?? \"(none)\"}' which does not match requested family '${familyArg}'`\n);\n```\n\n这确保了多family场景下参数的一致性，防止静默的错误路由。\n\n资料来源：[src/core/family.ts]()\n\n---\n\n## Wikilink链接系统\n\n### 链接格式规范\n\nStoa使用`[[wikilink]]`语法进行wiki内和跨wiki引用。链接格式支持以下变体：\n\n```\n[[wikis///]]\n[[wikis///|alias]]\n```\n\n**绝对形式（vault-root）：**\n```\n[[wikis/brett/concept/my-page]]\n[[wikis/brett/concept/my-page|显示别名]]\n```\n\n资料来源：[src/core/wikilinks.ts]()\n\n### WikilinkRef数据结构\n\n```typescript\nexport interface WikilinkRef {\n raw: string; // 原始链接文本\n wiki: string; // 目标wiki名称\n type: string; // 页面类型\n id: string; // 页面ID\n alias?: string; // 可选的显示别名\n source: \"body\" | \"frontmatter\"; // 链接来源位置\n}\n```\n\n资料来源：[src/core/wikilinks.ts]()\n\n### 链接提取规则\n\nWikilink提取器`extractWikilinks`具有以下行为特征：\n\n| 特性 | 说明 |\n|------|------|\n| 代码块感知 | 顶层\\`\\`\\`代码块内的链接被跳过 |\n| 行首要求 | 代码块标记必须在一行的开头 |\n| 内联代码 | 单反引号\\`包裹的文本中的链接**不**被过滤 |\n| 嵌套代码块 | 缩进内的代码块（如列表项内4空格缩进）**不**被处理 |\n\n```typescript\n// 示例：以下内容中\n```\n[[wikis/brett/concept/inside-code]]\n```\n这里 [[wikis/brett/concept/outside-code]] 会提取\n\n// 提取结果：只包含 outside-code\n```\n\n资料来源：[src/core/wikilinks.ts]()\n\n---\n\n## 内容综合（Synthesis）\n\n### Synthesis机制概述\n\nSynthesis是Stoa的核心知识整合功能，用于将多个相关页面综合成一篇聚合文档。综合页面维护一个managed region，由marker边界限定。\n\n```mermaid\ngraph TD\n A[\"输入：话题或agent\"] --> B[\"查询匹配页面\"]\n B --> C{\"by_agent?\"}\n C -->|是| D[\"过滤到特定agent\"]\n C -->|否| E[\"按话题检索\"]\n D --> F[\"生成Synthesis页面\"]\n E --> F\n F --> G[\"写入marker区域\"]\n G --> H[\"更新_index/syntheses.json\"]\n```\n\n### Marker区域管理\n\nMarker区域由HTML注释界定，支持幂等渲染：\n\n```html\n\n## 来源\n\n- [[wikis/brett/concept/page-a]]\n- [[wikis/brett/concept/page-b]]\n\n```\n\n**Marker选项：**\n\n| 选项 | 说明 |\n|------|------|\n| `renderedDate` | ISO日期YYYY-MM-DD，渲染时间戳 |\n| `halfLifeDays` | 半衰期天数，用于缓存策略 |\n\n重新渲染相同输入产生字节级一致输出，不同markerName的区域互不干扰。\n\n资料来源：[src/core/marker-render.ts]()\n\n### SynthesisFrontmatter\n\n综合页面生成的frontmatter结构：\n\n```typescript\nconst fm = {\n id, // 唯一标识符\n title, // 标题\n type: \"synthesis\", // 固定类型\n wiki, // 所属wiki\n status: \"draft\", // 初始状态\n created: today,\n updated: today,\n summary, // 综合说明\n tags, // 标签数组\n last_compiled: today, // 最后编译时间\n sources: [...] // 来源页面wikilinks数组\n};\n```\n\n对于agent memory类型的综合，还会包含`by_agent`和`scope: \"memory\"`字段。\n\n资料来源：[src/core/synthesize.ts]()\n\n---\n\n## 索引与查询\n\n### VaultIndex结构\n\nVault维护统一的索引结构支持高效查询：\n\n```typescript\nexport interface VaultIndex {\n pages: IndexedPage[];\n wikis: IndexedWiki[];\n profiles: IndexedProfile[];\n tokens: Record;\n links: Record;\n}\n```\n\n### Wiki查询\n\n```typescript\nexport function queryWikis(idx: VaultIndex): IndexedWiki[]\n```\n\n返回所有已索引的wiki列表，每个IndexedWiki包含名称、路径、family归属等信息。\n\n资料来源：[src/core/index.ts]()\n\n---\n\n## 工具命令参考\n\n### vault.new-wiki\n\n```bash\nvault new-wiki --mode --scope \n```\n\n**参数：**\n\n| 参数 | 说明 |\n|------|------|\n| `name` | wiki名称 |\n| `--mode` | 必须：idea-map\\|project-doc\\|learning\\|mixed |\n| `--scope` | 必须：作用域描述 |\n\n**输出示例：**\n```\ncreated wiki: mywiki at wikis/mywiki (7 files)\n```\n\n资料来源：[src/cli/commands/new-wiki.ts]()\n\n### vault.synthesize\n\n创建或刷新综合页面：\n\n```bash\nvault synthesize --topic --wiki [--by_agent ]\n```\n\n**参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `--topic` | string | 综合主题 |\n| `--wiki` | string | 目标wiki |\n| `--by_agent` | string | 可选：按agent过滤 |\n| `--limit` | number | 候选页面数量限制（默认25） |\n\n资料来源：[src/tools/synthesize.ts]()\n\n### vault.set-active\n\n设置当前活动的wiki上下文：\n\n```bash\nvault set-active \n```\n\n该命令更新`.active-family`文件，后续命令默认使用该wiki作为上下文。\n\n资料来源：[src/tools/set-active.ts]()\n\n---\n\n## 跨Wiki协作\n\n### Family机制\n\nFamily是一组相关wiki的逻辑分组，支持跨wiki内容发现：\n\n```typescript\nexport interface FamilyRollup {\n members: string[]; // wiki成员列表（已排序）\n total_pages: number; // 总页面数\n modes_used: string[]; // 使用的模式类型（去重+排序）\n}\n```\n\n### 频道系统\n\nWiki支持通过频道进行协调通信：\n\n```typescript\ninterface ChannelSummary {\n name: string;\n wiki: string;\n lastEntry: ChannelEntry | null;\n count24h: number; // 24小时内的条目数\n}\n```\n\n`vault.channel-tail`命令可拉取最近频道条目，`vault.channel-post`用于发布到频道。\n\n资料来源：[src/core/channel.ts]()\n\n---\n\n## 最佳实践\n\n### Wiki创建建议\n\n1. **选择合适的模式** — 根据内容性质选择`idea-map`、`project-doc`等模式\n2. **设置清晰的scope** — scope描述帮助系统理解wiki的职责边界\n3. **配置CLAUDE.md** — 在wiki根目录配置AI上下文，指导知识管理行为\n\n### 链接使用规范\n\n1. **优先使用绝对形式** — `[[wikis/wiki/type/id]]`形式跨上下文可移植\n2. **避免代码块内链接** — 顶层代码块中的wikilink不会被解析\n3. **使用alias增强可读性** — `[[target|描述文本]]`提供语义化展示\n\n### Synthesis维护\n\n1. **定期刷新** — 综合页面会记录`last_compiled`，建议周期性刷新以纳入新内容\n2. **利用半衰期** — 设置合理的`halfLifeDays`平衡新鲜度和稳定性\n3. **保护marker区域** — 手动编辑时避免修改marker注释边界\n\n---\n\n## 相关文档\n\n- [页面管理](./页面管理.md)\n- [链接系统](./链接系统.md)\n- [Family机制](./Family机制.md)\n- [Synthesis系统](./Synthesis系统.md)\n\n---\n\n\n\n## 任务协作系统\n\n### 相关页面\n\n相关主题：[事件总线系统](#eventbus)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/channel.ts](https://github.com/BrettNye/stoa/blob/main/src/core/channel.ts)\n- [src/core/frontmatter.ts](https://github.com/BrettNye/stoa/blob/main/src/core/frontmatter.ts)\n- [src/core/lint-checks/synthesis-debt.ts](https://github.com/BrettNye/stoa/blob/main/src/core/lint-checks/synthesis-debt.ts)\n- [src/core/index.ts](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts)\n- [src/core/pages.ts](https://github.com/BrettNye/stoa/blob/main/src/core/pages.ts)\n\n> **注意**：以下源码文件在查询范围内但未出现在当前上下文片段中：\n> - `src/core/tasks.ts`\n> - `src/core/inbox.ts`\n> - `src/core/sync-enumerate.ts`\n> - `src/tools/task-claim.ts`\n> - `src/tools/channel-post.ts`\n> - `src/tools/process-inbox.ts`\n>\n> 本页基于现有上下文片段构建，部分系统细节可能需要补充。\n\n \n\n# 任务协作系统\n\n## 概述\n\n任务协作系统是 Stoa 知识管理平台的核心子系统之一，负责管理任务（task）类型页面的生命周期、任务分发与认领、以及通过 Channel 机制实现跨智能体（agent）的任务协调。\n\n系统的设计目标包括：\n\n1. **结构化任务管理**：通过标准化的 frontmatter schema 定义任务元数据，确保任务状态、优先级和归属的完整性\n2. **智能体协调**：支持通过 Channel 进行任务公告和认领，实现多智能体环境下的工作分配\n3. **状态追踪**：提供任务状态流转的完整生命周期管理，从草稿（draft）到归档（archived）\n4. **索引与查询**：基于 VaultIndex 的全文检索能力，支持按类型、wiki、状态等维度查询任务\n\n资料来源：[src/core/frontmatter.ts:1-50]()\n\n## 核心数据模型\n\n### 页面类型体系\n\nStoa 采用统一的页面类型系统，任务（task）是其中一种核心类型。系统定义了以下类型常量用于过滤和分类：\n\n```typescript\n// 知识类型（硬知识，可合成）\nconst KNOWLEDGE_TYPES = [\"concept\", \"decision\", \"spec\", \"source\"];\n\n// 执行类型（过程性知识）\nconst EXECUTION_TYPES = [\"guide\", \"idea\", \"question\", \"task\", \"move\"];\n```\n\n资料来源：[src/core/index.ts:1-30]()\n\n### 页面状态枚举\n\n任务页面使用统一的 PageStatus 枚举定义状态：\n\n| 状态值 | 含义 | 使用场景 |\n|--------|------|----------|\n| `draft` | 草稿 | 任务刚创建，尚未激活 |\n| `active` | 活跃 | 任务正在执行中 |\n| `accepted` | 已接受 | 任务已被认领并确认 |\n| `superseded` | 已替代 | 任务已被新任务替代 |\n| `archived` | 已归档 | 任务完成或放弃后归档 |\n\n资料来源：[src/core/frontmatter.ts:15-17]()\n\n### Inbox 项结构\n\nInbox（收件箱）是任务分发的基础机制。系统通过解析 frontmatter 中的特定字段将页面路由到相应的 Inbox：\n\n```typescript\nexport interface InboxEntry {\n id: string;\n wiki: string;\n path: string;\n title: string;\n type: NoteType;\n updated: string;\n created: string;\n}\n```\n\n资料来源：[src/core/pages.ts:1-50]()\n\n## Channel 协作机制\n\nChannel 是 Stoa 中实现任务公告和实时协作的核心组件。它本质上是一个命名频道，用于：\n\n1. **任务公告**：将新任务发布到特定频道\n2. **认领机制**：智能体通过 Channel 认领分配给它的任务\n3. **活动聚合**：按频道聚合 24 小时内的活动摘要\n\n### Channel 摘要结构\n\n```typescript\nexport interface ChannelSummary {\n name: string; // 频道名称（kebab-case）\n wiki: string; // 所属 wiki\n lastEntry: EntryInfo | null; // 最新条目\n count24h: number; // 24小时内条目数\n}\n```\n\n资料来源：[src/core/channel.ts:1-30]()\n\n### Channel 聚合逻辑\n\n系统通过以下流程聚合 Channel 摘要：\n\n```mermaid\ngraph TD\n A[查询所有 journal 类型页面] --> B[按 channel 分组]\n B --> C{是否超过 24 小时?}\n C -->|是| D[跳过计数]\n C -->|否| E[count24h++]\n E --> F[更新 lastEntry]\n D --> G[返回排序后的 ChannelSummary 列表]\n E --> G\n```\n\n处理逻辑的核心代码：\n\n```typescript\nfor (const p of pages) {\n const channel = p.channel;\n if (typeof channel !== \"string\" || !channel) continue;\n const key = `${p.wiki}::${channel}`;\n if (p.created >= sinceIso) summary.count24h++;\n if (!summary.lastEntry || p.created > summary.lastEntry.ts) {\n // 读取文件获取 author 和 body excerpt\n summary.lastEntry = {\n id: p.id,\n channel,\n wiki: p.wiki,\n author: String(fm.author ?? \"unknown\"),\n ts: p.created,\n excerpt,\n pageId: p.id,\n };\n }\n}\n```\n\n资料来源：[src/core/channel.ts:30-60]()\n\n## 任务生命周期管理\n\n### 任务创建\n\n任务通过 `writePage` 函数创建，系统自动处理：\n\n1. 生成规范的文件路径：`tasks/.md`\n2. 解析并验证 frontmatter\n3. 写入文件系统并更新索引\n\n```typescript\nexport interface WritePageInput {\n id: string;\n type: NoteType;\n wiki: string;\n frontmatter: Record;\n body: string;\n expectedUpdated?: string;\n}\n```\n\n资料来源：[src/core/pages.ts:60-80]()\n\n### 任务路径映射\n\n系统使用 `pathForPage` 函数将页面 ID 映射到文件系统路径：\n\n```typescript\n// 任务类型路径格式\npath = join(vaultPath, \"wikis\", wiki, \"tasks\", `${id}.md`);\n```\n\n资料来源：[src/core/pages.ts:20-40]()\n\n## 智能体协作工作流\n\n### 任务分发流程\n\n```mermaid\ngraph LR\n A[任务创建] --> B[写入 tasks 目录]\n B --> C[更新 VaultIndex]\n C --> D[Channel 公告]\n D --> E[智能体感知]\n E --> F[任务认领]\n F --> G[状态更新为 accepted]\n```\n\n### 硬知识类型判定\n\n在协作系统中，系统需要区分\"硬知识\"（可合成的知识资产）和\"执行型\"知识。任务属于 `EXECUTION_TYPES`：\n\n```typescript\nconst HARD_KNOWLEDGE_TYPES = new Set([\"concept\", \"decision\", \"spec\", \"source\"]);\n\n// 任务不属于硬知识，不参与合成债务检测\nconst type = String(page.type);\nif (HARD_KNOWLEDGE_TYPES.has(type)) {\n // 参与合成债务检测\n}\n```\n\n资料来源：[src/core/lint-checks/synthesis-debt.ts:40-60]()\n\n## Channel 名称规范\n\nChannel 名称必须符合 kebab-case 格式，lint 检查会验证格式：\n\n| 规则 | 正则表达式 | 示例 |\n|------|------------|------|\n| 有效格式 | `^[a-z0-9]+(-[a-z0-9]+)*$` | `feature-x`, `bug-fix` |\n| 无效格式 | 包含大写或特殊字符 | `myChannel`, `feature_x` |\n\n```typescript\n// Lint 检查代码\nif (p.channel && !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(p.channel)) {\n diagnostics.push({\n severity: \"warning\",\n code: \"BAD_CHANNEL_FORMAT\",\n message: `channel \"${p.channel}\" must be lowercase kebab-case`\n });\n}\n```\n\n资料来源：[src/core/lint.ts:1-30]()\n\n## 配置与验证\n\n### Frontmatter Schema 验证\n\n系统使用 Zod 进行运行时验证，确保任务元数据的完整性：\n\n```typescript\nconst draftSchema = z.object({\n id: z.string().regex(/^[a-z0-9-]+$/),\n title: z.string().min(1),\n type: NoteType,\n created: z.string().regex(ISO_DATE),\n channel: z.string().regex(KEBAB).optional(),\n});\n```\n\n验证规则：\n- `id`：仅允许小写字母、数字和连字符\n- `created`：必须是 ISO 日期格式 `YYYY-MM-DD`\n- `channel`：必须是 kebab-case 格式\n\n资料来源：[src/core/frontmatter.ts:50-70]()\n\n### 索引查询能力\n\nVaultIndex 提供强大的查询能力，支持按多个维度过滤任务：\n\n```typescript\nexport function queryPages(\n idx: VaultIndex,\n filters: {\n wiki?: string;\n type?: string;\n status?: string;\n layer?: \"knowledge\" | \"execution\" | \"all\";\n }\n): IndexedPage[]\n```\n\n支持的过滤维度：\n- `wiki`：限定 wiki 范围\n- `type`：匹配页面类型\n- `status`：匹配页面状态\n- `layer`：按知识层过滤（knowledge 或 execution）\n\n资料来源：[src/core/index.ts:1-40]()\n\n## 系统集成\n\n### 与 Lint 系统集成\n\n任务协作系统与全局 lint 检查集成，确保数据质量：\n\n| 检查项 | 严重级别 | 说明 |\n|--------|----------|------|\n| `BAD_CHANNEL_FORMAT` | warning | Channel 名称格式不符合 kebab-case |\n| `FILENAME_ID_MISMATCH` | warning | 文件名与 ID 不匹配 |\n| `SNIPPET_NO_IMPLEMENTATION` | warning | 带有 snippet 标签的页面缺少 implementation 字段 |\n\n```typescript\n// 示例：遍历所有页面检查 channel 格式\nfor (const p of idx.pages) {\n if (input.wiki && p.wiki !== input.wiki) continue;\n if (p.channel && !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(p.channel)) {\n diagnostics.push({ /* ... */ });\n }\n}\n```\n\n资料来源：[src/core/lint.ts:20-45]()\n\n### 与 Synthesis 系统集成\n\n虽然任务本身不参与合成债务检测，但任务可以引用合成的知识资产：\n\n```typescript\n// 合成页面可以引用任务\nsources: inputIds.map(i => `[[wikis/${wiki}/${typeFolderForId(i)}/${i}]]`)\n```\n\n资料来源：[src/core/synthesize.ts:40-50]()\n\n## 总结\n\n任务协作系统是 Stoa 平台中连接知识管理与智能体执行的关键桥梁。它通过：\n\n1. **标准化数据模型**：基于 Zod schema 的类型安全定义\n2. **Channel 机制**：实现跨智能体的任务公告和认领\n3. **状态流转管理**：完整的任务生命周期支持\n4. **索引与查询**：高效的 VaultIndex 查询能力\n5. **质量保障**：集成 lint 检查确保数据完整性\n\n该系统设计遵循单一职责原则，将任务提取、状态管理、Channel 协作等功能模块化，便于维护和扩展。\n\n---\n\n\n\n## Claims与Evolution系统\n\n### 相关页面\n\n相关主题：[核心概念](#concepts), [Wiki管理](#wiki-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/claims.ts](https://github.com/BrettNye/stoa/blob/main/src/core/claims.ts)\n- [src/core/claim-render.ts](https://github.com/BrettNye/stoa/blob/main/src/core/claim-render.ts)\n- [src/core/claim-clustering.ts](https://github.com/BrettNye/stoa/blob/main/src/core/claim-clustering.ts)\n- [src/core/evolution.ts](https://github.com/BrettNye/stoa/blob/main/src/core/evolution.ts)\n- [src/core/evolution-claims.ts](https://github.com/BrettNye/stoa/blob/main/src/core/evolution-claims.ts)\n- [src/tools/claim.ts](https://github.com/BrettNye/stoa/blob/main/src/tools/claim.ts)\n- [src/tools/evolve-profile.ts](https://github.com/BrettNye/stoa/blob/main/src/tools/evolve-profile.ts)\n \n\n# Claims与Evolution系统\n\n## 系统概述\n\nClaims与Evolution系统是stoa项目的核心智能体能力框架，负责管理知识主张的验证、置信度计算以及智能体画像的动态演进。该系统通过半衰期衰减机制、证据链追踪和多维度评分算法，实现了知识可信度评估与能力成长的闭环管理。\n\nClaims（知识主张）作为系统的基本单元，承载了智能体对特定知识点的断言及其元数据。Evolution（进化）系统则利用Claims集合，通过聚类分析和移动推荐算法，驱动智能体画像的能力升级与专业化发展。\n\n**核心设计目标：**\n\n- 为知识断言提供可量化的置信度评估\n- 通过时间衰减机制保持知识库的新鲜度\n- 基于证据质量自动调整主张可信度\n- 支持多智能体协作场景下的知识共享与验证\n\n资料来源：[src/core/evolution.ts:1-30]()\n\n---\n\n## Claims数据模型\n\n### Claim基础结构\n\nClaims是知识主张的持久化表示，每个Claim包含以下核心字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 全局唯一标识符，格式为`claim-` |\n| `authored_by` | string | 主张创建者的智能体ID |\n| `confidence` | number | 原始置信度，范围0.0-1.0 |\n| `status` | enum | 主张状态：active/retracted/superseded |\n| `evidence` | string[] | 支持该主张的页面引用数组 |\n| `summary` | string | 主张的简要描述 |\n| `body` | string | 主张的完整内容 |\n| `last_validated` | string | ISO格式的最后验证时间 |\n| `validated_by` | string[] | 验证该主张的智能体ID列表 |\n| `tags` | string[] | 主题标签，用于分类和聚类 |\n| `profile` | string[] | 关联的画像ID列表 |\n\n资料来源：[src/tools/claim.ts:1-50]()\n\n### Claim状态机\n\n```mermaid\nstateDiagram-v2\n [*] --> active: 创建新主张\n active --> retracted: 作者主动撤回\n active --> superseded: 被更高置信度主张替代\n retracted --> [*]: 永久归档\n superseded --> [*]: 保留历史参考\n```\n\n**状态转换规则：**\n\n- **active → retracted**：仅原创建者可执行撤回操作\n- **active → superseded**：当新主张具有更高有效置信度时可触发\n- **retracted**：不可逆状态，记录撤回原因和时间戳\n\n资料来源：[src/tools/claim.ts:30-60]()\n\n---\n\n## 有效置信度计算\n\n### 半衰期衰减机制\n\n系统采用指数衰减模型计算主张的有效置信度，这是保持知识库时效性的核心机制：\n\n```\neffective_confidence = base_confidence × 0.5^(days_since_validation / half_life_days)\n```\n\n**衰减参数配置：**\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `half_life_days` | 90 | 置信度减半所需天数 |\n| `effective_floor` | 0.05 | 有效置信度下限 |\n\n### 有效置信度计算函数\n\n```typescript\nfunction effectiveConfidence(\n claim: { confidence: number; last_validated: string; status: string },\n today: Date,\n config: { half_life_days: number; effective_floor: number }\n): number {\n // 已撤回或被替代的主张直接返回下限\n if (claim.status !== \"active\") return config.effective_floor;\n \n const days = daysSince(claim.last_validated, today);\n const decay = Math.pow(0.5, days / config.half_life_days);\n const effective = claim.confidence * decay;\n \n return Math.max(effective, config.effective_floor);\n}\n```\n\n资料来源：[src/core/claim-render.ts:1-40]()\n\n### 部署画像加成\n\n当主张关联的画像与当前部署的智能体匹配时，额外获得0.1的置信度加成：\n\n```\nfinal_score = effective_confidence + (profile匹配 ? 0.1 : 0)\n```\n\n此机制确保智能体在评估与其能力相关的知识时具有优先权。\n\n资料来源：[src/core/claim-render.ts:10-20]()\n\n---\n\n## Claims工具集\n\n### 核心操作\n\n| 操作 | 说明 | 权限限制 |\n|------|------|----------|\n| `vault.claim-submit` | 提交新主张 | 无限制 |\n| `vault.claim-retract` | 撤回本人主张 | 仅原作者 |\n| `vault.claim-supersede` | 用新主张替代旧主张 | 高置信度优先 |\n| `vault.claim-read` | 读取主张详情 | 无限制 |\n\n### 提交新主张\n\n提交新主张时，系统执行以下校验：\n\n1. **唯一性检查**：相同证据+相同标签组合不允许重复提交\n2. **置信度门槛**：新主张置信度必须**严格高于**现有主张\n3. **证据完整性**：建议提供至少一个证据页面引用\n\n若校验失败，返回`rejected`状态并附带拒绝原因和现有主张信息：\n\n```json\n{\n \"claim_id\": \"existing_claim_id\",\n \"action\": \"rejected\",\n \"rejection\": {\n \"reason\": \"existing claim has effective confidence 0.756; submission's 0.700 is not strictly higher\",\n \"existing_id\": \"claim-xxx\",\n \"existing_effective_confidence\": 0.756,\n \"your_confidence\": 0.700\n }\n}\n```\n\n资料来源：[src/tools/claim.ts:40-80]()\n\n---\n\n## Evolution进化系统\n\n### 进化决策流程\n\n```mermaid\ngraph TD\n A[输入: 画像ID] --> B[查询关联Claims]\n B --> C{Claims数量 ≥ 阈值?}\n C -->|否| D[返回不满足条件]\n C -->|是| E[聚类分析Claims]\n E --> F[识别Top Clusters]\n F --> G[计算专业领域建议]\n G --> H[生成移动推荐]\n H --> I[渲染进化理由]\n I --> J[输出: 进化结果]\n```\n\nEvolution系统通过以下步骤为智能体生成能力进化建议：\n\n1. **Claims收集**：获取关联画像的所有活动主张\n2. **聚类分析**：基于标签和证据将主张分组\n3. **专业领域识别**：找出Claims最集中的领域\n4. **移动推荐**：基于聚类结果推荐可学习的技能\n5. **理由生成**：构建人类可读的进化建议文本\n\n资料来源：[src/core/evolution.ts:1-50]()\n\n### 进化输出结构\n\n```typescript\ninterface EvolutionResult {\n eligible: boolean;\n reason: string;\n current: ProfileSnapshot;\n proposed: {\n specialties: string[];\n moveset_suggestions: MoveSuggestion[];\n };\n rationale: string;\n eligibility: EligibilityDetails;\n evidence_summary: EvidenceSummary;\n}\n```\n\n### 专业领域（Specialties）\n\n系统从Claim聚类中提取排名前3的专业领域：\n\n- 按标签频率排序\n- 仅考虑有效置信度>0.2的Claims\n- 每个领域至少包含2个Claims\n\n### 移动建议（Move Suggestions）\n\n基于聚类分析结果，系统推荐适合当前能力阶段的学习移动：\n\n```typescript\ninterface MoveSuggestion {\n move_id: string;\n move_hint: string;\n evidence_claim_ids: string[];\n}\n```\n\n资料来源：[src/core/evolution.ts:50-100]()\n\n---\n\n## Claims聚类机制\n\n### 聚类算法\n\nClaims聚类基于多维度相似度计算：\n\n```mermaid\ngraph LR\n A[Claim A] -->|标签交集| E[相似度计算]\n B[Claim B] -->|标签交集| E\n A -->|证据重叠| E\n B -->|证据重叠| E\n E --> F[聚类分组]\n```\n\n**聚类维度：**\n\n| 维度 | 权重 | 说明 |\n|------|------|------|\n| 标签重叠 | 0.5 | 共同标签越多，关联越强 |\n| 证据重叠 | 0.3 | 引用的页面重叠度高 |\n| 时间邻近 | 0.2 | 相近时间创建的Claims更可能相关 |\n\n### 聚类用途\n\n1. **Evolution进化**：识别能力集中的主题领域\n2. **合成建议**：检测可合成的新知识主题\n3. **冲突检测**：发现相互矛盾的Claims组\n\n资料来源：[src/core/claim-clustering.ts:1-30]()\n\n---\n\n## 配置参数\n\n### Claims配置\n\n在`wikis//CLAUDE.md`中配置：\n\n```yaml\nclaims:\n half_life_days: 90 # 置信度衰减半衰期\n effective_floor: 0.05 # 最低有效置信度\n min_evidence: 1 # 最少证据数量\n```\n\n### Evolution配置\n\n```yaml\nevolution:\n min_claims_for_evolution: 10 # 触发进化的最少Claims数\n max_specialties: 3 # 最大专业领域数\n cluster_min_size: 2 # 聚类最小规模\n```\n\n### 渲染配置\n\n```typescript\ninterface ClaimsConfig {\n half_life_days: number;\n effective_floor: number;\n render_min_confidence: number; // 仅渲染高于此值的主张\n include_unvalidated: boolean; // 是否包含未验证主张\n}\n```\n\n资料来源：[src/core/claim-render.ts:1-60]()\n\n---\n\n## 工具注册与集成\n\n### 工具清单\n\n| 工具名称 | 功能 | 源码位置 |\n|----------|------|----------|\n| `vault.claim-submit` | 提交新主张 | src/tools/claim.ts |\n| `vault.claim-retract` | 撤回主张 | src/tools/claim.ts |\n| `vault.claim-read` | 读取主张详情 | src/tools/claim.ts |\n| `vault.evolve-profile` | 触发画像进化 | src/tools/evolve-profile.ts |\n| `vault.lint` | Claims相关检查 | src/tools/lint.ts |\n\n### Lint检查集成\n\nClaims系统与lint检查模块集成，提供以下质量保障规则：\n\n- **claim-key-collision**：检测重复主张\n- **claim-effective-below-floor**：标记有效置信度过低的主张\n- **claim-without-evidence**：检测缺少证据的主张\n- **claim-tag-repo-prefix-malformed**：标签格式校验\n\n资料来源：[src/tools/lint.ts:1-30]()\n\n---\n\n## 与其他系统模块的交互\n\n### 与索引系统的集成\n\nClaims的增删改查通过ClaimsStore与索引系统同步：\n\n```mermaid\nsequenceDiagram\n 参与者 Agent->>ClaimsStore: submit(claim)\n ClaimsStore->>Index: upsertPage(frontmatter)\n Index->>ClaimsStore: 返回索引结果\n ClaimsStore->>参与者 Agent: 返回claim_id\n```\n\n### 与Profile系统的集成\n\nEvolution结果直接作用于Profile：\n\n1. Evolution输出的`specialties`更新到Profile的`specialties`字段\n2. `moveset_suggestions`提供可选的技能扩展路径\n3. Profile的`evolution_stage`根据Claims累积量自动推进\n\n### 与合成系统的集成\n\nClaims聚类结果为`synthesize`工具提供素材：\n\n- 聚类标签直接作为合成主题建议\n- 高置信度Claims作为合成内容的证据来源\n- 有效置信度作为Claims在合成中的权重因子\n\n资料来源：[src/core/evolution.ts:80-120]()\n\n---\n\n## 最佳实践\n\n### 提高主张置信度\n\n1. **提供充分证据**：引用多个相关页面\n2. **主动验证**：定期重新验证旧主张\n3. **多人验证**：让多个智能体验证同一主张\n\n### 避免主张被拒绝\n\n1. 新主张置信度必须严格高于现有主张\n2. 确保证据页面真实存在且可访问\n3. 使用规范化的标签命名\n\n### 有效利用进化系统\n\n1. 保持Claims数量在触发阈值以上\n2. 关注高置信度Claims集中的领域\n3. 根据进化建议选择可学习的移动\n\n---\n\n\n\n## CLI命令参考\n\n### 相关页面\n\n相关主题：[任务协作系统](#task-coordination)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cli/commands/recall.ts](https://github.com/BrettNye/stoa/blob/main/src/cli/commands/recall.ts)\n- [src/cli/commands/inbox.ts](https://github.com/BrettNye/stoa/blob/main/src/cli/commands/inbox.ts)\n- [src/cli/commands/synthesize.ts](https://github.com/BrettNye/stoa/blob/main/src/cli/commands/synthesize.ts)\n- [src/cli/commands/channel-post.ts](https://github.com/BrettNye/stoa/blob/main/src/cli/commands/channel-post.ts)\n- [src/cli/commands/task-create.ts](https://github.com/BrettNye/stoa/blob/main/src/cli/commands/task-create.ts)\n- [src/cli/commands/bootstrap-repo.ts](https://github.com/BrettNye/stoa/blob/main/src/cli/commands/bootstrap-repo.ts)\n- [src/cli/commands/new-wiki.ts](https://github.com/BrettNye/stoa/blob/main/src/cli/commands/new-wiki.ts)\n \n\n# CLI命令参考\n\n本文档全面介绍 stoa CLI 的命令结构、用法模式及核心命令详解。stoa 是一个基于 MCP（Model Context Protocol）的知识库管理系统，通过命令行接口提供笔记检索、内容捕获、任务协作等功能。\n\n## 概述\n\nstoa CLI 是 vault-mcp 服务器的命令行封装，提供与 MCP 工具等效的操作能力。所有命令均支持通过 `--vault` 参数指定 vault 路径，或通过环境变量 `STOA_VAULT_PATH` 设置默认路径。资料来源：[README.md:1-50]()\n\n```bash\nstoa --vault=/path/to/vault recall \nstoa --vault=/path/to/vault inbox \"thought to capture\"\nstoa --vault=/path/to/vault list-wikis\n```\n\n环境变量 `STOA_VAULT_PATH` 可替代每次调用时的 `--vault=` 参数，提升使用效率。资料来源：[README.md:45-50]()\n\n## 命令架构\n\nstoa CLI 采用Commander框架进行命令解析，支持多层级子命令结构。命令注册遵循统一模式，每个命令模块负责注册自身的参数解析和行为逻辑。资料来源：[src/cli/commands/new-wiki.ts:1-15]()\n\n```mermaid\ngraph TD\n A[stoa CLI] --> B[--vault 路径选项]\n A --> C[命令主体]\n C --> D[recall]\n C --> E[inbox]\n C --> F[synthesize]\n C --> G[channel-post]\n C --> H[task-create]\n C --> I[bootstrap-repo]\n C --> J[new-wiki]\n C --> K[list-wikis]\n```\n\n## 核心命令详解\n\n### recall — 主题检索\n\n`recall` 命令根据关键词检索 vault 中的相关页面，返回匹配的页面列表及相关性评分。\n\n```bash\nstoa --vault=/path/to/vault recall \n```\n\n**功能说明：** 该命令通过全文索引和分词机制匹配包含指定主题的笔记内容，返回最多25条相关结果。资料来源：[src/core/index.ts:1-30]()\n\n检索结果包含页面ID、标题、wiki归属及更新时间等元数据，支持通过 `--limit` 参数调整返回数量。\n\n### inbox — 快速捕获\n\n`inbox` 命令用于即时捕获思绪或临时笔记，将其写入当前激活 wiki 的 inbox 目录。\n\n```bash\nstoa --vault=/path/to/vault inbox \"thought to capture\"\n```\n\n**功能说明：** 捕获的内容会自动添加时间戳并生成唯一ID，适合记录快速闪现的想法而不打乱现有工作流。资料来源：[src/cli/commands/inbox.ts:1-20]()\n\n### synthesize — 合成页面生成\n\n`synthesize` 命令从多个源页面编译生成综合报告，适用于知识整合与摘要生成场景。\n\n```bash\nstoa --vault=/path/to/vault synthesize --topic \"主题名称\"\n```\n\n**功能说明：** 系统根据主题相关性从 vault 中选取相关页面，自动生成包含引用来源的综合文档。生成结果保存为 `synthesis-*.md` 格式的草稿页面。资料来源：[src/core/synthesize.ts:1-50]()\n\n### channel-post — 频道消息发布\n\n`channel-post` 用于向协调频道发布消息，支持跨实例通信与任务协调。\n\n```bash\nstoa --vault=/path/to/vault channel-post --channel --message \n```\n\n**功能说明：** 频道消息遵循 YAML 格式规范，支持结构化数据传递。消息发布后可供其他 MCP 客户端或订阅者消费。资料来源：[src/cli/commands/channel-post.ts:1-25]()\n\n### task-create — 任务创建\n\n`task-create` 命令用于在 vault 中创建新任务，支持原子性任务声明与竞态处理。\n\n```bash\nstoa --vault=/path/to/vault task-create --title --description <desc>\n```\n\n**功能说明：** 任务创建采用乐观锁机制防止并发冲突，后到的声明请求会收到 `AlreadyClaimedError` 错误。资料来源：[README.md:30-35]()\n\n### bootstrap-repo — 仓库引导\n\n`bootstrap-repo` 命令为消费仓库初始化 MCP 配置和 CLAUDE.md 片段，建立与 vault 的连接。\n\n```bash\nstoa --vault=/path/to/vault bootstrap-repo --target <repo-path>\n```\n\n**功能说明：** 该命令在目标仓库中写入 `.mcp.json` 配置文件和 `CLAUDE.md` 引导文件，完成自动化集成设置。资料来源：[src/cli/commands/bootstrap-repo.ts:1-20]()\n\n### new-wiki — 新建 Wiki\n\n`new-wiki` 命令脚手架化一个新的 wiki 空间，包括必要的文件夹结构和初始化文件。\n\n```bash\nstoa new-wiki <name> --mode <mode> --scope <scope>\n```\n\n**参数说明：**\n\n| 参数 | 必填 | 说明 |\n|------|------|------|\n| `<name>` | 是 | Wiki 名称 |\n| `--mode` | 是 | 创建模式：idea-map、project-doc、learning、mixed |\n| `--scope` | 是 | Wiki 作用域定义 |\n\n**功能说明：** 新建的 wiki 包含 `map.md`、`index.md`、wiki 本地的 `CLAUDE.md` 等标准文件。资料来源：[src/cli/commands/new-wiki.ts:1-18]()\n\n## 环境变量\n\n| 变量名 | 说明 | 优先级 |\n|--------|------|--------|\n| `STOA_VAULT_PATH` | 设置默认 vault 路径 | 高于 `.active-wiki` 文件 |\n| `STOA_DEFAULT_WIKI` | 设置默认 wiki 名称 | 高于配置文件 |\n| `STOA_DEFAULT_FAMILY` | 设置默认家族名称 | 高于配置文件 |\n\n环境变量设置后可省略 `--vault` 参数，直接使用命令主体。资料来源：[README.md:45-50]()\n\n## Wiki 参数解析顺序\n\n当命令涉及 wiki 作用域时，系统按以下优先级解析 wiki 标识：\n\n1. 显式 `wiki:` 参数\n2. `--default-wiki=<name>` 服务器启动参数\n3. vault 根目录的 `.active-wiki` 文件\n4. 无匹配时抛出错误\n\n资料来源：[README.md:40-45]()\n\n## 命令执行流程\n\n```mermaid\nsequenceDiagram\n participant CLI as 命令行\n participant CMD as 命令处理器\n participant CORE as 核心模块\n participant FS as 文件系统\n \n CLI->>CMD: 解析参数与选项\n CMD->>CMD: 加载上下文配置\n CMD->>CORE: 调用核心业务逻辑\n CORE->>FS: 读写 vault 数据\n FS-->>CORE: 返回操作结果\n CORE-->>CMD: 格式化输出\n CMD-->>CLI: 显示结果\n```\n\n## 输出格式\n\nCLI 命令的输出遵循统一格式，包含操作状态和结果数据：\n\n- **成功操作：** 返回 JSON 格式的结构化结果\n- **错误情况：** 返回错误码和描述信息\n- **列表查询：** 返回数组格式的多项结果\n\n## 相关命令索引\n\n| 分类 | 命令 | 功能 |\n|------|------|------|\n| 读取 | recall | 主题检索 |\n| 写入 | inbox | 快速捕获 |\n| 写入 | synthesize | 合成页面 |\n| 协作 | channel-post | 频道消息 |\n| 协作 | task-create | 任务创建 |\n| 系统 | bootstrap-repo | 仓库引导 |\n| 系统 | new-wiki | 新建 wiki |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：BrettNye/stoa\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1229401738 | https://github.com/BrettNye/stoa | host_targets=mcp_host, claude, claude_code\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1229401738 | https://github.com/BrettNye/stoa | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1229401738 | https://github.com/BrettNye/stoa | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1229401738 | https://github.com/BrettNye/stoa | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | release_recency=unknown\n\n<!-- canonical_name: BrettNye/stoa; human_manual_source: deepwiki_human_wiki -->\n",
"markdown_key": "stoa",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1229401738",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/BrettNye/stoa"
},
{
"evidence_id": "art_fb38c6ad5653460cb95cb87f1efd1ea3",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/BrettNye/stoa#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "stoa 说明书",
"toc": [
"https://github.com/BrettNye/stoa 项目说明书",
"目录",
"项目概述",
"项目简介",
"核心架构",
"核心模块",
"CLI 命令",
"页面类型对应文件命名",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "1f7295ccab5c8319905400084d619d4b8624bbce",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"docs/manual-smoke-test.md",
"docs/agent-memory.md",
"docs/installation.md",
"docs/wait-for.md",
"src/config.ts",
"src/silence-dotenv.ts",
"src/bin.ts",
"src/cli/_ctx.ts",
"src/cli/index.ts",
"src/tools/list-invites.ts",
"src/tools/refresh-profile-memory.ts",
"src/tools/task-create.ts",
"src/tools/suggest-pokemon.ts",
"src/tools/inbox.ts",
"src/tools/channel-tail.ts",
"src/tools/_resolve-wiki.ts",
"src/tools/task-list.ts",
"src/tools/lint.ts",
"src/tools/channel-post.ts",
"src/tools/wait-for.ts",
"src/tools/move-fuse.ts",
"src/tools/merge-queue.ts",
"src/tools/read.ts",
"src/tools/list-platform-profiles.ts",
"src/tools/new.ts",
"src/tools/profile-register.ts",
"src/tools/list-claims.ts",
"src/tools/sync-skills.ts",
"src/tools/bootstrap-repo.ts",
"src/tools/list-wikis.ts",
"src/tools/task-claim.ts",
"src/tools/wait-for-any.ts",
"src/tools/trainer-submit-move.ts",
"src/tools/wait-for-all.ts",
"src/tools/index.ts",
"src/tools/profile-stats.ts",
"src/tools/real-skill-refresh.ts",
"src/tools/start.ts"
],
"repo_inspection_verified": true,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @stoa-mcp/cli - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @stoa-mcp/cli 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm i -g @stoa-mcp/cli` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、宿主 AI 上下文\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：436\n- 重要文件覆盖：30/436\n- 证据索引条目：30\n- 角色 / Skill 条目：17\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @stoa-mcp/cli 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @stoa-mcp/cli 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @stoa-mcp/cli 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 17 个角色 / Skill / 项目文档条目。\n\n- **Stoa**（project_doc）：Persistent shared memory for AI coding agents. Your Claude Code sessions stop forgetting things across days, repos, and machines. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Vault schema fixture**（project_doc）：Fixture vault for integration tests. Mirrors v1 conventions but smaller. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/fixtures/test-vault/CLAUDE.md`\n- **alpha — wiki conventions**（project_doc）：Mode: idea-map Scope: fixture for tests 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/fixtures/test-vault/wikis/alpha/CLAUDE.md`\n- **beta — wiki conventions**（project_doc）：Mode: project-doc Scope: fixture demonstrating cross-wiki references 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/fixtures/test-vault/wikis/beta/CLAUDE.md`\n- **Installation**（project_doc）：- Node.js 20 or newer. Check with node --version . - A vault directory — a folder containing a CLAUDE.md at its root and optionally an index/ subdirectory. The index/ is created automatically on first reindex if missing. If you don't have a vault yet, create an empty folder and a one-line CLAUDE.md to start. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/installation.md`\n- **Manual cross-repo smoke test**（project_doc）：Run this once per release to verify the cross-repo workflow end-to-end. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/manual-smoke-test.md`\n- **wait-for: push primitives**（project_doc）：Cross-process event coordination over the local filesystem. Four MCP tools — vault.wait-for , vault.wait-for-any , vault.wait-for-all , vault.wait-for-many — let an agent register a single bounded wait that resolves on the next matching journal or task event, instead of polling vault.channel-tail on a timer. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/wait-for.md`\n- **claim page template — instantiated by vault.new claim \" \" .**（project_doc）：<!-- Claim body: 1-3 sentences explaining the assertion. Keep prose under ~280 characters when possible — this is what vault.sync-skills will render into the deployed SKILL.md, and longer prose gets truncated or wraps awkwardly in agent context windows. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/fixtures/templates/claim.md`\n- **Wikis**（project_doc）：- alpha mode: idea-map — fixture wiki for tests - beta mode: project-doc — fixture wiki demonstrating cross-wiki links 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/fixtures/test-vault/REGISTRY.md`\n- **Concept Bar**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/fixtures/test-vault/wikis/alpha/concepts/concept-bar.md`\n- **Concept Foo**（project_doc）：The foo concept is fundamental to bar. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/fixtures/test-vault/wikis/alpha/concepts/concept-foo.md`\n- **Decision 2026 04 01 Pick Foo**（project_doc）：After comparing options we picked foo. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/fixtures/test-vault/wikis/alpha/decisions/decision-2026-04-01-pick-foo.md`\n- **alpha**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/fixtures/test-vault/wikis/alpha/map.md`\n- **Synthesis Foo Vs Bar**（project_doc）：Compared foo and bar; foo wins for simplicity, bar wins for power. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/fixtures/test-vault/wikis/alpha/synthesis/synthesis-foo-vs-bar.md`\n- **Task Implement Baz**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/fixtures/test-vault/wikis/alpha/tasks/task-implement-baz.md`\n- **Concept Quux**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/fixtures/test-vault/wikis/beta/concepts/concept-quux.md`\n- **beta**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/fixtures/test-vault/wikis/beta/map.md`\n\n## 证据索引\n\n- 共索引 30 条证据。\n\n- **Stoa**（documentation）：Persistent shared memory for AI coding agents. Your Claude Code sessions stop forgetting things across days, repos, and machines. 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"@stoa-mcp/cli\", \"version\": \"0.1.0\", \"description\": \"Persistent shared memory for AI coding agents MCP server + CLI \", \"type\": \"module\", \"license\": \"FSL-1.1-MIT\", \"bin\": { \"stoa\": \"./dist/bin.js\" }, \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/BrettNye/stoa.git\" }, \"homepage\": \"https://github.com/BrettNye/stoa readme\", \"bugs\": { \"url\": \"https://github.com/BrettNye/stoa/issues\" }, \"keywords\": \"mcp\", \"model-context-protocol\", \"claude\", \"claude-code\", \"memory\", \"knowledge-management\", \"ai-agents\" , \"files\": \"dist\", \"README.md\" , \"scripts\": { \"build\": \"tsc\", \"dev\": \"tsx src/bin.ts\", \"test\": \"vitest run\", \"test:watch\": \"vitest\", \"lint\": \"eslint src tests\" }, \"dependenc… 证据：`package.json`\n- **Vault schema fixture**（documentation）：Fixture vault for integration tests. Mirrors v1 conventions but smaller. 证据：`tests/fixtures/test-vault/CLAUDE.md`\n- **alpha — wiki conventions**（documentation）：Mode: idea-map Scope: fixture for tests 证据：`tests/fixtures/test-vault/wikis/alpha/CLAUDE.md`\n- **beta — wiki conventions**（documentation）：Mode: project-doc Scope: fixture demonstrating cross-wiki references 证据：`tests/fixtures/test-vault/wikis/beta/CLAUDE.md`\n- **Functional Source License, Version 1.1, MIT Future License**（source_file）：Functional Source License, Version 1.1, MIT Future License 证据：`LICENSE`\n- **Installation**（documentation）：- Node.js 20 or newer. Check with node --version . - A vault directory — a folder containing a CLAUDE.md at its root and optionally an index/ subdirectory. The index/ is created automatically on first reindex if missing. If you don't have a vault yet, create an empty folder and a one-line CLAUDE.md to start. 证据：`docs/installation.md`\n- **Manual cross-repo smoke test**（documentation）：Run this once per release to verify the cross-repo workflow end-to-end. 证据：`docs/manual-smoke-test.md`\n- **wait-for: push primitives**（documentation）：Cross-process event coordination over the local filesystem. Four MCP tools — vault.wait-for , vault.wait-for-any , vault.wait-for-all , vault.wait-for-many — let an agent register a single bounded wait that resolves on the next matching journal or task event, instead of polling vault.channel-tail on a timer. 证据：`docs/wait-for.md`\n- **claim page template — instantiated by vault.new claim \" \" .**（documentation）：<!-- Claim body: 1-3 sentences explaining the assertion. Keep prose under ~280 characters when possible — this is what vault.sync-skills will render into the deployed SKILL.md, and longer prose gets truncated or wraps awkwardly in agent context windows. 证据：`tests/fixtures/templates/claim.md`\n- **.Eslintrc**（structured_config）：{ \"parser\": \"@typescript-eslint/parser\", \"plugins\": \"@typescript-eslint\" , \"extends\": \"eslint:recommended\", \"plugin:@typescript-eslint/recommended\" , \"rules\": { \"@typescript-eslint/no-unused-vars\": \"warn\", { \"argsIgnorePattern\": \"^ \", \"varsIgnorePattern\": \"^ \" } , \"@typescript-eslint/no-explicit-any\": \"off\", \"@typescript-eslint/no-unsafe-function-type\": \"off\", \"no-useless-escape\": \"off\", \"no-control-regex\": \"off\", \"no-constant-condition\": \"off\", \"prefer-const\": \"warn\" } } 证据：`.eslintrc.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"ESNext\", \"moduleResolution\": \"bundler\", \"outDir\": \"./dist\", \"rootDir\": \"./src\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"resolveJsonModule\": true, \"declaration\": true, \"sourceMap\": true }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\", \"tests\" } 证据：`tsconfig.json`\n- **.gitignore**（source_file）：node modules/ dist/ .log .DS Store coverage/ 证据：`.gitignore`\n- **statusline-pokemon.ps1 — emit a one-line statusline summary for the active vault Pokemon.**（source_file）：statusline-pokemon.ps1 — emit a one-line statusline summary for the active vault Pokemon. Usage: $env:STOA VAULT PATH= ; $env:VAULT POKEMON= ; .\\statusline-pokemon.ps1 证据：`scripts/statusline-pokemon.ps1`\n- **!/usr/bin/env bash**（source_file）：!/usr/bin/env bash statusline-pokemon.sh — emit a one-line statusline summary for the active vault Pokemon. Usage: env STOA VAULT PATH= VAULT POKEMON= statusline-pokemon.sh Wire into Claude Code statusline: \"statusLine\": { \"type\": \"command\", \"command\": \"bash /path/to/statusline-pokemon.sh\" } 证据：`scripts/statusline-pokemon.sh`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node import \"./silence-dotenv.js\"; // MUST be first — see comment in that file import { parseConfig, ConfigError } from \"./config.js\"; import { setCtx } from \"./cli/ ctx.js\"; import { buildCli } from \"./cli/index.js\"; import { startStdio } from \"./transport/stdio.js\"; 证据：`src/bin.ts`\n- **Config**（source_file）：import { resolve } from \"node:path\"; import { z } from \"zod\"; 证据：`src/config.ts`\n- **Silence Dotenv**（source_file）：// Side-effect-only module. MUST be imported FIRST in bin.ts and any other // entrypoint — before any module that transitively pulls in natural . // // The natural package depends on dotenv@17+ , which prints unsolicited // \"tip:\" advertisements to stdout on import. That corrupts MCP's stdio // JSON-RPC framing and prevents clients from connecting. Setting // DOTENV CONFIG QUIET=true before dotenv loads suppresses the tips. // // ESM evaluates imports in source order, so as long as this module is // imported first, the env var is in place before natural's transitive // dotenv module runs its top-level code. process.env.DOTENV CONFIG QUIET = \"true\"; 证据：`src/silence-dotenv.ts`\n- **Wikis**（documentation）：- alpha mode: idea-map — fixture wiki for tests - beta mode: project-doc — fixture wiki demonstrating cross-wiki links 证据：`tests/fixtures/test-vault/REGISTRY.md`\n- **Concept Bar**（documentation）：--- id: concept-bar title: \"Bar concept\" type: concept wiki: alpha status: active created: 2026-04-01 updated: 2026-04-28 summary: \"The bar entity.\" tags: bar, testing --- Bar depends on foo. 证据：`tests/fixtures/test-vault/wikis/alpha/concepts/concept-bar.md`\n- **Concept Foo**（documentation）：The foo concept is fundamental to bar. 证据：`tests/fixtures/test-vault/wikis/alpha/concepts/concept-foo.md`\n- **Decision 2026 04 01 Pick Foo**（documentation）：After comparing options we picked foo. 证据：`tests/fixtures/test-vault/wikis/alpha/decisions/decision-2026-04-01-pick-foo.md`\n- **alpha**（documentation）：--- id: map-alpha title: \"alpha map\" type: map wiki: alpha status: active created: 2026-04-01 updated: 2026-04-28 summary: \"Map of the alpha wiki for fixture testing.\" --- alpha Fixture wiki content. 证据：`tests/fixtures/test-vault/wikis/alpha/map.md`\n- **Synthesis Foo Vs Bar**（documentation）：Compared foo and bar; foo wins for simplicity, bar wins for power. 证据：`tests/fixtures/test-vault/wikis/alpha/synthesis/synthesis-foo-vs-bar.md`\n- **Task Implement Baz**（documentation）：--- id: task-implement-baz title: \"Implement baz handler\" type: task wiki: alpha status: pending created: 2026-04-28 updated: 2026-04-28 summary: \"Implement the baz request handler.\" --- Add a handler for baz requests. 证据：`tests/fixtures/test-vault/wikis/alpha/tasks/task-implement-baz.md`\n- **Concept Quux**（documentation）：--- id: concept-quux title: \"Quux concept\" type: concept wiki: beta status: active created: 2026-04-01 updated: 2026-04-28 summary: \"Quux is a downstream concept; alpha cites this.\" tags: quux, testing --- Quux extends foo and bar. 证据：`tests/fixtures/test-vault/wikis/beta/concepts/concept-quux.md`\n- **beta**（documentation）：--- id: map-beta title: \"beta map\" type: map wiki: beta status: active created: 2026-04-01 updated: 2026-04-28 summary: \"Map of the beta wiki.\" --- beta 证据：`tests/fixtures/test-vault/wikis/beta/map.md`\n- **Helpers**（source_file）：// vault-mcp/tests/helpers.ts // // Shared test helpers for the claims plan Plan 1 test suites. Hoisted per // the plan's S7 test-helper hoisting + H8 import resolution hazards: 13 // downstream tasks import from this file, so it lives upstream of all of // them in the DAG. See wikis/ meta/plans/2026-05-02-vault-mcp-claims-plan- // 1-foundation-dag.md §task-test-helpers for the contract. // // Conventions: // - Temp vaults under os.tmpdir with mkdtempSync synchronous because // we want a stable directory name before any async work begins . // - Frontmatter is serialized via JSON.stringify per value to dodge YAML // escaping pitfalls matches the v1.5 friction T3-5 lesson on ISO date // quoti… 证据：`tests/helpers.ts`\n- **Setup**（source_file）：import { mkdtempSync } from \"node:fs\"; import { join } from \"node:path\"; import { tmpdir } from \"node:os\"; 证据：`tests/setup.ts`\n- **Vitest.Config**（source_file）：import { defineConfig } from \"vitest/config\"; 证据：`vitest.config.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `package.json`, `tests/fixtures/test-vault/CLAUDE.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `package.json`, `tests/fixtures/test-vault/CLAUDE.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, package.json, src/config.ts\n- **核心概念**：importance `high`\n - source_paths: src/core/wikis.ts, src/core/claims.ts, src/core/pages.ts, src/core/profiles.ts, src/core/scope-hash.ts\n- **系统架构**：importance `high`\n - source_paths: src/cli/index.ts, src/core/index.ts, src/tools/index.ts, src/core/start.ts\n- **传输层实现**：importance `medium`\n - source_paths: src/transport/stdio.ts, src/transport/http.ts, src/transport/ui/index.ts, src/transport/ui/routes-read.ts, src/transport/ui/routes-write.ts\n- **事件总线系统**：importance `high`\n - source_paths: src/core/eventbus/bus.ts, src/core/eventbus/match.ts, src/core/eventbus/registry.ts, src/core/eventbus/event-deriver.ts, src/core/eventbus/handle-wait.ts\n- **召回与检索系统**：importance `high`\n - source_paths: src/core/recall.ts, src/core/claims-index.ts, src/core/recall-filter.ts, src/tools/recall.ts, src/tools/read.ts\n- **Wiki管理**：importance `high`\n - source_paths: src/core/wikis.ts, src/core/frontmatter.ts, src/core/wikilinks.ts, src/core/synthesize.ts, src/tools/new-wiki.ts\n- **任务协作系统**：importance `high`\n - source_paths: src/core/tasks.ts, src/core/inbox.ts, src/core/channel.ts, src/core/sync-enumerate.ts, src/tools/task-claim.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `1f7295ccab5c8319905400084d619d4b8624bbce`\n- inspected_files: `package.json`, `README.md`, `docs/manual-smoke-test.md`, `docs/agent-memory.md`, `docs/installation.md`, `docs/wait-for.md`, `src/config.ts`, `src/silence-dotenv.ts`, `src/bin.ts`, `src/cli/_ctx.ts`, `src/cli/index.ts`, `src/tools/list-invites.ts`, `src/tools/refresh-profile-memory.ts`, `src/tools/task-create.ts`, `src/tools/suggest-pokemon.ts`, `src/tools/inbox.ts`, `src/tools/channel-tail.ts`, `src/tools/_resolve-wiki.ts`, `src/tools/task-list.ts`, `src/tools/lint.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1229401738 | https://github.com/BrettNye/stoa | host_targets=mcp_host, claude, claude_code\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1229401738 | https://github.com/BrettNye/stoa | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1229401738 | https://github.com/BrettNye/stoa | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1229401738 | https://github.com/BrettNye/stoa | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：BrettNye/stoa\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude, claude_code\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/BrettNye/stoa 项目说明书\n\n生成时间：2026-05-13 16:44:51 UTC\n\n## 目录\n\n- [项目概述](#overview)\n- [核心概念](#concepts)\n- [系统架构](#architecture)\n- [传输层实现](#transport)\n- [事件总线系统](#eventbus)\n- [召回与检索系统](#recall-system)\n- [Wiki管理](#wiki-management)\n- [任务协作系统](#task-coordination)\n- [Claims与Evolution系统](#claims-evolution)\n- [CLI命令参考](#cli-commands)\n\n<a id='overview'></a>\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [核心概念](#concepts)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/core/index.ts](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts)\n- [src/core/pages.ts](https://github.com/BrettNye/stoa/blob/main/src/core/pages.ts)\n- [src/core/wikilinks.ts](https://github.com/BrettNye/stoa/blob/main/src/core/wikilinks.ts)\n- [src/core/synthesize.ts](https://github.com/BrettNye/stoa/blob/main/src/core/synthesize.ts)\n- [src/core/syntheses.ts](https://github.com/BrettNye/stoa/blob/main/src/core/syntheses.ts)\n- [src/core/family.ts](https://github.com/BrettNye/stoa/blob/main/src/core/family.ts)\n- [src/core/frontmatter.ts](https://github.com/BrettNye/stoa/blob/main/src/core/frontmatter.ts)\n- [src/transport/stdio.ts](https://github.com/BrettNye/stoa/blob/main/src/transport/stdio.ts)\n- [src/core/skills-platform.ts](https://github.com/BrettNye/stoa/blob/main/src/core/skills-platform.ts)\n- [src/core/lint-checks/synthesis-debt.ts](https://github.com/BrettNye/stoa/blob/main/src/core/lint-checks/synthesis-debt.ts)\n</details>\n\n# 项目概述\n\n## 项目简介\n\n**stoa** 是一个基于 Markdown 文件系统的知识库管理系统（Knowledge Vault System），通过结构化的组织方式管理包含前端matter 的 markdown 文件。该系统提供了页面索引、维基链接解析、合成页面生成、语法检查、CLI 命令工具以及 MCP（Model Context Protocol）服务等核心功能。\n\n系统的核心设计理念是将知识以标准化的页面形式存储在文件系统中，通过索引和工具层实现高级的知识管理操作，如跨页面引用、批量合成、部署漂移检测等。\n\n## 核心架构\n\n### 系统层次结构\n\nstoa 采用分层架构设计，主要包含以下层次：\n\n```mermaid\ngraph TD\n A[CLI 层] --> B[工具层]\n B --> C[核心业务层]\n C --> D[传输层]\n D --> E[文件系统]\n \n F[lint-checks] --> C\n G[index] --> C\n H[pages] --> C\n I[synthesize] --> C\n```\n\n### 目录结构\n\n项目源码按功能模块组织：\n\n| 目录 | 职责 |\n|------|------|\n| `src/core/` | 核心业务逻辑，包含索引、页面操作、合成、链接解析等 |\n| `src/tools/` | MCP 工具实现，如 profile-register 等 |\n| `src/cli/` | 命令行接口实现 |\n| `src/transport/` | 传输层实现，如 stdio 服务器 |\n| `src/core/lint-checks/` | 各种语法检查规则实现 |\n\n## 核心模块\n\n### 页面管理（pages）\n\n页面是 stoa 的基本存储单元，每个页面对应一个 markdown 文件。\n\n```mermaid\ngraph LR\n A[page id] --> B[pathForPage]\n B --> C[文件系统路径]\n D[readPage] --> E[返回页面对象]\n F[writePage] --> G[持久化到磁盘]\n```\n\n页面对象包含以下字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 页面唯一标识符 |\n| `path` | string | 文件系统路径 |\n| `frontmatter` | Record | YAML 前端配置 |\n| `body` | string | markdown 正文内容 |\n| `updated` | string | ISO 日期格式的更新时间 |\n\n资料来源：[src/core/pages.ts:1-50]()\n\n页面读取时会解析文件的前端matter，提取元数据并规范化更新时间为 ISO 格式：\n\n```typescript\nconst raw = readFileSync(path, \"utf8\");\nconst { frontmatter, body } = parseFrontmatter(raw);\nreturn {\n id, path, frontmatter, body,\n updated: toIsoDate(frontmatter.updated ?? frontmatter.created)\n};\n```\n\n资料来源：[src/core/pages.ts:20-27]()\n\n### 索引系统（index）\n\n索引系统是 stoa 的核心组件，负责维护页面元数据的索引以支持高效查询。\n\n```mermaid\ngraph TD\n A[VaultIndex] --> B[pages]\n A --> C[wikis]\n A --> D[links]\n A --> E[profiles]\n A --> F[tokens]\n```\n\n索引数据结构 `VaultIndex` 包含以下子索引：\n\n| 索引 | 用途 |\n|------|------|\n| `pages` | 所有页面的元数据数组 |\n| `wikis` | wiki 列表及其配置 |\n| `links` | 页面间链接关系 |\n| `profiles` | profile 相关数据 |\n| `tokens` | 全文搜索令牌索引 |\n\n查询支持多维度过滤：\n\n```typescript\nif (f.wiki && wikiSet && !wikiSet.has(p.wiki)) return false;\nif (f.type && p.type !== f.type) return false;\nif (f.channel && p.channel !== f.channel) return false;\nif (f.layer && f.layer !== \"all\") {\n const set = f.layer === \"knowledge\" ? KNOWLEDGE_TYPES : EXECUTION_TYPES;\n if (!set.includes(p.type)) return false;\n}\n```\n\n资料来源：[src/core/index.ts:1-50]()\n\n### 维基链接解析（wikilinks）\n\n维基链接是 stoa 实现页面间关联的核心机制，支持 `[[wikis/<wiki>/<type>/<id>(|alias)]]` 格式的链接。\n\n```mermaid\ngraph TD\n A[markdown 内容] --> B[wikilinkExtractor]\n B --> C{代码块检查}\n C -->|顶层代码块| D[跳过]\n C -->|普通内容| E[正则匹配]\n E --> F[WikilinkRef]\n \n F --> G[body]\n F --> H[frontmatter]\n```\n\n解析结果 `WikilinkRef` 接口定义：\n\n| 字段 | 类型 | 说明 | 来源 |\n|------|------|------|------|\n| `raw` | string | 原始链接文本 | body 或 frontmatter |\n| `wiki` | string | wiki 名称 | 路径解析 |\n| `type` | string | 页面类型 | 路径解析 |\n| `id` | string | 页面 ID | 路径解析 |\n| `alias` | string? | 可选别名 | 管道后文本 |\n| `source` | \"body\" \\| \"frontmatter\" | 链接来源位置 | 提取位置 |\n\n资料来源：[src/core/wikilinks.ts:1-40]()\n\n代码块感知：顶层代码块（行首的 ``` ）内的链接会被跳过，但嵌套在列表项中的缩进代码块不会被剥离。\n\n### 合成系统（synthesize）\n\n合成功能用于将多个相关页面聚合成一篇综合性的 synthesis 页面。\n\n```mermaid\ngraph TD\n A[输入: topic/by_agent] --> B[查询候选页面]\n B --> C[按类型过滤]\n C --> D[构建 synthesis 元数据]\n D --> E[生成 summary]\n E --> F[写入 synthesis 页面]\n```\n\n合成的页面元数据包含：\n\n| 字段 | 示例值 |\n|------|--------|\n| `type` | synthesis |\n| `wiki` | 目标 wiki |\n| `status` | draft |\n| `tags` | 根据作用域确定 |\n| `sources` | 来源页面的 wikilink 数组 |\n| `last_compiled` | ISO 日期 |\n| `scope` | \"memory\"（可选） |\n\n资料来源：[src/core/synthesize.ts:1-80]()\n\n### 合成陈旧度追踪（syntheses）\n\n系统追踪合成页面的陈旧程度，基于 `last_compiled` 时间戳计算滞后期。\n\n```mermaid\ngraph TD\n A[所有 synthesis 页面] --> B[读取 last_compiled]\n B --> C{时间戳存在?}\n C -->|是| D[计算 lag_days]\n D --> E{超过 min_lag_days?}\n E -->|是| F[加入结果集]\n C -->|否| G[标记为从未编译]\n E -->|否| H[过滤掉]\n```\n\n陈旧度数据结构 `SynthesisStaleness` 包含：\n\n- `pageId`: 页面标识\n- `wiki`: 所属 wiki\n- `lastCompiled`: ISO 日期或 null\n- `lagDays`: 自上次编译以来的天数或 null\n\n资料来源：[src/core/syntheses.ts:1-60]()\n\n### Family 解析（family）\n\nFamily 是 wiki 的上层组织单元，支持多 wiki 的批量操作。\n\n```mermaid\ngraph TD\n A[FamilyResolveCtx] --> B{解析优先级}\n B --> C[1. 显式 familyArg]\n B --> D[2. ctx.defaultFamily]\n B --> E[3. .active-family 文件]\n B --> F[4. 返回 null]\n \n C --> G{类型检查}\n G -->|wikiArg 存在| H[FamilyMismatchError]\n G -->|仅 familyArg| I[返回 familyArg]\n```\n\n解析上下文 `FamilyResolveCtx`：\n\n```typescript\ninterface FamilyResolveCtx {\n vaultPath: string;\n defaultFamily?: string;\n}\n```\n\n资料来源：[src/core/family.ts:1-50]()\n\n### 语法检查系统（lint-checks）\n\nlint 系统提供多维度的页面质量检查。\n\n#### 主要检查规则\n\n| 检查规则 | 严重程度 | 说明 |\n|----------|----------|------|\n| SYNTHESIS_DEBT | warn | 标记缺乏对应 synthesis 的硬知识聚类 |\n| CLAIM_WITH_NO_SCOPE | warn | 标记无作用域的 claim 页面 |\n| ACTIVE_WIKI_DIVERGENCE | info | 提示 defaultWiki 与 .active-wiki 不一致 |\n\n#### SYNTHESIS_DEBT 详解\n\n该检查识别满足以下条件的硬知识聚类：\n\n1. 至少 N 个（默认 3）页面共享同一 tag\n2. 这些页面都属于\"硬知识\"类型（concept、decision、spec）\n3. 该 wiki 下没有任何 synthesis 页面使用该 tag\n\n```typescript\nconst HARD_KNOWLEDGE_TYPES = new Set([\"concept\", \"decision\", \"spec\"]);\nconst DEFAULT_MIN_CLUSTER_SIZE = 3;\n```\n\n资料来源：[src/core/lint-checks/synthesis-debt.ts:1-50]()\n\n### 前端matter 模式（frontmatter）\n\n系统定义了严格的前端matter 验证模式。\n\n#### 页面类型（NoteType）\n\n```typescript\nexport const NoteType = z.enum([\n \"concept\", \"guide\", \"decision\", \"source\",\n \"idea\", \"question\", \"journal\", \"move\",\n \"claim\", \"map\", \"synthesis\"\n]);\n```\n\n#### 页面状态（PageStatus）\n\n```typescript\nexport const PageStatus = z.enum([\n \"draft\", \"active\", \"accepted\", \"superseded\", \"archived\"\n]);\n```\n\n#### 置信度（Confidence）\n\n```typescript\nexport const Confidence = z.enum([\"high\", \"medium\", \"low\"]);\n```\n\n#### 编排优先级（CurationPriority）\n\n用于标记需要人工关注的草案页面：\n\n```typescript\nexport const CurationPriority = z.enum([\"high\", \"medium\", \"low\"]);\n```\n\n资料来源：[src/core/frontmatter.ts:1-50]()\n\n### 技能平台（skills-platform）\n\n技能平台管理技能的部署和漂移检测。\n\n```mermaid\ngraph TD\n A[DriftDeployment] --> B[detectDriftAt]\n B --> C{文件状态}\n C -->|canonical 缺失| D[抛出错误]\n C -->|deployed 缺失| E[kind: missing]\n C -->|哈希不匹配| F[kind: hash-mismatch]\n C -->|哈希匹配| G[无报告]\n```\n\n检测规则：\n\n| 情况 | 处理方式 |\n|------|----------|\n| canonical 缺失 | 抛出异常（vault 完整性问题） |\n| deployed 缺失 | 报告 `kind: \"missing\"` |\n| 哈希不匹配 | 报告 `kind: \"hash-mismatch\"` |\n| 哈希匹配 | 不报告 |\n\n技能文件路径约定：\n\n- **canonical**: `<vaultPath>/wikis/_agents/moves/<moveId>/SKILL.md`\n- **deployed**: `<deployment.skills_dir>/<moveId>/SKILL.md`\n\n资料来源：[src/core/skills-platform.ts:1-60]()\n\n### MCP 服务（transport/stdio）\n\nMCP 服务通过 stdio 传输层提供工具接口。\n\n```mermaid\ngraph TD\n A[stdio 输入] --> B[JSON-RPC 解析]\n B --> C[工具路由]\n C --> D[profile-register]\n C --> E[其他工具]\n D --> F[StadiumClient]\n F --> G[平台 API]\n D --> H[更新 frontmatter]\n C --> I[返回 JSON-RPC 响应]\n```\n\n服务启动时通过 `walkInitablePaths` 预热状态缓存：\n\n```typescript\nfunction walkInitablePaths(vaultPath: string): string[] {\n // 递归遍历 wikis/ 目录\n // 返回所有 .md 文件路径\n // 用于构建初始状态\n}\n```\n\n资料来源：[src/transport/stdio.ts:1-60]()\n\n### 状态缓存（eventbus/state-cache）\n\n状态缓存为事件处理提供内存状态存储。\n\n```typescript\nclass StateCache {\n private states = new Map<string, unknown>();\n \n private key(source: string, wiki: string, id: string): string {\n return `${source}:${wiki}:${id}`;\n }\n}\n```\n\n缓存键格式：`source:wiki:id`，支持按源、wiki、ID 三维定位状态。\n\n资料来源：[src/core/eventbus/state-cache.ts:1-30]()\n\n### 工具注册（tools/profile-register）\n\nprofile-register 工具将 profile 页面注册到 Stadium 平台。\n\n流程：\n\n1. 读取 `wikis/<wiki>/profiles/<profile_id>.md`\n2. 提取 `pokemon` 或 `species_name` 字段\n3. POST 到 `/profiles/register`\n4. 更新文件的 `platform_profile_id` 和 `platform_stats`\n\n资料来源：[src/tools/profile-register.ts:1-50]()\n\n## CLI 命令\n\n系统通过 commander 提供命令行接口：\n\n| 命令 | 功能 |\n|------|------|\n| `new-wiki <name>` | 创建新 wiki，需指定 `--mode` 和 `--scope` |\n\n创建 wiki 时的模式选项：\n\n- `idea-map`\n- `project-doc`\n- `learning`\n- `mixed`\n\n资料来源：[src/cli/commands/new-wiki.ts:1-30]()\n\n## 页面类型对应文件命名\n\n| 类型 | 文件命名规则 |\n|------|-------------|\n| concept, guide, source, idea, question, claim, synthesis | `<type>-<slug>.md` |\n| decision | `decision-YYYY-MM-DD-<slug>.md` |\n| journal | `journal-YYYY-MM-DD-HHMM-<slug>.md` |\n| move | `<move>/SKILL.md`（目录） |\n| map | `map.md`（固定名称） |\n\n资料来源：[src/core/ids.ts:1-30]()\n\n## 总结\n\nstoa 是一个功能完备的知识库管理系统，其核心价值在于：\n\n1. **文件系统优先**：所有数据以标准 markdown 文件存储，便于版本控制和人工编辑\n2. **结构化索引**：通过前端matter 和索引提供高效的元数据查询\n3. **链接驱动**：通过 wikilink 实现页面间的语义关联\n4. **质量保障**：多层 lint 检查确保知识库的一致性\n5. **工具扩展**：MCP 架构支持与其他系统的集成\n\n系统的设计遵循单一职责原则，各模块边界清晰，便于维护和扩展。\n\n---\n\n<a id='concepts'></a>\n\n## 核心概念\n\n### 相关页面\n\n相关主题：[项目概述](#overview), [Wiki管理](#wiki-management)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/core/index.ts](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts)\n- [src/core/pages.ts](https://github.com/BrettNye/stoa/blob/main/src/core/pages.ts)\n- [src/core/frontmatter.ts](https://github.com/BrettNye/stoa/blob/main/src/core/frontmatter.ts)\n- [src/core/wikilinks.ts](https://github.com/BrettNye/stoa/blob/main/src/core/wikilinks.ts)\n- [src/core/channel.ts](https://github.com/BrettNye/stoa/blob/main/src/core/channel.ts)\n- [src/core/family.ts](https://github.com/BrettNye/stoa/blob/main/src/core/family.ts)\n- [src/core/synthesize.ts](https://github.com/BrettNye/stoa/blob/main/src/core/synthesize.ts)\n- [src/core/syntheses.ts](https://github.com/BrettNye/stoa/blob/main/src/core/syntheses.ts)\n</details>\n\n# 核心概念\n\nStoa 是一个知识管理 MCP (Model Context Protocol) 服务器，旨在对笔记库 (vault) 进行索引、检索和一致性检查。以下文档详细介绍其核心概念与架构。\n\n## 页面类型系统\n\nStoa 采用结构化的页面类型体系，每种类型具有特定语义和存储约定。\n\n### 页面类型定义\n\n根据 `src/core/frontmatter.ts` 的定义，核心页面类型包括：\n\n| 类型 | 语义 | 文件命名规则 |\n|------|------|-------------|\n| `concept` | 概念性知识 | `concept-<slug>.md` |\n| `decision` | 决策记录 | `decision-YYYY-MM-DD-<slug>.md` |\n| `journal` | 日志条目 | `journal-YYYY-MM-DD-HHMM-<slug>.md` |\n| `guide` | 操作指南 | `guide-<slug>.md` |\n| `source` | 外部引用 | `source-<slug>.md` |\n| `idea` | 想法 | `idea-<slug>.md` |\n| `question` | 问题 | `question-<slug>.md` |\n| `spec` | 规格说明 | `spec-<slug>.md` |\n| `synthesis` | 综合页面 | `synthesis-<slug>.md` |\n| `move` | 技能移动 | `move-<slug>/SKILL.md` (目录结构) |\n| `map` | 维基地图 | `map.md` (固定文件名) |\n\n资料来源：[src/core/frontmatter.ts:1-30]()\n\n### 页面状态\n\n页面状态使用枚举定义：\n\n```typescript\nexport const PageStatus = z.enum([\n \"draft\", \"active\", \"accepted\", \"superseded\", \"archived\"\n]);\n```\n\n- **draft**: 草稿状态\n- **active**: 活跃状态\n- **accepted**: 已接受\n- **superseded**: 已替代\n- **archived**: 已归档\n\n资料来源：[src/core/frontmatter.ts:35-37]()\n\n### 置信度等级\n\n```typescript\nexport const Confidence = z.enum([\"high\", \"medium\", \"low\"]);\n```\n\n资料来源：[src/core/frontmatter.ts:39-40]()\n\n### 整理优先级\n\n用于标记草稿页面的整理优先级，帮助人类注意力分配：\n\n```typescript\nexport const CurationPriority = z.enum([\"high\", \"medium\", \"low\"]);\n```\n\n资料来源：[src/core/frontmatter.ts:48-49]()\n\n## 维基与家族体系\n\n### Wiki 结构\n\nStoa 使用多 Wiki 架构，每个 Wiki 存储在 `vaultPath/wikis/<wiki>/` 目录下。\n\n### 家族解析顺序\n\n`src/core/family.ts` 定义了家族 (family) 解析的优先级：\n\n1. 显式 `familyArg` 参数\n2. MCP CLI 参数 `--default-family`\n3. `vaultPath/.active-family` 文件\n4. `null` → 回退到单 Wiki 解析\n\n```typescript\nexport function resolveFamily(\n ctx: FamilyResolveCtx,\n familyArg?: string,\n wikiArg?: string,\n knownWikis?: Record<string, { family?: string | null }>\n): string | null\n```\n\n资料来源：[src/core/family.ts:38-58]()\n\n### Wiki 与家族校验\n\n当同时提供 `familyArg` 和 `wikiArg` 时，系统会校验 Wiki 所属家族是否匹配：\n\n```typescript\nif (wikiFamily !== familyArg) {\n throw new FamilyMismatchError(\n `wiki '${wikiArg}' has family '${wikiFamily ?? \"(none)\"}' which does not match requested family '${familyArg}'`\n );\n}\n```\n\n资料来源：[src/core/family.ts:47-51]()\n\n## Wiki 链接系统\n\n### Wikilink 格式\n\nWiki 链接采用标准化格式：\n\n```\n[[wikis/<wiki>/<type>/<id>(|alias)?]]\n```\n\n例如：`[[wikis/_meta/concepts/concept-trust-gradient-axes]]`\n\n### Wikilink 提取器\n\n`src/core/wikilinks.ts` 提供了结构化的链接引用接口：\n\n```typescript\nexport interface WikilinkRef {\n raw: string;\n wiki: string;\n type: string;\n id: string;\n alias?: string;\n source: \"body\" | \"frontmatter\";\n}\n```\n\n资料来源：[src/core/wikilinks.ts:22-29]()\n\n### 代码块感知\n\nWikilink 提取器具有代码块感知能力：\n\n- 顶层 fenced 代码块 (` ``` `) 内的链接会被跳过\n- 缩进代码块（如列表项内的 4 空格缩进）**不会**被剥离\n- 内联单反引号代码 span **不会**被剥离\n\n资料来源：[src/core/wikilinks.ts:24-34]()\n\n### Wikilink 职责分离\n\n- **提取职责** (`wikilinks.ts`)：仅提取结构化链接引用\n- **完整性检查** (`lint-checks/cross-wiki-link-broken.ts`)：检查目标页面是否存在\n\n资料来源：[src/core/wikilinks.ts:14-16]()\n\n## 页面索引与查询\n\n### VaultIndex 结构\n\n索引文件 `_index/pages.json` 存储所有页面的元数据：\n\n```typescript\ninterface VaultIndex {\n pages: IndexedPage[];\n wikis: IndexedWiki[];\n}\n```\n\n资料来源：[src/core/index.ts:1-50]()\n\n### 页面查询\n\n使用 `queryPages` 函数进行多条件过滤：\n\n```typescript\nexport function queryPages(\n idx: VaultIndex,\n f: PageFilter\n): IndexedPage[]\n```\n\n支持的过滤条件：\n\n| 过滤器字段 | 说明 |\n|-----------|------|\n| `wiki` | Wiki 名称精确匹配 |\n| `wikis` | Wiki 名称集合 |\n| `type` | 页面类型精确匹配 |\n| `channel` | 频道名称精确匹配 |\n| `status` | 页面状态精确匹配 |\n| `layer` | `\"knowledge\"` 或 `\"execution\"` 或 `\"all\"` |\n\n资料来源：[src/core/index.ts:80-95]()\n\n### 全文搜索\n\n`upsertTokenize` 函数使用 Porter Stemmer 进行词干提取和停用词过滤：\n\n```typescript\nconst UPSERT_STOP_WORDS = new Set([\n \"the\",\"and\",\"of\",\"a\",\"an\",\"in\",\"to\",\"is\",\"for\",\"on\",\n \"with\",\"as\",\"at\",\"by\",\"or\",\"be\",\"this\",\"that\",\"it\",\n \"from\",\"are\",\"was\",\"were\",\"not\",\"but\",\"if\"\n]);\n```\n\n资料来源：[src/core/index.ts:65-67]()\n\n## 页面读写操作\n\n### 读取页面\n\n`readPage` 函数根据 ID 解析页面路径：\n\n```typescript\nexport function readPage(\n vaultPath: string,\n wiki: string,\n id: string\n): ReadPageResult\n```\n\n路径解析顺序：\n1. `wikis/<wiki>/<type>/<id>.md` (按类型遍历)\n2. `map-<wiki>.md` 或 `map.md`\n\n资料来源：[src/core/pages.ts:40-80]()\n\n### 写入页面\n\n```typescript\nexport interface WritePageInput {\n id: string;\n type: NoteType;\n wiki: string;\n frontmatter: Record<string, any>;\n body: string;\n expectedUpdated?: string; // 乐观锁\n}\n\nexport function writePage(\n vaultPath: string,\n input: WritePageInput\n): WritePageResult\n```\n\n**乐观锁机制**：若提供 `expectedUpdated`，系统会验证现有文件的 updated 时间戳，防止并发覆盖。\n\n资料来源：[src/core/pages.ts:82-100]()\n\n## 频道系统\n\n### 频道日志\n\n频道 (channel) 用于聚合 `journal` 类型页面的活动摘要：\n\n```typescript\ninterface ChannelSummary {\n name: string;\n wiki: string;\n lastEntry: ChannelEntry | null;\n count24h: number;\n}\n```\n\n资料来源：[src/core/channel.ts:20-24]()\n\n### 频道条目\n\n```typescript\ninterface ChannelEntry {\n id: string;\n channel: string;\n wiki: string;\n author: string;\n ts: string;\n excerpt: string; // 前 240 字符\n pageId: string;\n}\n```\n\n资料来源：[src/core/channel.ts:26-33]()\n\n## 综合页面 (Synthesis)\n\n### Synthesis 创建\n\n`synthesize` 命令生成综合页面：\n\n```typescript\nconst fm: Record<string, any> = {\n id,\n title: `${input.topic} — synthesis`,\n type: \"synthesis\",\n wiki,\n status: \"draft\",\n created: today,\n updated: today,\n summary: `Synthesis of ${inputIds.length} pages on \"${input.topic}\".`,\n tags: [],\n last_compiled: today,\n sources: inputIds.map(i => `[[wikis/${wiki}/${typeFolderForId(i)}/${i}]]`)\n};\n```\n\n资料来源：[src/core/synthesize.ts:60-75]()\n\n### Synthesis 陈旧度检测\n\n`detectSynthesisStaleness` 函数计算页面\"过时\"程度：\n\n```typescript\nif (lastCompiled) {\n const compiledMs = new Date(lastCompiled).getTime();\n lagDays = Math.floor((now - compiledMs) / MS_PER_DAY);\n}\n```\n\n资料来源：[src/core/syntheses.ts:55-58]()\n\n### Synthesis 债务检测\n\n当同标签的硬知识页面聚类缺少对应的综合页面时，触发警告：\n\n```typescript\nexport const DEFAULT_MIN_CLUSTER_SIZE = 3;\n\nconst HARD_KNOWLEDGE_TYPES = new Set([\n \"concept\", \"decision\", \"spec\"\n]);\n```\n\n资料来源：[src/core/synthesize.ts:30-40]()\n\n## 标记渲染系统\n\n### 托管区域契约\n\nMarker 系统用于在文档中维护\"托管区域\"：\n\n- **起始标记**: `<!-- markerName:start (rendered: YYYY-MM-DD, half-life: Nd) -->`\n- **结束标记**: `<!-- markerName:end -->`\n- **幂等性**: 相同输入产生字节级相同的输出\n\n```typescript\nexport interface MarkerOptions {\n renderedDate?: string; // ISO 日期\n halfLifeDays?: number; // 半衰期（天）\n}\n```\n\n资料来源：[src/core/marker-render.ts:20-24]()\n\n### 使用场景\n\n- **Claims 汇总** (`synthesize`)\n- **技能/代理文档补丁** (`sync-skills`, `bootstrap-repo`)\n\n资料来源：[src/core/marker-render.ts:6-10]()\n\n## 状态缓存\n\n`StateCache` 提供简单的内存状态缓存：\n\n```typescript\nexport class StateCache {\n private states = new Map<string, unknown>();\n\n private key(source: string, wiki: string, id: string): string {\n return `${source}:${wiki}:${id}`;\n }\n\n get<T>(source: string, wiki: string, id: string): T | undefined;\n set<T>(source: string, wiki: string, id: string, state: T): void;\n has(source: string, wiki: string, id: string): boolean;\n size(): number;\n}\n```\n\n资料来源：[src/core/eventbus/state-cache.ts:1-25]()\n\n### MCP 预热机制\n\n`walkInitablePaths` 函数在接收变更事件前预热状态缓存：\n\n```typescript\nfunction walkInitablePaths(vaultPath: string): string[] {\n // 遍历 wikis/ 目录，收集所有 .md 文件路径\n}\n```\n\n资料来源：[src/core/stdio.ts:50-75]()\n\n## 命名规范\n\n### ID 格式\n\n| 类型 | ID 格式要求 |\n|------|-------------|\n| 普通页面 | 小写字母、数字、连字符 `^[a-z0-9-]+$` |\n| Channel | 小写 kebab-case `^[a-z0-9]+(-[a-z0-9]+)*$` |\n| 日期 | ISO 格式 `^\\d{4}-\\d{2}-\\d{2}$` |\n\n资料来源：[src/core/frontmatter.ts:41-44]()\n\n## 架构总览\n\n```mermaid\ngraph TD\n subgraph \"MCP 接口层\"\n STDIO[STDIO 传输]\n MCP[MCP 服务器]\n end\n\n subgraph \"核心处理层\"\n IDX[索引系统]\n QUERY[查询引擎]\n LINT[Lint 检查]\n SYNC[同步引擎]\n end\n\n subgraph \"存储层\"\n PAGES[Pages 读写]\n FRONT[Frontmatter 解析]\n WIKI[Wikilinks]\n CHAN[Channel]\n end\n\n subgraph \"文件系统\"\n VAULT[Vault 目录]\n WIKIS[wikis/ 目录]\n INDEX[_index/ 目录]\n end\n\n STDIO --> MCP\n MCP --> IDX\n IDX --> QUERY\n IDX --> LINT\n SYNC --> PAGES\n PAGES --> FRONT\n PAGES --> WIKI\n IDX --> CHAN\n QUERY --> INDEX\n IDX --> VAULT\n VAULT --> WIKIS\n IDX --> INDEX\n```\n\n## 术语表\n\n| 术语 | 定义 |\n|------|------|\n| **Vault** | 根目录下的笔记库，包含 wikis/ 和 _index/ |\n| **Wiki** | 某个主题领域的页面集合，位于 `wikis/<wiki>/` |\n| **Family** | Wiki 的分组，用于批量操作 |\n| **Synthesis** | 综合页面，聚合多个同标签页面的内容 |\n| **Hard Knowledge** | 核心知识类型 (concept, decision, spec) |\n| **Soft Knowledge** | 非核心类型 (guide, source, idea, question) |\n| **Marker** | 托管区域的边界标记 |\n| **Channel** | 聚合日志条目的频道 |\n\n---\n\n<a id='architecture'></a>\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[传输层实现](#transport), [事件总线系统](#eventbus), [项目概述](#overview)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/core/index.ts](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts)\n- [src/core/start.ts](https://github.com/BrettNye/stoa/blob/main/src/core/start.ts)\n- [src/core/pages.ts](https://github.com/BrettNye/stoa/blob/main/src/core/pages.ts)\n- [src/core/synthesize.ts](https://github.com/BrettNye/stoa/blob/main/src/core/synthesize.ts)\n- [src/core/family.ts](https://github.com/BrettNye/stoa/blob/main/src/core/family.ts)\n- [src/core/lint.ts](https://github.com/BrettNye/stoa/blob/main/src/core/lint.ts)\n- [src/core/frontmatter.ts](https://github.com/BrettNye/stoa/blob/main/src/core/frontmatter.ts)\n- [src/transport/stdio.ts](https://github.com/BrettNye/stoa/blob/main/src/transport/stdio.ts)\n- [src/core/skills-platform.ts](https://github.com/BrettNye/stoa/blob/main/src/core/skills-platform.ts)\n- [src/core/rewrite-links.ts](https://github.com/BrettNye/stoa/blob/main/src/core/rewrite-links.ts)\n</details>\n\n# 系统架构\n\n## 概述\n\nStoa 是一个基于 Model Context Protocol (MCP) 的知识库管理系统，通过 STDIO 传输层与 LLM 代理进行通信。其核心功能围绕**页面索引**、**合成（Synthesis）管理**、**代码检查（Lint）** 和**技能平台**四大模块展开。系统采用 vault 结构的 Markdown 文件存储，页面之间通过 wikilink 互相引用，形成一个自包含的知识图谱。资料来源：[src/transport/stdio.ts:30-35]()\n\n## 核心设计理念\n\nStoa 采用单职责原则设计，各模块职责明确划分：\n\n| 模块 | 职责 | 核心文件 |\n|------|------|----------|\n| 索引系统 | 页面元数据提取、全文搜索、token 管理 | `src/core/index.ts` |\n| 页面操作 | 页面读写、路径解析、版本控制 | `src/core/pages.ts` |\n| 合成引擎 | 多页面聚合、摘要生成、来源追踪 | `src/core/synthesize.ts` |\n| Lint 系统 | 规则检查、诊断报告、错误修复 | `src/core/lint.ts` |\n| 技能平台 | 技能部署、漂移检测、版本管理 | `src/core/skills-platform.ts` |\n| 家族解析 | 多 wiki 聚合、家族范围查询 | `src/core/family.ts` |\n\n资料来源：[src/core/index.ts:1-50]()\n\n## 系统层次架构\n\n```mermaid\ngraph TD\n subgraph 传输层[\"传输层 (Transport)\"]\n STDIO[STDIO Server Transport]\n end\n \n subgraph 服务层[\"服务层 (Service)\"]\n MCP[MCP Server]\n Tools[Tools Layer]\n end\n \n subgraph 核心业务[\"核心业务 (Core)\"]\n Index[索引系统]\n Pages[页面管理]\n Synthesize[合成引擎]\n Lint[代码检查]\n Skills[技能平台]\n Family[家族解析]\n end\n \n subgraph 数据层[\"数据层 (Data)\"]\n Vault[Vault 存储]\n IndexFiles[_index 索引文件]\n Frontmatter[Frontmatter 元数据]\n end\n \n STDIO --> MCP\n MCP --> Tools\n Tools --> Index\n Tools --> Pages\n Tools --> Synthesize\n Tools --> Lint\n Tools --> Skills\n Tools --> Family\n \n Index --> IndexFiles\n Pages --> Vault\n Synthesize --> Index\n Lint --> Index\n```\n\n## 索引系统\n\n### 索引数据结构\n\n系统维护多个索引文件用于快速查询：\n\n```mermaid\ngraph LR\n subgraph _index[\"_index/ 目录\"]\n PagesIdx[_index/pages.json]\n TokensIdx[_index/tokens.json]\n LinksIdx[_index/links.json]\n WikisIdx[_index/wikis.json]\n ProfilesIdx[_index/profiles.json]\n end\n \n subgraph 源数据[\"Vault 源文件\"]\n Markdown[*.md 文件]\n Frontmatter[Frontmatter]\n end\n \n Markdown -->|解析| Frontmatter\n Frontmatter -->|提取| PagesIdx\n Frontmatter -->|分词| TokensIdx\n Frontmatter -->|链接提取| LinksIdx\n WikisIdx -->|Wiki 配置| ProfilesIdx\n```\n\n索引系统通过 `VaultIndex` 接口提供统一的数据访问：\n\n```typescript\nexport interface VaultIndex {\n pages: IndexedPage[];\n wikis: IndexedWiki[];\n profiles: IndexedProfile[];\n links: IndexedLink[];\n tokens: Record<string, string[]>;\n}\n```\n\n资料来源：[src/core/index.ts:1-30]()\n\n### 页面类型体系\n\nStoa 定义了严格的页面类型系统：\n\n| 类型 | 说明 | 文件命名规范 |\n|------|------|-------------|\n| `concept` | 概念页面 | `concept-<slug>.md` |\n| `decision` | 决策记录 | `decision-YYYY-MM-DD-<slug>.md` |\n| `guide` | 操作指南 | `guide-<slug>.md` |\n| `source` | 外部引用 | `source-<slug>.md` |\n| `idea` | 想法记录 | `idea-<slug>.md` |\n| `question` | 问题记录 | `question-<slug>.md` |\n| `journal` | 日志条目 | `journal-YYYY-MM-DD-HHMM-<slug>.md` |\n| `move` | 技能移动 | `move-<slug>/SKILL.md` |\n| `map` | 地图页面 | `map.md` (固定命名) |\n| `synthesis` | 合成页面 | 自动生成 |\n\n资料来源：[src/core/ids.ts:1-25]()\n\n### 搜索与查询\n\n系统支持多维度查询过滤：\n\n```typescript\nexport interface PageFilter {\n wiki?: string;\n type?: NoteType;\n channel?: string;\n status?: PageStatus;\n layer?: \"knowledge\" | \"execution\" | \"all\";\n}\n```\n\n全文搜索使用 Porter Stemmer 算法进行词干提取，支持停用词过滤：\n\n```typescript\nfunction upsertTokenize(text: string): string[] {\n return text.toLowerCase()\n .replace(/[^a-z0-9\\s]/g, \" \")\n .split(/\\s+/)\n .filter(t => t.length > 1 && !UPSERT_STOP_WORDS.has(t))\n .map(t => upsertStemmer.stem(t));\n}\n```\n\n资料来源：[src/core/index.ts:35-50]()\n\n## 页面管理系统\n\n### 页面读写流程\n\n```mermaid\ngraph TD\n A[请求读写页面] --> B{页面是否存在}\n B -->|不存在| C[新建页面]\n B -->|存在| D{是否有 expectedUpdated}\n D -->|有| E[乐观锁检查]\n E -->|版本匹配| F[写入文件]\n E -->|版本不匹配| G[抛出错误]\n D -->|无| F\n C --> H[生成路径]\n F --> I[更新索引]\n H --> I\n```\n\n### 页面路径解析\n\n路径生成遵循以下规则：\n\n| 页面类型 | 路径模板 |\n|----------|----------|\n| 普通页面 | `wikis/{wiki}/{type}/{id}.md` |\n| 地图页面 | `wikis/{wiki}/map.md` |\n| 技能移动 | `wikis/_agents/moves/{id}/SKILL.md` |\n| 技能档案 | `wikis/_agents/profiles/{id}.md` |\n\n资料来源：[src/core/pages.ts:1-60]()\n\n## Frontmatter 验证\n\n### 验证模式\n\n系统使用 Zod 进行运行时验证：\n\n```typescript\nconst draftSchema = z.object({\n id: z.string().regex(/^[a-z0-9-]+$/),\n title: z.string().min(1),\n type: NoteType,\n created: z.string().regex(ISO_DATE),\n channel: z.string().regex(KEBAB).optional(),\n});\n\nexport const PageStatus = z.enum([\n \"draft\", \"active\", \"accepted\", \"superseded\", \"archived\"\n]);\n\nexport const Confidence = z.enum([\"high\", \"medium\", \"low\"]);\n\nexport const CurationPriority = z.enum([\"high\", \"medium\", \"low\"]);\n```\n\n资料来源：[src/core/frontmatter.ts:1-50]()\n\n### 状态流转\n\n| 状态 | 说明 | 允许的转换 |\n|------|------|------------|\n| `draft` | 草稿状态 | `active` |\n| `active` | 活跃状态 | `accepted`, `archived` |\n| `accepted` | 已接受 | `superseded`, `archived` |\n| `superseded` | 已废弃 | 无 |\n| `archived` | 归档 | 无 |\n\n## 合成引擎\n\n### 合成类型\n\n系统支持两种合成模式：\n\n| 模式 | 说明 | 生成条件 |\n|------|------|----------|\n| `topic` | 主题合成 | 按标签聚合相关页面 |\n| `memory` | 记忆合成 | 按代理聚合其 authored 页面 |\n\n### 合成数据结构\n\n```mermaid\ngraph TD\n subgraph 合成输入[\"合成输入\"]\n Topic[Topic 标签]\n Tags[多个 Tag]\n Pages[源页面列表]\n end\n \n subgraph 合成过程[\"合成过程\"]\n Extract[提取引用]\n Generate[生成摘要]\n Render[渲染标记区域]\n end\n \n subgraph 合成输出[\"合成输出\"]\n Synthesis[Synthesis 页面]\n Sources[Sources 列表]\n Markers[标记区域]\n end\n \n Topic --> Extract\n Tags --> Extract\n Pages --> Extract\n Extract --> Generate\n Generate --> Render\n Render --> Synthesis\n```\n\n合成页面的 frontmatter 结构：\n\n```yaml\nid: <auto-generated>\ntitle: \"{topic} — synthesis\"\ntype: synthesis\nwiki: <target-wiki>\nstatus: draft\ncreated: <today>\nupdated: <today>\nsummary: \"Synthesis of {count} pages on \\\"{topic}\\\".\"\ntags: [<tags>]\nlast_compiled: <today>\nsources: [wikilinks to source pages]\n```\n\n资料来源：[src/core/synthesize.ts:1-80]()\n\n### 合成陈旧度检测\n\n系统可检测长时间未重新编译的合成页面：\n\n```typescript\nexport interface SynthesisStaleness {\n id: string;\n wiki: string;\n lag_days: number | null;\n last_compiled: string | null;\n}\n```\n\n陈旧度计算基于 `last_compiled` 字段与当前时间的差值：\n\n```typescript\nif (lastCompiled) {\n const compiledMs = new Date(lastCompiled).getTime();\n lagDays = Math.floor((now - compiledMs) / MS_PER_DAY);\n}\n```\n\n资料来源：[src/core/syntheses.ts:1-60]()\n\n## Lint 检查系统\n\n### 检查规则体系\n\n```mermaid\ngraph LR\n subgraph 规则类型[\"规则分类\"]\n Error[Error 级规则]\n Warning[Warning 级规则]\n Info[Info 级规则]\n end\n \n subgraph 检查范围[\"检查范围\"]\n Frontmatter[Frontmatter 检查]\n Content[内容检查]\n Filename[文件名检查]\n Links[链接检查]\n CrossWiki[跨 Wiki 检查]\n end\n \n Frontmatter -->|验证| Error\n Content -->|验证| Warning\n Filename -->|验证| Warning\n Links -->|验证| Info\n```\n\n### 核心检查规则\n\n| 规则代码 | 严重级别 | 说明 |\n|----------|----------|------|\n| `FILENAME_ID_MISMATCH` | warning | 文件名与 ID 不匹配 |\n| `BAD_CHANNEL_FORMAT` | warning | Channel 格式非法（需 kebab-case） |\n| `CLAIM_WITH_NO_SCOPE` | warn | Claim 无作用域定义 |\n| `SYNTHESIS_DEBT` | info | 存在未合成的知识集群 |\n| `SNIPPET_NO_IMPLEMENTATION` | warning | 代码片段缺少实现引用 |\n| `CROSS_WIKI_LINK_BROKEN` | error | 跨 Wiki 链接目标不存在 |\n| `MISSING_CURATION_PRIORITY` | info | Agent 创作的草稿缺少整理优先级 |\n\n资料来源：[src/core/lint.ts:1-100]()\n\n### 特定 Wiki 检查\n\n针对 `_agents` wiki 有专门的检查逻辑：\n\n- **Profile 检查**：验证 profile 页面存在且格式正确\n- **Move 检查**：验证 move 目录结构符合规范（需包含 `SKILL.md`）\n- **别名漂移检查**（ALIAS_DRIFT）：检测 agent 别名与实际页面的不一致\n\n## 技能平台\n\n### 技能部署架构\n\n```mermaid\ngraph TD\n subgraph 源端[\"Vault 源端\"]\n Canonical[Canonical SKILL.md]\n MoveDir[move-{id} 目录]\n end\n \n subgraph 部署端[\"Deployment 端\"]\n DeployDir[部署目录]\n Deployed[Deployed SKILL.md]\n end\n \n subgraph 检测机制[\"漂移检测\"]\n Hash1[源文件哈希]\n Hash2[部署文件哈希]\n Compare[比较结果]\n end\n \n Canonical --> Hash1\n Deployed --> Hash2\n Hash1 --> Compare\n Hash2 --> Compare\n Compare -->|匹配| OK[无需更新]\n Compare -->|不匹配| Drift[报告漂移]\n Compare -->|缺失| Missing[报告缺失]\n```\n\n### 漂移报告类型\n\n| 类型 | 说明 | 触发条件 |\n|------|------|----------|\n| `missing` | 部署端缺失 | 部署目录中无对应 SKILL.md |\n| `hash-mismatch` | 哈希不匹配 | 源文件与部署文件内容不一致 |\n\n```typescript\nexport interface DriftReport {\n move_id: string;\n kind: \"missing\" | \"hash-mismatch\";\n actual_hash: string | undefined;\n}\n```\n\n资料来源：[src/core/skills-platform.ts:1-60]()\n\n## 家族解析系统\n\n### 家族解析优先级\n\n系统按以下顺序解析家族范围：\n\n```mermaid\ngraph TD\n A{是否有显式 family 参数?} -->|是| B[使用显式参数]\n A -->|否| C{是否有 defaultFamily?}\n C -->|是| D[使用 defaultFamily]\n C -->|否| E{是否有 .active-family 文件?}\n E -->|是| F[使用文件内容]\n E -->|否| G[返回 null, 单 Wiki 解析]\n```\n\n### 家族不匹配检测\n\n当同时提供 `family` 和 `wiki` 参数时，系统会验证一致性：\n\n```typescript\nif (wikiFamily !== familyArg) {\n throw new FamilyMismatchError(\n `wiki '${wikiArg}' has family '${wikiFamily}' which does not match requested family '${familyArg}'`\n );\n}\n```\n\n资料来源：[src/core/family.ts:1-50]()\n\n## Wikilink 处理\n\n### 链接格式规范\n\n系统支持 vault-root 绝对路径格式的 wikilink：\n\n```\n[[wikis/{wiki}/{type}/{id}(|alias)?]]\n```\n\n### 链接提取规则\n\n| 场景 | 是否提取 |\n|------|----------|\n| 顶层代码块内链接 | ❌ 跳过 |\n| 嵌套代码块内链接 | ✅ 提取（v1.6 Phase 1 限制） |\n| 单反引号行内代码 | ✅ 提取 |\n| Frontmatter related 数组 | ✅ 提取 |\n\n```typescript\nexport interface WikilinkRef {\n raw: string;\n wiki: string;\n type: string;\n id: string;\n alias?: string;\n source: \"body\" | \"frontmatter\";\n}\n```\n\n资料来源：[src/core/wikilinks.ts:1-30]()\n\n### 链接重写\n\n支持批量前缀重写，保持语义一致性：\n\n```typescript\nexport interface RewriteScope {\n body: boolean;\n frontmatter: boolean;\n}\n\nexport interface PageRewrite {\n page_id: string;\n links_rewritten: number;\n new_body: string;\n new_related: string[] | undefined;\n}\n```\n\n资料来源：[src/core/rewrite-links.ts:1-40]()\n\n## 传输层\n\n### STDIO 服务器\n\n系统通过 STDIO 与 MCP 客户端通信：\n\n```mermaid\ngraph LR\n subgraph MCP客户端[\"MCP Client (LLM Agent)\"]\n JSONRPC[JSON-RPC Requests]\n end\n \n subgraph STDIO传输[\"STDIO Transport\"]\n Stdin[stdin]\n Stdout[stdout]\n Stderr[stderr (日志)]\n end\n \n JSONRPC -->|输入| Stdin\n Stdout -->|输出| JSONRPC\n Stderr -->|诊断| Console\n```\n\n服务器初始化输出：\n\n```\nvault-mcp stdio server ready (vault={path}, default-wiki={wiki}, default-family={family})\n```\n\n资料来源：[src/transport/stdio.ts:1-60]()\n\n## 配置与扩展\n\n### 运行时配置\n\n| 配置项 | 说明 | 来源 |\n|--------|------|------|\n| `vaultPath` | Vault 根目录路径 | 必需参数 |\n| `defaultWiki` | 默认 Wiki 名称 | CLI 参数 |\n| `defaultFamily` | 默认家族名称 | CLI 参数 |\n\n### 扩展机制\n\n- **Marker 渲染**：支持在文件中维护可编辑区域，工具与人类共同编辑\n- **Zod 验证**：所有输入通过 schema 验证，确保类型安全\n- **模块化检查**：Lint 规则以插件形式注册\n\n## 关键技术栈\n\n| 技术 | 用途 |\n|------|------|\n| TypeScript | 核心开发语言 |\n| Zod | 运行时 schema 验证 |\n| Node.js fs 模块 | 文件系统操作 |\n| MCP SDK | 模型上下文协议实现 |\n| Porter Stemmer | 全文搜索分词 |\n\n## 总结\n\nStoa 的系统架构体现了以下设计原则：\n\n1. **单一职责**：每个模块只负责一个明确的领域\n2. **数据与逻辑分离**：索引系统与业务逻辑解耦\n3. **可验证性**：通过 Zod schema 确保数据完整性\n4. **幂等性**：所有写操作均可安全重试\n5. **可观测性**：Lint 系统提供诊断能力\n\n整个系统以 vault 目录为数据源，通过 MCP STDIO 传输层对外提供服务，形成了完整的知识管理闭环。\n\n---\n\n<a id='transport'></a>\n\n## 传输层实现\n\n### 相关页面\n\n相关主题：[系统架构](#architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/transport/stdio.ts](https://github.com/BrettNye/stoa/blob/main/src/transport/stdio.ts)\n- [src/core/eventbus/state-cache.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/state-cache.ts)\n- [src/core/index.ts](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts)\n- [src/core/pages.ts](https://github.com/BrettNye/stoa/blob/main/src/core/pages.ts)\n</details>\n\n# 传输层实现\n\n## 概述\n\nStoa 的传输层是 MCP（Model Context Protocol）服务器与外部客户端之间的通信桥梁，负责处理请求的接收、路由和响应返回。该层采用插件化架构，支持多种传输协议，当前实现包括 STDIO 标准输入输出传输和 HTTP 传输两种模式。\n\n传输层的核心职责：\n\n- 初始化并管理 MCP 服务器连接\n- 预热状态缓存以支持增量事件处理\n- 处理文件系统变化事件并维护索引一致性\n- 提供可插拔的传输适配器接口\n\n资料来源：[src/transport/stdio.ts:1-20]()\n\n## 架构设计\n\n### 传输类型概览\n\n| 传输类型 | 用途 | 特点 |\n|---------|------|------|\n| STDIO | 本地 CLI 集成 | 进程间通信，低延迟，适合桌面工具 |\n| HTTP | 远程服务 | 支持网络访问，适合服务器部署 |\n| UI Routes | Web 界面 | 提供读写路由的 HTTP 端点 |\n\n### 状态缓存机制\n\n传输层依赖 `StateCache` 类实现内存状态缓存，用于在处理文件系统变更事件时提供基准状态对比。\n\n```mermaid\ngraph TD\n A[文件系统变更] --> B{StateCache.has?}\n B -->|是| C[获取历史状态]\n B -->|否| D[返回 undefined]\n C --> E[计算差异]\n E --> F[触发增量更新]\n D --> G[处理初始事件]\n```\n\n**StateCache 关键方法：**\n\n| 方法 | 签名 | 说明 |\n|------|------|------|\n| get | `<T>(source, wiki, id) => T \\| undefined` | 按复合键获取缓存状态 |\n| set | `<T>(source, wiki, id, state) => void` | 存储状态到缓存 |\n| has | `(source, wiki, id) => boolean` | 检查键是否存在 |\n| size | `() => number` | 返回缓存条目总数 |\n\n复合键格式：`${source}:${wiki}:${id}`，确保不同来源、维基和页面的状态隔离。\n\n资料来源：[src/core/eventbus/state-cache.ts:1-30]()\n\n## STDIO 传输实现\n\n### 工作流程\n\nSTDIO 传输是 Stoa 的主要本地通信方式，通过标准输入/输出流与 MCP 客户端交互。\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Server as StdioServerTransport\n participant Cache as StateCache\n participant Vault as 文件系统\n\n Client->>Server: 连接建立\n Server->>Vault: walkInitablePaths()\n Server->>Cache: 预热缓存\n Note over Cache: 加载历史状态\n Client->>Server: 请求消息\n Server->>Cache: 查询/更新状态\n Server->>Client: 响应消息\n```\n\n### 缓存预热机制\n\n在接收实时事件前，传输层会遍历 `wikis/` 目录结构，将现有文件路径加载到状态缓存中，确保第一次变更事件有有效的基准状态可供对比。\n\n```typescript\nfunction walkInitablePaths(vaultPath: string): string[] {\n const root = join(vaultPath, \"wikis\");\n if (!existsSync(root)) return [];\n \n let entries: Array<{\n isFile(): boolean;\n name: string;\n parentPath?: string;\n path?: string;\n }>;\n \n entries = readdirSync(root, { recursive: true, withFileTypes: true });\n \n const paths: string[] = [];\n for (const e of entries) {\n if (!e.isFile()) continue;\n if (!e.name.endsWith(\".md\")) continue;\n // ... 收集有效路径\n }\n return paths;\n}\n```\n\n**预热流程说明：**\n\n1. 定位 `wikis/` 根目录\n2. 递归遍历目录结构获取所有条目\n3. 过滤仅保留 `.md` 扩展名文件\n4. 将有效路径存入缓存\n\n资料来源：[src/transport/stdio.ts:25-55]()\n\n### 类型兼容性处理\n\n代码对 Node.js v22 的类型定义进行了显式处理：\n\n```typescript\n// @types/node 22 声明 Dirent<NonSharedBuffer> 作为默认值\n// 'name' 在运行时是字符串，但类型表现为 buffer-like\nlet entries: Array<{\n isFile(): boolean;\n name: string;\n parentPath?: string;\n path?: string;\n}>;\n\nentries = readdirSync(root, { recursive: true, withFileTypes: true }) \n as unknown as typeof entries;\n```\n\n此处的类型断言确保了运行时字符串类型与 TypeScript 类型定义的一致性。\n\n资料来源：[src/transport/stdio.ts:40-45]()\n\n## HTTP 传输\n\nHTTP 传输层通过 Web 服务器方式暴露 MCP 服务，支持远程客户端连接。该传输方式适用于将 Stoa 作为独立服务部署的场景。\n\n**HTTP 传输的核心能力：**\n\n- 接受外部 HTTP 请求\n- 路由到对应的工具处理器\n- 返回 JSON 格式响应\n\n> 注：详细 HTTP 传输实现请参考 `src/transport/http.ts`。\n\n## UI 路由层\n\nUI 路由层提供基于 HTTP 的读写接口，供 Web 前端或其他 HTTP 客户端使用。\n\n| 路由文件 | 职责 |\n|---------|------|\n| `routes-read.ts` | 页面读取操作 |\n| `routes-write.ts` | 页面写入操作 |\n| `index.ts` | 路由聚合与中间件 |\n\n> 注：详细路由实现请参考 `src/transport/ui/` 目录。\n\n## 页面路径解析\n\n传输层与核心页面模块协作，将页面 ID 解析为实际文件系统路径：\n\n```typescript\nexport function pathForPage(\n vaultPath: string, \n id: string, \n type: NoteType, \n wiki: string\n): string {\n // 特殊页面类型处理\n if (id === `map-${wiki}` || id === \"map\") {\n return join(vaultPath, \"wikis\", wiki, \"map.md\");\n }\n // 标准页面路径\n return join(vaultPath, \"wikis\", wiki, typeFolderForId(id), `${id}.md`);\n}\n```\n\n资料来源：[src/core/pages.ts:40-55]()\n\n## 索引与缓存协同\n\n传输层的事件处理依赖底层的写穿式索引更新机制：\n\n```mermaid\ngraph LR\n A[变更事件] --> B[upsertPage]\n B --> C[解析 frontmatter]\n C --> D[更新 pages.json]\n D --> E[更新 tokens.json]\n E --> F[StateCache 同步]\n```\n\n索引更新是原子操作，保证了在并发访问下的数据一致性。\n\n资料来源：[src/core/index.ts:80-100]()\n\n## 配置参数\n\n| 参数 | 来源 | 说明 |\n|------|------|------|\n| `vaultPath` | CLI `--vault=` 或 `STOA_VAULT_PATH` | 保险库根目录 |\n| `defaultWiki` | CLI `--default-wiki=` | 默认维基名称 |\n| `defaultFamily` | CLI `--default-family=` | 默认家族名称 |\n\n服务器启动时会输出配置确认信息到 stderr：\n\n```\nvault-mcp stdio server ready (vault=/path/to/vault, default-wiki=<unset>, default-family=<unset>)\n```\n\n资料来源：[src/transport/stdio.ts:20-25]()\n\n## 错误处理\n\n传输层的错误处理策略：\n\n| 场景 | 处理方式 |\n|------|---------|\n| 目录不存在 | 返回空数组 |\n| 读取失败 | 吞没异常并返回空结果 |\n| 文件损坏 | 交由调用方处理 |\n| 状态缓存未命中 | 返回 undefined |\n\n这种防御性编程确保了传输层在异常情况下的健壮性，不会因单个文件问题导致整个服务中断。\n\n## 扩展传输类型\n\nStoa 的传输层设计支持添加新的传输适配器。实现新传输类型的步骤：\n\n1. 实现传输类，实现 `connect` 方法\n2. 注册传输处理器到 MCP 服务器\n3. 在入口文件选择合适的传输类型\n4. 添加对应的启动日志输出\n\n当前支持的传输类型已覆盖本地集成（STDIO）和远程访问（HTTP）两种主要场景。\n\n---\n\n<a id='eventbus'></a>\n\n## 事件总线系统\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [召回与检索系统](#recall-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/core/eventbus/bus.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/bus.ts)\n- [src/core/eventbus/match.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/match.ts)\n- [src/core/eventbus/registry.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/registry.ts)\n- [src/core/eventbus/event-deriver.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/event-deriver.ts)\n- [src/core/eventbus/handle-wait.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/handle-wait.ts)\n- [src/core/eventbus/types.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/types.ts)\n- [src/core/eventbus/matchers/task.ts](https://github.com/BrettNye/stoa/blob/main/src/core/eventbus/matchers/task.ts)\n</details>\n\n# 事件总线系统\n\n## 概述\n\n事件总线系统是 stoa 项目的核心基础设施之一，提供基于文件系统观察的发布-订阅事件处理机制。该系统使 MCP 工具能够以**阻塞等待**（push 原语）而非轮询的方式响应 vault 中的文件变更，实现了实时事件驱动的工具调用模式。\n\n事件总线在以下场景中发挥关键作用：\n\n- 任务状态变更检测（status/owner 变化）\n- wiki 内容变更监听\n- 通道（channel）消息通知\n- 跨实例协调通信\n\n资料来源：[src/core/eventbus/types.ts]()\n\n## 核心架构\n\n### 模块结构\n\n事件总线系统由以下子模块组成：\n\n| 模块 | 文件 | 职责 |\n|------|------|------|\n| 类型定义 | `types.ts` | 定义 `VaultEvent`、`VaultEventFilter`、事件派生器接口 |\n| 事件总线 | `bus.ts` | 核心事件发布-订阅引擎，文件系统监视器集成 |\n| 匹配器 | `match.ts` | 过滤器匹配逻辑，实现事件筛选条件 |\n| 注册表 | `registry.ts` | 管理事件监听器订阅和取消订阅 |\n| 事件派生器 | `event-deriver.ts` | 从原始文件事件派生语义化 vault 事件 |\n| 等待处理 | `handle-wait.ts` | 实现 `wait-for` 系列阻塞原语 |\n| 内置匹配器 | `matchers/task.ts` | 任务状态变更检测匹配器 |\n\n```mermaid\ngraph TD\n subgraph \"文件系统层\"\n FS[文件系统观察者]\n end\n \n subgraph \"事件总线核心\"\n EB[EventBus]\n REG[Registry]\n DER[EventDeriver]\n MATCH[Matcher]\n end\n \n subgraph \"等待原语\"\n WF[wait-for]\n WFA[wait-for-any]\n WFL[wait-for-all]\n WFM[wait-for-many]\n end\n \n FS -->|原始文件变更| EB\n EB --> REG\n EB --> DER\n DER --> MATCH\n MATCH -->|过滤后事件| WF\n MATCH -->|过滤后事件| WFA\n MATCH -->|过滤后事件| WFL\n MATCH -->|过滤后事件| WFM\n \n REG -->|订阅管理| EB\n```\n\n资料\nError with Openai API: output new_sensitive (1027)\n\nPlease check that you have set the OPENAI_API_KEY environment variable with a valid API key.\n\n---\n\n<a id='recall-system'></a>\n\n## 召回与检索系统\n\n### 相关页面\n\n相关主题：[Wiki管理](#wiki-management), [事件总线系统](#eventbus)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/core/index.ts](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts) - 页面索引与查询核心逻辑\n- [src/core/claim-render.ts](https://github.com/BrettNye/stoa/blob/main/src/core/claim-render.ts) - Claims 渲染与排序\n- [src/core/synthesize.ts](https://github.com/BrettNye/stoa/blob/main/src/core/synthesize.ts) - 综合页面合成\n- [src/core/syntheses.ts](https://github.com/BrettNye/stoa/blob/main/src/core/syntheses.ts) - 综合页面状态管理\n- [src/core/channel.ts](https://github.com/BrettNye/stoa/blob/main/src/core/channel.ts) - 频道摘要与查询\n\n> ⚠️ 以下文件在请求上下文中不可用，无法纳入本文档：\n> - `src/core/recall.ts`\n> - `src/core/claims-index.ts`\n> - `src/core/recall-filter.ts`\n> - `src/tools/recall.ts`\n> - `src/tools/read.ts`\n</details>\n\n# 召回与检索系统\n\n## 概述\n\n召回与检索系统是 stoa 知识库系统的核心基础设施，负责从结构化索引中高效定位符合查询条件的页面、Claims 和综合文档。该系统采用**写穿透（Write-Through）索引更新**策略，确保索引数据与文件系统保持同步，同时将完整性检查（目标页面是否存在、Wiki 是否存在）的职责委托给上层消费者。\n\n核心设计原则：\n\n- **单一职责**：召回模块仅负责提取结构化链接引用，不进行完整性验证 资料来源：[src/core/wikilinks.ts:11-12](https://github.com/BrettNye/stoa/blob/main/src/core/wikilinks.ts#L11-L12)\n- **幂等性**：重新渲染相同输入产生字节级相同的输出 资料来源：[src/core/marker-render.ts:19-21](https://github.com/BrettNye/stoa/blob/main/src/core/marker-render.ts#L19-L21)\n- **分层架构**：索引管理层与工具层分离，索引层负责数据持久化，工具层负责业务逻辑编排\n\n## 核心数据模型\n\n### 索引页面结构（IndexedPage）\n\n```typescript\ninterface IndexedPage {\n id: string;\n wiki: string;\n type: string;\n path?: string;\n channel?: string;\n status?: string;\n title?: string;\n tags?: string[];\n created?: string; // ISO日期 YYYY-MM-DD\n updated?: string; // ISO日期 YYYY-MM-DD\n last_validated?: string;\n confidence?: Confidence;\n authored_by?: string;\n}\n```\n\n### VaultIndex 主索引结构\n\n```typescript\ninterface VaultIndex {\n pages: IndexedPage[];\n wikis: IndexedWiki[];\n profiles: IndexedProfile[];\n links: LinkEdge[];\n tokens: TokenIndex;\n}\n```\n\n## 页面查询系统\n\n### queryPages 函数\n\n`queryPages` 是页面查询的核心入口，支持多维度过滤 资料来源：[src/core/index.ts:40-52](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts#L40-L52)：\n\n```typescript\nexport function queryPages(idx: VaultIndex, f: PageFilter): IndexedPage[] {\n return idx.pages.filter(p => {\n if (f.wiki && wikiSet && !wikiSet.has(p.wiki)) return false;\n if (f.type && p.type !== f.type) return false;\n if (f.channel && p.channel !== f.channel) return false;\n if (f.status && p.status !== f.status) return false;\n if (f.layer && f.layer !== \"all\") {\n const set = f.layer === \"knowledge\" ? KNOWLEDGE_TYPES : EXECUTION_TYPES;\n if (!set.includes(p.type)) return false;\n }\n return true;\n });\n}\n```\n\n### 查询过滤器参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `wiki` | `string \\| undefined` | 按 Wiki 名称过滤 |\n| `type` | `string \\| undefined` | 按页面类型过滤 |\n| `channel` | `string \\| undefined` | 按协调频道过滤 |\n| `status` | `string \\| undefined` | 按状态过滤（draft/active/accepted 等） |\n| `layer` | `\"knowledge\" \\| \"execution\" \\| \"all\" \\| undefined` | 按知识层过滤 |\n| `id` | `string \\| undefined` | 按页面 ID 精确匹配 |\n\n### 页面类型分层\n\n系统将页面类型划分为两个知识层：\n\n| 知识层 | 包含类型 | 说明 |\n|--------|----------|------|\n| `KNOWLEDGE_TYPES` | concept, decision, spec, process, capability, domain, support | 持久化、可蒸馏的知识 |\n| `EXECUTION_TYPES` | guide, source, idea, question | 执行层面的文档 |\n\n> 注意：`guide`、`source`、`idea`、`question` 被排除在知识层之外，因为它们是程序性或外部引用性质，不符合\"持久化、可蒸馏\"知识的标准 资料来源：[src/core/lint-checks/synthesis-debt.ts:26-34](https://github.com/BrettNye/stoa/blob/main/src/core/lint-checks/synthesis-debt.ts#L26-L34)\n\n## 索引更新机制\n\n### 写穿透索引（Write-Through Index）\n\n`upsertPage` 函数负责单页面的索引更新：\n\n```typescript\nexport function upsertPage(pagePath: string): void {\n // 读取文件 → 解析 frontmatter → 更新 pages.json 和 tokens.json\n // 注意：不重新生成 links.json, wikis.json, profiles.json\n}\n```\n\n该函数执行以下操作：\n\n1. 读取页面文件内容\n2. 解析 frontmatter 元数据\n3. 向 `_index/pages.json` 添加/替换条目\n4. 向 `_index/tokens.json` 添加分词数据\n5. **不重新生成** `_index/{links,wikis,profiles}.json`（这些是聚合文件）\n\n> 聚合索引文件的重新生成由 `vault.reindex` 工具单独处理 资料来源：[src/core/index.ts:78-82](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts#L78-L82)\n\n### 分词与停用词过滤\n\n```typescript\nconst UPSERT_STOP_WORDS = new Set([\n \"the\",\"and\",\"of\",\"a\",\"an\",\"in\",\"to\",\"is\",\"for\",\"on\",\"with\",\"as\",\"at\",\"by\",\"or\",\"be\",\n \"this\",\"that\",\"it\",\"from\",\"are\",\"was\",\"were\",\"not\",\"but\",\"if\"\n]);\n\nfunction upsertTokenize(text: string): string[] {\n return text.toLowerCase()\n .replace(/[^a-z0-9\\s]/g, \" \")\n .split(/\\s+/)\n .filter(t => t.length > 1 && !UPSERT_STOP_WORDS.has(t))\n .map(t => upsertStemmer.stem(t)); // 使用 Porter Stemmer\n}\n```\n\n| 处理步骤 | 说明 |\n|----------|------|\n| 转小写 | 统一大小写 |\n| 去除非字母数字字符 | 保留单词边界 |\n| 停用词过滤 | 移除高频无意义词 |\n| Porter 词干提取 | 词形归一化 |\n\n## Claims 检索与排序\n\n### 有效置信度计算\n\nClaims 采用**半衰期衰减模型**计算有效置信度 资料来源：[src/core/claim-render.ts:52-62](https://github.com/BrettNye/stoa/blob/main/src/core/claim-render.ts#L52-L62)：\n\n```typescript\nfunction effectiveConfidence(\n claim: { confidence: Confidence; last_validated?: string; status?: string },\n today: Date,\n config: ClaimsConfig,\n): number {\n const base = BASE_CONFIDENCE[claim.confidence ?? \"medium\"];\n const ageMs = today.getTime() - new Date(claim.last_validated ?? today).getTime();\n const halfLives = ageMs / MS_PER_DAY / config.half_life_days;\n const decayed = base * Math.pow(0.5, halfLives);\n const eff = Math.max(decayed, config.effective_floor);\n \n // 被撤回的 Claims 有效置信度归零\n if (claim.status === \"retracted\") return 0;\n \n return eff;\n}\n```\n\n### 置信度基础值\n\n| 置信度级别 | 基础值 | 半衰期衰减后最小值 |\n|------------|--------|-------------------|\n| `high` | 0.9 | 由 `effective_floor` 决定 |\n| `medium` | 0.6 | 由 `effective_floor` 决定 |\n| `low` | 0.3 | 由 `effective_floor` 决定 |\n\n### Claims 排序策略\n\n排序得分公式：\n\n```\nscore(claim) = effective_confidence + (profile_match ? 0.1 : 0)\n```\n\n| 排序因素 | 说明 |\n|----------|------|\n| 有效置信度 | 半衰期衰减后的当前置信度 |\n| Profile 加成 | 当部署 Profile ID 在 claim 的 profile 数组中时加 0.1 |\n\n## 综合文档检索\n\n### 综合文档查询\n\n`syntheses.ts` 提供综合文档的查询与陈旧度分析 资料来源：[src/core/syntheses.ts:40-75](https://github.com/BrettNye/stoa/blob/main/src/core/syntheses.ts#L40-L75)：\n\n```typescript\n// 过滤出 synthesis 类型的页面\nconst syntheses = allPages.filter(p => {\n if (p.type !== \"synthesis\") return false;\n if (opts.wiki && p.wiki !== opts.wiki) return false;\n return true;\n});\n\n// 从文件 frontmatter 读取 last_compiled\nif (synthPath && existsSync(synthPath)) {\n const raw = readFileSync(synthPath, \"utf8\");\n const { frontmatter } = parseFrontmatter(raw);\n const rawLc = frontmatter.last_compiled;\n // 计算距今天数\n lagDays = Math.floor((now - compiledMs) / MS_PER_DAY);\n}\n```\n\n### 综合文档陈旧度指标\n\n| 指标 | 说明 |\n|------|------|\n| `last_compiled` | 上次编译日期，来自 frontmatter |\n| `lag_days` | 距今天数 |\n| `staleness` | 可配置的陈旧度阈值（默认 30 天） |\n\n## 频道摘要检索\n\n`channel.ts` 提供协调频道的实时摘要 资料来源：[src/core/channel.ts:24-45](https://github.com/BrettNye/stoa/blob/main/src/core/channel.ts#L24-L45)：\n\n```typescript\nexport function channelTail(vaultPath: string, opts: ChannelTailOptions): ChannelSummary[] {\n // 查询所有 journal 类型页面\n const pages = queryPages(idx, { type: \"journal\", wiki: opts.wiki });\n \n // 按 wiki::channel 聚合\n const byKey = new Map<string, ChannelSummary>();\n for (const p of pages) {\n const key = `${p.wiki}::${p.channel}`;\n // 统计 24 小时内的条目数\n if (p.created >= sinceIso) summary.count24h++;\n // 记录最新条目\n if (!summary.lastEntry || p.created > summary.lastEntry.ts) {\n // 读取文件获取摘要和作者\n excerpt = body.trim().slice(0, 240);\n author = String(fm.author ?? \"unknown\");\n }\n }\n}\n```\n\n### 频道摘要数据结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `name` | `string` | 频道名称 |\n| `wiki` | `string` | 所属 Wiki |\n| `count24h` | `number` | 24 小时内条目数 |\n| `lastEntry` | `ChannelEntry \\| null` | 最新条目详情 |\n\n## 检索流程图\n\n```mermaid\ngraph TD\n A[用户查询请求] --> B{查询类型}\n B -->|页面查询| C[queryPages]\n B -->|Claims 查询| D[查询 + 置信度计算]\n B -->|综合文档| E[过滤 synthesis 类型]\n B -->|频道摘要| F[channelTail 聚合]\n \n C --> G[应用过滤器]\n D --> H[计算 effective_confidence]\n E --> I[读取 last_compiled]\n F --> J[统计 count24h]\n \n G --> K[返回 IndexedPage[]]\n H --> L[按 score 排序]\n I --> M[计算 lag_days]\n J --> N[返回 ChannelSummary[]]\n \n L --> O[返回排序后 Claims]\n M --> P[返回 SynthesisStaleness[]]\n```\n\n## 架构设计要点\n\n### 索引与文件系统同步\n\n| 操作 | 索引更新范围 |\n|------|--------------|\n| `upsertPage` | `pages.json` + `tokens.json` |\n| `vault.reindex` | 全部索引文件 |\n| 文件删除 | 需手动触发重建 |\n\n### Wiki 解析器\n\n```typescript\nexport function queryWikis(idx: VaultIndex): IndexedWiki[] {\n return idx.wikis;\n}\n```\n\n### 过滤器组合\n\n页面过滤器支持**多维度组合过滤**，各维度之间为 AND 关系：\n\n```mermaid\ngraph LR\n A[Wiki 过滤] -->|AND| Z[最终结果]\n B[Type 过滤] -->|AND| Z\n C[Channel 过滤] -->|AND| Z\n D[Status 过滤] -->|AND| Z\n E[Layer 过滤] -->|AND| Z\n```\n\n## 配置参数\n\n### Claims 渲染配置\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `half_life_days` | `number` | 30 | 置信度半衰期（天） |\n| `effective_floor` | `number` | 0.1 | 有效置信度下限 |\n\n### 综合文档配置\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `min_lag_days` | `number \\| null` | null | 最小陈旧天数阈值 |\n| `stale_after_days` | `number` | 30 | 标记为陈旧的天数 |\n\n## 相关工具\n\n| 工具名称 | 功能 |\n|----------|------|\n| `vault.reindex` | 重新生成全部索引文件 |\n| `vault.synthesize` | 编译或刷新综合页面 |\n| `vault.channel-tail` | 拉取协调频道的最新条目 |\n| `vault.recall` | 根据条件召回相关页面 |\n\n---\n\n*本文档基于 stoa 仓库的可用源码生成。部分检索系统核心文件（`recall.ts`、`claims-index.ts` 等）在当前上下文不可用，完整功能描述需待源码补充后更新。*\n\n---\n\n<a id='wiki-management'></a>\n\n## Wiki管理\n\n### 相关页面\n\n相关主题：[召回与检索系统](#recall-system), [核心概念](#concepts)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/core/wikis.ts](https://github.com/BrettNye/stoa/blob/main/src/core/wikis.ts)\n- [src/core/frontmatter.ts](https://github.com/BrettNye/stoa/blob/main/src/core/frontmatter.ts)\n- [src/core/wikilinks.ts](https://github.com/BrettNye/stoa/blob/main/src/core/wikilinks.ts)\n- [src/core/synthesize.ts](https://github.com/BrettNye/stoa/blob/main/src/core/synthesize.ts)\n- [src/tools/new-wiki.ts](https://github.com/BrettNye/stoa/blob/main/src/tools/new-wiki.ts)\n- [src/tools/set-active.ts](https://github.com/BrettNye/stoa/blob/main/src/tools/set-active.ts)\n- [src/tools/synthesize.ts](https://github.com/BrettNye/stoa/blob/main/src/tools/synthesize.ts)\n</details>\n\n# Wiki管理\n\n## 概述\n\nWiki管理是Stoa系统的核心功能之一，负责管理知识库中的wiki空间、页面组织、链接解析以及内容综合。Stoa采用vault-root结构，所有wiki内容位于`wikis/`目录下，每个wiki是独立的内容空间，支持多wiki架构和跨wiki引用。\n\nWiki管理的核心职责包括：\n\n- 创建和配置新的wiki\n- 管理wiki的活动状态和默认上下文\n- 解析和验证wiki间的链接关系\n- 驱动内容综合（synthesis）机制\n- 维护wiki索引和元数据\n\n资料来源：[README.md]()\n\n---\n\n## Wiki核心概念\n\n### 架构分层\n\nStoa的知识库采用分层架构：\n\n```mermaid\ngraph TD\n A[\"vault root\"] --> B[\"wikis/\"]\n B --> C[\"<wiki-name>/\"]\n C --> D[\"concept/\"]\n C --> E[\"decision/\"]\n C --> E2[\"source/\"]\n C --> E3[\"guide/\"]\n C --> E4[\"journal/\"]\n C --> E5[\"claim/\"]\n C --> E6[\"synthesis/\"]\n C --> E7[\"move/\"]\n C --> F[\"map.md\"]\n C --> G[\"index.md\"]\n C --> H[\"_meta/\"]\n```\n\n每个wiki包含多种页面类型，每种类型对应不同的知识处理模式。\n\n### 页面类型体系\n\n| 类型 | 说明 | 文件命名规则 |\n|------|------|-------------|\n| `concept` | 概念页面 | `concept-<slug>.md` |\n| `decision` | 决策记录 | `decision-YYYY-MM-DD-<slug>.md` |\n| `source` | 外部引用 | `source-<slug>.md` |\n| `guide` | 操作指南 | `guide-<slug>.md` |\n| `journal` | 日志条目 | `journal-YYYY-MM-DD-HHMM-<slug>.md` |\n| `claim` | 断言声明 | `claim-<slug>.md` |\n| `synthesis` | 综合页面 | `synthesis-<slug>.md` |\n| `move` | 技能移动 | `move-<slug>/SKILL.md` |\n| `map` | 地图页面 | `map.md` |\n\n资料来源：[src/core/ids.ts]()\n\n---\n\n## Wiki创建与初始化\n\n### newWiki函数\n\n`newWiki`函数负责在vault中创建新的wiki空间，包含完整的目录结构和初始配置文件。\n\n```typescript\nfunction newWiki(\n vaultPath: string,\n opts: NewWikiOptions\n): NewWikiResult\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `vaultPath` | `string` | 是 | vault根目录路径 |\n| `opts.name` | `string` | 是 | wiki名称 |\n| `opts.mode` | `WikiMode` | 是 | wiki模式：idea-map、project-doc、learning、mixed |\n| `opts.scope` | `string` | 是 | wiki作用域描述 |\n\n**返回值：**\n\n```typescript\ninterface NewWikiResult {\n name: string;\n path: string;\n files_created: string[];\n}\n```\n\n创建过程中会生成以下基础文件：\n\n- `wikis/<name>/map.md` — wiki导航地图\n- `wikis/<name>/index.md` — wiki首页\n- `wikis/<name>/CLAUDE.md` — wiki级别的AI上下文配置\n- `wikis/<name>/_meta/` — 元数据目录\n\n资料来源：[src/tools/new-wiki.ts]()\n\n### Wiki模式\n\nWiki支持四种创建模式，每种模式预设不同的内容结构和初始标签：\n\n| 模式 | 用途 | 典型内容 |\n|------|------|---------|\n| `idea-map` | 头脑风暴和概念映射 | 大量concept页面 |\n| `project-doc` | 项目文档管理 | guide、decision为主 |\n| `learning` | 学习和知识积累 | source、concept交替 |\n| `mixed` | 混合用途 | 均衡各类内容 |\n\n资料来源：[src/core/wikis.ts]()\n\n---\n\n## 活动Wiki管理\n\n### setActiveWiki机制\n\n系统维护一个\"活动wiki\"的概念，作为命令执行的默认上下文。活动wiki的解析遵循优先级链：\n\n```mermaid\ngraph LR\n A[\"explicit wikiArg\"] --> B{\"已知wiki?\"}\n B -->|是| C[\"返回wikiArg\"]\n B -->|否| D[\"抛出错误\"]\n E[\"无explicit参数\"] --> F{\".active-family文件?\"}\n F -->|存在| G[\"读取文件内容\"]\n F -->|不存在| H[\"CLI --default-family\"]\n H --> I{\".active-family文件?\"}\n I -->|存在| J[\"读取文件内容\"]\n I -->|不存在| K[\"返回null - 单wiki解析\"]\n```\n\n**解析优先级（高到低）：**\n\n1. 显式传入的`wikiArg`参数\n2. `ctx.defaultFamily` — CLI的`--default-family`参数\n3. `<vaultPath>/.active-family`文件内容\n4. `null` — 回退到单wiki解析模式\n\n资料来源：[src/core/family.ts]()\n\n### FamilyMismatchError\n\n当显式传入的`family`和`wiki`参数不匹配时，系统抛出结构化错误：\n\n```typescript\nthrow new FamilyMismatchError(\n `wiki '${wikiArg}' has family '${wikiFamily ?? \"(none)\"}' which does not match requested family '${familyArg}'`\n);\n```\n\n这确保了多family场景下参数的一致性，防止静默的错误路由。\n\n资料来源：[src/core/family.ts]()\n\n---\n\n## Wikilink链接系统\n\n### 链接格式规范\n\nStoa使用`[[wikilink]]`语法进行wiki内和跨wiki引用。链接格式支持以下变体：\n\n```\n[[wikis/<wiki>/<type>/<id>]]\n[[wikis/<wiki>/<type>/<id>|alias]]\n```\n\n**绝对形式（vault-root）：**\n```\n[[wikis/brett/concept/my-page]]\n[[wikis/brett/concept/my-page|显示别名]]\n```\n\n资料来源：[src/core/wikilinks.ts]()\n\n### WikilinkRef数据结构\n\n```typescript\nexport interface WikilinkRef {\n raw: string; // 原始链接文本\n wiki: string; // 目标wiki名称\n type: string; // 页面类型\n id: string; // 页面ID\n alias?: string; // 可选的显示别名\n source: \"body\" | \"frontmatter\"; // 链接来源位置\n}\n```\n\n资料来源：[src/core/wikilinks.ts]()\n\n### 链接提取规则\n\nWikilink提取器`extractWikilinks`具有以下行为特征：\n\n| 特性 | 说明 |\n|------|------|\n| 代码块感知 | 顶层\\`\\`\\`代码块内的链接被跳过 |\n| 行首要求 | 代码块标记必须在一行的开头 |\n| 内联代码 | 单反引号\\`包裹的文本中的链接**不**被过滤 |\n| 嵌套代码块 | 缩进内的代码块（如列表项内4空格缩进）**不**被处理 |\n\n```typescript\n// 示例：以下内容中\n```\n[[wikis/brett/concept/inside-code]]\n```\n这里 [[wikis/brett/concept/outside-code]] 会提取\n\n// 提取结果：只包含 outside-code\n```\n\n资料来源：[src/core/wikilinks.ts]()\n\n---\n\n## 内容综合（Synthesis）\n\n### Synthesis机制概述\n\nSynthesis是Stoa的核心知识整合功能，用于将多个相关页面综合成一篇聚合文档。综合页面维护一个managed region，由marker边界限定。\n\n```mermaid\ngraph TD\n A[\"输入：话题或agent\"] --> B[\"查询匹配页面\"]\n B --> C{\"by_agent?\"}\n C -->|是| D[\"过滤到特定agent\"]\n C -->|否| E[\"按话题检索\"]\n D --> F[\"生成Synthesis页面\"]\n E --> F\n F --> G[\"写入marker区域\"]\n G --> H[\"更新_index/syntheses.json\"]\n```\n\n### Marker区域管理\n\nMarker区域由HTML注释界定，支持幂等渲染：\n\n```html\n<!-- synthesis:start (rendered: 2025-01-15, half-life: 7d) -->\n## 来源\n\n- [[wikis/brett/concept/page-a]]\n- [[wikis/brett/concept/page-b]]\n<!-- synthesis:end -->\n```\n\n**Marker选项：**\n\n| 选项 | 说明 |\n|------|------|\n| `renderedDate` | ISO日期YYYY-MM-DD，渲染时间戳 |\n| `halfLifeDays` | 半衰期天数，用于缓存策略 |\n\n重新渲染相同输入产生字节级一致输出，不同markerName的区域互不干扰。\n\n资料来源：[src/core/marker-render.ts]()\n\n### SynthesisFrontmatter\n\n综合页面生成的frontmatter结构：\n\n```typescript\nconst fm = {\n id, // 唯一标识符\n title, // 标题\n type: \"synthesis\", // 固定类型\n wiki, // 所属wiki\n status: \"draft\", // 初始状态\n created: today,\n updated: today,\n summary, // 综合说明\n tags, // 标签数组\n last_compiled: today, // 最后编译时间\n sources: [...] // 来源页面wikilinks数组\n};\n```\n\n对于agent memory类型的综合，还会包含`by_agent`和`scope: \"memory\"`字段。\n\n资料来源：[src/core/synthesize.ts]()\n\n---\n\n## 索引与查询\n\n### VaultIndex结构\n\nVault维护统一的索引结构支持高效查询：\n\n```typescript\nexport interface VaultIndex {\n pages: IndexedPage[];\n wikis: IndexedWiki[];\n profiles: IndexedProfile[];\n tokens: Record<string, string[]>;\n links: Record<string, string[]>;\n}\n```\n\n### Wiki查询\n\n```typescript\nexport function queryWikis(idx: VaultIndex): IndexedWiki[]\n```\n\n返回所有已索引的wiki列表，每个IndexedWiki包含名称、路径、family归属等信息。\n\n资料来源：[src/core/index.ts]()\n\n---\n\n## 工具命令参考\n\n### vault.new-wiki\n\n```bash\nvault new-wiki <name> --mode <mode> --scope <scope>\n```\n\n**参数：**\n\n| 参数 | 说明 |\n|------|------|\n| `name` | wiki名称 |\n| `--mode` | 必须：idea-map\\|project-doc\\|learning\\|mixed |\n| `--scope` | 必须：作用域描述 |\n\n**输出示例：**\n```\ncreated wiki: mywiki at wikis/mywiki (7 files)\n```\n\n资料来源：[src/cli/commands/new-wiki.ts]()\n\n### vault.synthesize\n\n创建或刷新综合页面：\n\n```bash\nvault synthesize --topic <topic> --wiki <wiki> [--by_agent <agent>]\n```\n\n**参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `--topic` | string | 综合主题 |\n| `--wiki` | string | 目标wiki |\n| `--by_agent` | string | 可选：按agent过滤 |\n| `--limit` | number | 候选页面数量限制（默认25） |\n\n资料来源：[src/tools/synthesize.ts]()\n\n### vault.set-active\n\n设置当前活动的wiki上下文：\n\n```bash\nvault set-active <wiki>\n```\n\n该命令更新`.active-family`文件，后续命令默认使用该wiki作为上下文。\n\n资料来源：[src/tools/set-active.ts]()\n\n---\n\n## 跨Wiki协作\n\n### Family机制\n\nFamily是一组相关wiki的逻辑分组，支持跨wiki内容发现：\n\n```typescript\nexport interface FamilyRollup {\n members: string[]; // wiki成员列表（已排序）\n total_pages: number; // 总页面数\n modes_used: string[]; // 使用的模式类型（去重+排序）\n}\n```\n\n### 频道系统\n\nWiki支持通过频道进行协调通信：\n\n```typescript\ninterface ChannelSummary {\n name: string;\n wiki: string;\n lastEntry: ChannelEntry | null;\n count24h: number; // 24小时内的条目数\n}\n```\n\n`vault.channel-tail`命令可拉取最近频道条目，`vault.channel-post`用于发布到频道。\n\n资料来源：[src/core/channel.ts]()\n\n---\n\n## 最佳实践\n\n### Wiki创建建议\n\n1. **选择合适的模式** — 根据内容性质选择`idea-map`、`project-doc`等模式\n2. **设置清晰的scope** — scope描述帮助系统理解wiki的职责边界\n3. **配置CLAUDE.md** — 在wiki根目录配置AI上下文，指导知识管理行为\n\n### 链接使用规范\n\n1. **优先使用绝对形式** — `[[wikis/wiki/type/id]]`形式跨上下文可移植\n2. **避免代码块内链接** — 顶层代码块中的wikilink不会被解析\n3. **使用alias增强可读性** — `[[target|描述文本]]`提供语义化展示\n\n### Synthesis维护\n\n1. **定期刷新** — 综合页面会记录`last_compiled`，建议周期性刷新以纳入新内容\n2. **利用半衰期** — 设置合理的`halfLifeDays`平衡新鲜度和稳定性\n3. **保护marker区域** — 手动编辑时避免修改marker注释边界\n\n---\n\n## 相关文档\n\n- [页面管理](./页面管理.md)\n- [链接系统](./链接系统.md)\n- [Family机制](./Family机制.md)\n- [Synthesis系统](./Synthesis系统.md)\n\n---\n\n<a id='task-coordination'></a>\n\n## 任务协作系统\n\n### 相关页面\n\n相关主题：[事件总线系统](#eventbus)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/core/channel.ts](https://github.com/BrettNye/stoa/blob/main/src/core/channel.ts)\n- [src/core/frontmatter.ts](https://github.com/BrettNye/stoa/blob/main/src/core/frontmatter.ts)\n- [src/core/lint-checks/synthesis-debt.ts](https://github.com/BrettNye/stoa/blob/main/src/core/lint-checks/synthesis-debt.ts)\n- [src/core/index.ts](https://github.com/BrettNye/stoa/blob/main/src/core/index.ts)\n- [src/core/pages.ts](https://github.com/BrettNye/stoa/blob/main/src/core/pages.ts)\n\n> **注意**：以下源码文件在查询范围内但未出现在当前上下文片段中：\n> - `src/core/tasks.ts`\n> - `src/core/inbox.ts`\n> - `src/core/sync-enumerate.ts`\n> - `src/tools/task-claim.ts`\n> - `src/tools/channel-post.ts`\n> - `src/tools/process-inbox.ts`\n>\n> 本页基于现有上下文片段构建，部分系统细节可能需要补充。\n\n</details>\n\n# 任务协作系统\n\n## 概述\n\n任务协作系统是 Stoa 知识管理平台的核心子系统之一，负责管理任务（task）类型页面的生命周期、任务分发与认领、以及通过 Channel 机制实现跨智能体（agent）的任务协调。\n\n系统的设计目标包括：\n\n1. **结构化任务管理**：通过标准化的 frontmatter schema 定义任务元数据，确保任务状态、优先级和归属的完整性\n2. **智能体协调**：支持通过 Channel 进行任务公告和认领，实现多智能体环境下的工作分配\n3. **状态追踪**：提供任务状态流转的完整生命周期管理，从草稿（draft）到归档（archived）\n4. **索引与查询**：基于 VaultIndex 的全文检索能力，支持按类型、wiki、状态等维度查询任务\n\n资料来源：[src/core/frontmatter.ts:1-50]()\n\n## 核心数据模型\n\n### 页面类型体系\n\nStoa 采用统一的页面类型系统，任务（task）是其中一种核心类型。系统定义了以下类型常量用于过滤和分类：\n\n```typescript\n// 知识类型（硬知识，可合成）\nconst KNOWLEDGE_TYPES = [\"concept\", \"decision\", \"spec\", \"source\"];\n\n// 执行类型（过程性知识）\nconst EXECUTION_TYPES = [\"guide\", \"idea\", \"question\", \"task\", \"move\"];\n```\n\n资料来源：[src/core/index.ts:1-30]()\n\n### 页面状态枚举\n\n任务页面使用统一的 PageStatus 枚举定义状态：\n\n| 状态值 | 含义 | 使用场景 |\n|--------|------|----------|\n| `draft` | 草稿 | 任务刚创建，尚未激活 |\n| `active` | 活跃 | 任务正在执行中 |\n| `accepted` | 已接受 | 任务已被认领并确认 |\n| `superseded` | 已替代 | 任务已被新任务替代 |\n| `archived` | 已归档 | 任务完成或放弃后归档 |\n\n资料来源：[src/core/frontmatter.ts:15-17]()\n\n### Inbox 项结构\n\nInbox（收件箱）是任务分发的基础机制。系统通过解析 frontmatter 中的特定字段将页面路由到相应的 Inbox：\n\n```typescript\nexport interface InboxEntry {\n id: string;\n wiki: string;\n path: string;\n title: string;\n type: NoteType;\n updated: string;\n created: string;\n}\n```\n\n资料来源：[src/core/pages.ts:1-50]()\n\n## Channel 协作机制\n\nChannel 是 Stoa 中实现任务公告和实时协作的核心组件。它本质上是一个命名频道，用于：\n\n1. **任务公告**：将新任务发布到特定频道\n2. **认领机制**：智能体通过 Channel 认领分配给它的任务\n3. **活动聚合**：按频道聚合 24 小时内的活动摘要\n\n### Channel 摘要结构\n\n```typescript\nexport interface ChannelSummary {\n name: string; // 频道名称（kebab-case）\n wiki: string; // 所属 wiki\n lastEntry: EntryInfo | null; // 最新条目\n count24h: number; // 24小时内条目数\n}\n```\n\n资料来源：[src/core/channel.ts:1-30]()\n\n### Channel 聚合逻辑\n\n系统通过以下流程聚合 Channel 摘要：\n\n```mermaid\ngraph TD\n A[查询所有 journal 类型页面] --> B[按 channel 分组]\n B --> C{是否超过 24 小时?}\n C -->|是| D[跳过计数]\n C -->|否| E[count24h++]\n E --> F[更新 lastEntry]\n D --> G[返回排序后的 ChannelSummary 列表]\n E --> G\n```\n\n处理逻辑的核心代码：\n\n```typescript\nfor (const p of pages) {\n const channel = p.channel;\n if (typeof channel !== \"string\" || !channel) continue;\n const key = `${p.wiki}::${channel}`;\n if (p.created >= sinceIso) summary.count24h++;\n if (!summary.lastEntry || p.created > summary.lastEntry.ts) {\n // 读取文件获取 author 和 body excerpt\n summary.lastEntry = {\n id: p.id,\n channel,\n wiki: p.wiki,\n author: String(fm.author ?? \"unknown\"),\n ts: p.created,\n excerpt,\n pageId: p.id,\n };\n }\n}\n```\n\n资料来源：[src/core/channel.ts:30-60]()\n\n## 任务生命周期管理\n\n### 任务创建\n\n任务通过 `writePage` 函数创建，系统自动处理：\n\n1. 生成规范的文件路径：`tasks/<slug>.md`\n2. 解析并验证 frontmatter\n3. 写入文件系统并更新索引\n\n```typescript\nexport interface WritePageInput {\n id: string;\n type: NoteType;\n wiki: string;\n frontmatter: Record<string, any>;\n body: string;\n expectedUpdated?: string;\n}\n```\n\n资料来源：[src/core/pages.ts:60-80]()\n\n### 任务路径映射\n\n系统使用 `pathForPage` 函数将页面 ID 映射到文件系统路径：\n\n```typescript\n// 任务类型路径格式\npath = join(vaultPath, \"wikis\", wiki, \"tasks\", `${id}.md`);\n```\n\n资料来源：[src/core/pages.ts:20-40]()\n\n## 智能体协作工作流\n\n### 任务分发流程\n\n```mermaid\ngraph LR\n A[任务创建] --> B[写入 tasks 目录]\n B --> C[更新 VaultIndex]\n C --> D[Channel 公告]\n D --> E[智能体感知]\n E --> F[任务认领]\n F --> G[状态更新为 accepted]\n```\n\n### 硬知识类型判定\n\n在协作系统中，系统需要区分\"硬知识\"（可合成的知识资产）和\"执行型\"知识。任务属于 `EXECUTION_TYPES`：\n\n```typescript\nconst HARD_KNOWLEDGE_TYPES = new Set([\"concept\", \"decision\", \"spec\", \"source\"]);\n\n// 任务不属于硬知识，不参与合成债务检测\nconst type = String(page.type);\nif (HARD_KNOWLEDGE_TYPES.has(type)) {\n // 参与合成债务检测\n}\n```\n\n资料来源：[src/core/lint-checks/synthesis-debt.ts:40-60]()\n\n## Channel 名称规范\n\nChannel 名称必须符合 kebab-case 格式，lint 检查会验证格式：\n\n| 规则 | 正则表达式 | 示例 |\n|------|------------|------|\n| 有效格式 | `^[a-z0-9]+(-[a-z0-9]+)*$` | `feature-x`, `bug-fix` |\n| 无效格式 | 包含大写或特殊字符 | `myChannel`, `feature_x` |\n\n```typescript\n// Lint 检查代码\nif (p.channel && !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(p.channel)) {\n diagnostics.push({\n severity: \"warning\",\n code: \"BAD_CHANNEL_FORMAT\",\n message: `channel \"${p.channel}\" must be lowercase kebab-case`\n });\n}\n```\n\n资料来源：[src/core/lint.ts:1-30]()\n\n## 配置与验证\n\n### Frontmatter Schema 验证\n\n系统使用 Zod 进行运行时验证，确保任务元数据的完整性：\n\n```typescript\nconst draftSchema = z.object({\n id: z.string().regex(/^[a-z0-9-]+$/),\n title: z.string().min(1),\n type: NoteType,\n created: z.string().regex(ISO_DATE),\n channel: z.string().regex(KEBAB).optional(),\n});\n```\n\n验证规则：\n- `id`：仅允许小写字母、数字和连字符\n- `created`：必须是 ISO 日期格式 `YYYY-MM-DD`\n- `channel`：必须是 kebab-case 格式\n\n资料来源：[src/core/frontmatter.ts:50-70]()\n\n### 索引查询能力\n\nVaultIndex 提供强大的查询能力，支持按多个维度过滤任务：\n\n```typescript\nexport function queryPages(\n idx: VaultIndex,\n filters: {\n wiki?: string;\n type?: string;\n status?: string;\n layer?: \"knowledge\" | \"execution\" | \"all\";\n }\n): IndexedPage[]\n```\n\n支持的过滤维度：\n- `wiki`：限定 wiki 范围\n- `type`：匹配页面类型\n- `status`：匹配页面状态\n- `layer`：按知识层过滤（knowledge 或 execution）\n\n资料来源：[src/core/index.ts:1-40]()\n\n## 系统集成\n\n### 与 Lint 系统集成\n\n任务协作系统与全局 lint 检查集成，确保数据质量：\n\n| 检查项 | 严重级别 | 说明 |\n|--------|----------|------|\n| `BAD_CHANNEL_FORMAT` | warning | Channel 名称格式不符合 kebab-case |\n| `FILENAME_ID_MISMATCH` | warning | 文件名与 ID 不匹配 |\n| `SNIPPET_NO_IMPLEMENTATION` | warning | 带有 snippet 标签的页面缺少 implementation 字段 |\n\n```typescript\n// 示例：遍历所有页面检查 channel 格式\nfor (const p of idx.pages) {\n if (input.wiki && p.wiki !== input.wiki) continue;\n if (p.channel && !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(p.channel)) {\n diagnostics.push({ /* ... */ });\n }\n}\n```\n\n资料来源：[src/core/lint.ts:20-45]()\n\n### 与 Synthesis 系统集成\n\n虽然任务本身不参与合成债务检测，但任务可以引用合成的知识资产：\n\n```typescript\n// 合成页面可以引用任务\nsources: inputIds.map(i => `[[wikis/${wiki}/${typeFolderForId(i)}/${i}]]`)\n```\n\n资料来源：[src/core/synthesize.ts:40-50]()\n\n## 总结\n\n任务协作系统是 Stoa 平台中连接知识管理与智能体执行的关键桥梁。它通过：\n\n1. **标准化数据模型**：基于 Zod schema 的类型安全定义\n2. **Channel 机制**：实现跨智能体的任务公告和认领\n3. **状态流转管理**：完整的任务生命周期支持\n4. **索引与查询**：高效的 VaultIndex 查询能力\n5. **质量保障**：集成 lint 检查确保数据完整性\n\n该系统设计遵循单一职责原则，将任务提取、状态管理、Channel 协作等功能模块化，便于维护和扩展。\n\n---\n\n<a id='claims-evolution'></a>\n\n## Claims与Evolution系统\n\n### 相关页面\n\n相关主题：[核心概念](#concepts), [Wiki管理](#wiki-management)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/core/claims.ts](https://github.com/BrettNye/stoa/blob/main/src/core/claims.ts)\n- [src/core/claim-render.ts](https://github.com/BrettNye/stoa/blob/main/src/core/claim-render.ts)\n- [src/core/claim-clustering.ts](https://github.com/BrettNye/stoa/blob/main/src/core/claim-clustering.ts)\n- [src/core/evolution.ts](https://github.com/BrettNye/stoa/blob/main/src/core/evolution.ts)\n- [src/core/evolution-claims.ts](https://github.com/BrettNye/stoa/blob/main/src/core/evolution-claims.ts)\n- [src/tools/claim.ts](https://github.com/BrettNye/stoa/blob/main/src/tools/claim.ts)\n- [src/tools/evolve-profile.ts](https://github.com/BrettNye/stoa/blob/main/src/tools/evolve-profile.ts)\n</details>\n\n# Claims与Evolution系统\n\n## 系统概述\n\nClaims与Evolution系统是stoa项目的核心智能体能力框架，负责管理知识主张的验证、置信度计算以及智能体画像的动态演进。该系统通过半衰期衰减机制、证据链追踪和多维度评分算法，实现了知识可信度评估与能力成长的闭环管理。\n\nClaims（知识主张）作为系统的基本单元，承载了智能体对特定知识点的断言及其元数据。Evolution（进化）系统则利用Claims集合，通过聚类分析和移动推荐算法，驱动智能体画像的能力升级与专业化发展。\n\n**核心设计目标：**\n\n- 为知识断言提供可量化的置信度评估\n- 通过时间衰减机制保持知识库的新鲜度\n- 基于证据质量自动调整主张可信度\n- 支持多智能体协作场景下的知识共享与验证\n\n资料来源：[src/core/evolution.ts:1-30]()\n\n---\n\n## Claims数据模型\n\n### Claim基础结构\n\nClaims是知识主张的持久化表示，每个Claim包含以下核心字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 全局唯一标识符，格式为`claim-<slug>` |\n| `authored_by` | string | 主张创建者的智能体ID |\n| `confidence` | number | 原始置信度，范围0.0-1.0 |\n| `status` | enum | 主张状态：active/retracted/superseded |\n| `evidence` | string[] | 支持该主张的页面引用数组 |\n| `summary` | string | 主张的简要描述 |\n| `body` | string | 主张的完整内容 |\n| `last_validated` | string | ISO格式的最后验证时间 |\n| `validated_by` | string[] | 验证该主张的智能体ID列表 |\n| `tags` | string[] | 主题标签，用于分类和聚类 |\n| `profile` | string[] | 关联的画像ID列表 |\n\n资料来源：[src/tools/claim.ts:1-50]()\n\n### Claim状态机\n\n```mermaid\nstateDiagram-v2\n [*] --> active: 创建新主张\n active --> retracted: 作者主动撤回\n active --> superseded: 被更高置信度主张替代\n retracted --> [*]: 永久归档\n superseded --> [*]: 保留历史参考\n```\n\n**状态转换规则：**\n\n- **active → retracted**：仅原创建者可执行撤回操作\n- **active → superseded**：当新主张具有更高有效置信度时可触发\n- **retracted**：不可逆状态，记录撤回原因和时间戳\n\n资料来源：[src/tools/claim.ts:30-60]()\n\n---\n\n## 有效置信度计算\n\n### 半衰期衰减机制\n\n系统采用指数衰减模型计算主张的有效置信度，这是保持知识库时效性的核心机制：\n\n```\neffective_confidence = base_confidence × 0.5^(days_since_validation / half_life_days)\n```\n\n**衰减参数配置：**\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `half_life_days` | 90 | 置信度减半所需天数 |\n| `effective_floor` | 0.05 | 有效置信度下限 |\n\n### 有效置信度计算函数\n\n```typescript\nfunction effectiveConfidence(\n claim: { confidence: number; last_validated: string; status: string },\n today: Date,\n config: { half_life_days: number; effective_floor: number }\n): number {\n // 已撤回或被替代的主张直接返回下限\n if (claim.status !== \"active\") return config.effective_floor;\n \n const days = daysSince(claim.last_validated, today);\n const decay = Math.pow(0.5, days / config.half_life_days);\n const effective = claim.confidence * decay;\n \n return Math.max(effective, config.effective_floor);\n}\n```\n\n资料来源：[src/core/claim-render.ts:1-40]()\n\n### 部署画像加成\n\n当主张关联的画像与当前部署的智能体匹配时，额外获得0.1的置信度加成：\n\n```\nfinal_score = effective_confidence + (profile匹配 ? 0.1 : 0)\n```\n\n此机制确保智能体在评估与其能力相关的知识时具有优先权。\n\n资料来源：[src/core/claim-render.ts:10-20]()\n\n---\n\n## Claims工具集\n\n### 核心操作\n\n| 操作 | 说明 | 权限限制 |\n|------|------|----------|\n| `vault.claim-submit` | 提交新主张 | 无限制 |\n| `vault.claim-retract` | 撤回本人主张 | 仅原作者 |\n| `vault.claim-supersede` | 用新主张替代旧主张 | 高置信度优先 |\n| `vault.claim-read` | 读取主张详情 | 无限制 |\n\n### 提交新主张\n\n提交新主张时，系统执行以下校验：\n\n1. **唯一性检查**：相同证据+相同标签组合不允许重复提交\n2. **置信度门槛**：新主张置信度必须**严格高于**现有主张\n3. **证据完整性**：建议提供至少一个证据页面引用\n\n若校验失败，返回`rejected`状态并附带拒绝原因和现有主张信息：\n\n```json\n{\n \"claim_id\": \"existing_claim_id\",\n \"action\": \"rejected\",\n \"rejection\": {\n \"reason\": \"existing claim has effective confidence 0.756; submission's 0.700 is not strictly higher\",\n \"existing_id\": \"claim-xxx\",\n \"existing_effective_confidence\": 0.756,\n \"your_confidence\": 0.700\n }\n}\n```\n\n资料来源：[src/tools/claim.ts:40-80]()\n\n---\n\n## Evolution进化系统\n\n### 进化决策流程\n\n```mermaid\ngraph TD\n A[输入: 画像ID] --> B[查询关联Claims]\n B --> C{Claims数量 ≥ 阈值?}\n C -->|否| D[返回不满足条件]\n C -->|是| E[聚类分析Claims]\n E --> F[识别Top Clusters]\n F --> G[计算专业领域建议]\n G --> H[生成移动推荐]\n H --> I[渲染进化理由]\n I --> J[输出: 进化结果]\n```\n\nEvolution系统通过以下步骤为智能体生成能力进化建议：\n\n1. **Claims收集**：获取关联画像的所有活动主张\n2. **聚类分析**：基于标签和证据将主张分组\n3. **专业领域识别**：找出Claims最集中的领域\n4. **移动推荐**：基于聚类结果推荐可学习的技能\n5. **理由生成**：构建人类可读的进化建议文本\n\n资料来源：[src/core/evolution.ts:1-50]()\n\n### 进化输出结构\n\n```typescript\ninterface EvolutionResult {\n eligible: boolean;\n reason: string;\n current: ProfileSnapshot;\n proposed: {\n specialties: string[];\n moveset_suggestions: MoveSuggestion[];\n };\n rationale: string;\n eligibility: EligibilityDetails;\n evidence_summary: EvidenceSummary;\n}\n```\n\n### 专业领域（Specialties）\n\n系统从Claim聚类中提取排名前3的专业领域：\n\n- 按标签频率排序\n- 仅考虑有效置信度>0.2的Claims\n- 每个领域至少包含2个Claims\n\n### 移动建议（Move Suggestions）\n\n基于聚类分析结果，系统推荐适合当前能力阶段的学习移动：\n\n```typescript\ninterface MoveSuggestion {\n move_id: string;\n move_hint: string;\n evidence_claim_ids: string[];\n}\n```\n\n资料来源：[src/core/evolution.ts:50-100]()\n\n---\n\n## Claims聚类机制\n\n### 聚类算法\n\nClaims聚类基于多维度相似度计算：\n\n```mermaid\ngraph LR\n A[Claim A] -->|标签交集| E[相似度计算]\n B[Claim B] -->|标签交集| E\n A -->|证据重叠| E\n B -->|证据重叠| E\n E --> F[聚类分组]\n```\n\n**聚类维度：**\n\n| 维度 | 权重 | 说明 |\n|------|------|------|\n| 标签重叠 | 0.5 | 共同标签越多，关联越强 |\n| 证据重叠 | 0.3 | 引用的页面重叠度高 |\n| 时间邻近 | 0.2 | 相近时间创建的Claims更可能相关 |\n\n### 聚类用途\n\n1. **Evolution进化**：识别能力集中的主题领域\n2. **合成建议**：检测可合成的新知识主题\n3. **冲突检测**：发现相互矛盾的Claims组\n\n资料来源：[src/core/claim-clustering.ts:1-30]()\n\n---\n\n## 配置参数\n\n### Claims配置\n\n在`wikis/<wiki>/CLAUDE.md`中配置：\n\n```yaml\nclaims:\n half_life_days: 90 # 置信度衰减半衰期\n effective_floor: 0.05 # 最低有效置信度\n min_evidence: 1 # 最少证据数量\n```\n\n### Evolution配置\n\n```yaml\nevolution:\n min_claims_for_evolution: 10 # 触发进化的最少Claims数\n max_specialties: 3 # 最大专业领域数\n cluster_min_size: 2 # 聚类最小规模\n```\n\n### 渲染配置\n\n```typescript\ninterface ClaimsConfig {\n half_life_days: number;\n effective_floor: number;\n render_min_confidence: number; // 仅渲染高于此值的主张\n include_unvalidated: boolean; // 是否包含未验证主张\n}\n```\n\n资料来源：[src/core/claim-render.ts:1-60]()\n\n---\n\n## 工具注册与集成\n\n### 工具清单\n\n| 工具名称 | 功能 | 源码位置 |\n|----------|------|----------|\n| `vault.claim-submit` | 提交新主张 | src/tools/claim.ts |\n| `vault.claim-retract` | 撤回主张 | src/tools/claim.ts |\n| `vault.claim-read` | 读取主张详情 | src/tools/claim.ts |\n| `vault.evolve-profile` | 触发画像进化 | src/tools/evolve-profile.ts |\n| `vault.lint` | Claims相关检查 | src/tools/lint.ts |\n\n### Lint检查集成\n\nClaims系统与lint检查模块集成，提供以下质量保障规则：\n\n- **claim-key-collision**：检测重复主张\n- **claim-effective-below-floor**：标记有效置信度过低的主张\n- **claim-without-evidence**：检测缺少证据的主张\n- **claim-tag-repo-prefix-malformed**：标签格式校验\n\n资料来源：[src/tools/lint.ts:1-30]()\n\n---\n\n## 与其他系统模块的交互\n\n### 与索引系统的集成\n\nClaims的增删改查通过ClaimsStore与索引系统同步：\n\n```mermaid\nsequenceDiagram\n 参与者 Agent->>ClaimsStore: submit(claim)\n ClaimsStore->>Index: upsertPage(frontmatter)\n Index->>ClaimsStore: 返回索引结果\n ClaimsStore->>参与者 Agent: 返回claim_id\n```\n\n### 与Profile系统的集成\n\nEvolution结果直接作用于Profile：\n\n1. Evolution输出的`specialties`更新到Profile的`specialties`字段\n2. `moveset_suggestions`提供可选的技能扩展路径\n3. Profile的`evolution_stage`根据Claims累积量自动推进\n\n### 与合成系统的集成\n\nClaims聚类结果为`synthesize`工具提供素材：\n\n- 聚类标签直接作为合成主题建议\n- 高置信度Claims作为合成内容的证据来源\n- 有效置信度作为Claims在合成中的权重因子\n\n资料来源：[src/core/evolution.ts:80-120]()\n\n---\n\n## 最佳实践\n\n### 提高主张置信度\n\n1. **提供充分证据**：引用多个相关页面\n2. **主动验证**：定期重新验证旧主张\n3. **多人验证**：让多个智能体验证同一主张\n\n### 避免主张被拒绝\n\n1. 新主张置信度必须严格高于现有主张\n2. 确保证据页面真实存在且可访问\n3. 使用规范化的标签命名\n\n### 有效利用进化系统\n\n1. 保持Claims数量在触发阈值以上\n2. 关注高置信度Claims集中的领域\n3. 根据进化建议选择可学习的移动\n\n---\n\n<a id='cli-commands'></a>\n\n## CLI命令参考\n\n### 相关页面\n\n相关主题：[任务协作系统](#task-coordination)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/cli/commands/recall.ts](https://github.com/BrettNye/stoa/blob/main/src/cli/commands/recall.ts)\n- [src/cli/commands/inbox.ts](https://github.com/BrettNye/stoa/blob/main/src/cli/commands/inbox.ts)\n- [src/cli/commands/synthesize.ts](https://github.com/BrettNye/stoa/blob/main/src/cli/commands/synthesize.ts)\n- [src/cli/commands/channel-post.ts](https://github.com/BrettNye/stoa/blob/main/src/cli/commands/channel-post.ts)\n- [src/cli/commands/task-create.ts](https://github.com/BrettNye/stoa/blob/main/src/cli/commands/task-create.ts)\n- [src/cli/commands/bootstrap-repo.ts](https://github.com/BrettNye/stoa/blob/main/src/cli/commands/bootstrap-repo.ts)\n- [src/cli/commands/new-wiki.ts](https://github.com/BrettNye/stoa/blob/main/src/cli/commands/new-wiki.ts)\n</details>\n\n# CLI命令参考\n\n本文档全面介绍 stoa CLI 的命令结构、用法模式及核心命令详解。stoa 是一个基于 MCP（Model Context Protocol）的知识库管理系统，通过命令行接口提供笔记检索、内容捕获、任务协作等功能。\n\n## 概述\n\nstoa CLI 是 vault-mcp 服务器的命令行封装，提供与 MCP 工具等效的操作能力。所有命令均支持通过 `--vault` 参数指定 vault 路径，或通过环境变量 `STOA_VAULT_PATH` 设置默认路径。资料来源：[README.md:1-50]()\n\n```bash\nstoa --vault=/path/to/vault recall <topic>\nstoa --vault=/path/to/vault inbox \"thought to capture\"\nstoa --vault=/path/to/vault list-wikis\n```\n\n环境变量 `STOA_VAULT_PATH` 可替代每次调用时的 `--vault=` 参数，提升使用效率。资料来源：[README.md:45-50]()\n\n## 命令架构\n\nstoa CLI 采用Commander框架进行命令解析，支持多层级子命令结构。命令注册遵循统一模式，每个命令模块负责注册自身的参数解析和行为逻辑。资料来源：[src/cli/commands/new-wiki.ts:1-15]()\n\n```mermaid\ngraph TD\n A[stoa CLI] --> B[--vault 路径选项]\n A --> C[命令主体]\n C --> D[recall]\n C --> E[inbox]\n C --> F[synthesize]\n C --> G[channel-post]\n C --> H[task-create]\n C --> I[bootstrap-repo]\n C --> J[new-wiki]\n C --> K[list-wikis]\n```\n\n## 核心命令详解\n\n### recall — 主题检索\n\n`recall` 命令根据关键词检索 vault 中的相关页面，返回匹配的页面列表及相关性评分。\n\n```bash\nstoa --vault=/path/to/vault recall <topic>\n```\n\n**功能说明：** 该命令通过全文索引和分词机制匹配包含指定主题的笔记内容，返回最多25条相关结果。资料来源：[src/core/index.ts:1-30]()\n\n检索结果包含页面ID、标题、wiki归属及更新时间等元数据，支持通过 `--limit` 参数调整返回数量。\n\n### inbox — 快速捕获\n\n`inbox` 命令用于即时捕获思绪或临时笔记，将其写入当前激活 wiki 的 inbox 目录。\n\n```bash\nstoa --vault=/path/to/vault inbox \"thought to capture\"\n```\n\n**功能说明：** 捕获的内容会自动添加时间戳并生成唯一ID，适合记录快速闪现的想法而不打乱现有工作流。资料来源：[src/cli/commands/inbox.ts:1-20]()\n\n### synthesize — 合成页面生成\n\n`synthesize` 命令从多个源页面编译生成综合报告，适用于知识整合与摘要生成场景。\n\n```bash\nstoa --vault=/path/to/vault synthesize --topic \"主题名称\"\n```\n\n**功能说明：** 系统根据主题相关性从 vault 中选取相关页面，自动生成包含引用来源的综合文档。生成结果保存为 `synthesis-*.md` 格式的草稿页面。资料来源：[src/core/synthesize.ts:1-50]()\n\n### channel-post — 频道消息发布\n\n`channel-post` 用于向协调频道发布消息，支持跨实例通信与任务协调。\n\n```bash\nstoa --vault=/path/to/vault channel-post --channel <channel-name> --message <content>\n```\n\n**功能说明：** 频道消息遵循 YAML 格式规范，支持结构化数据传递。消息发布后可供其他 MCP 客户端或订阅者消费。资料来源：[src/cli/commands/channel-post.ts:1-25]()\n\n### task-create — 任务创建\n\n`task-create` 命令用于在 vault 中创建新任务，支持原子性任务声明与竞态处理。\n\n```bash\nstoa --vault=/path/to/vault task-create --title <title> --description <desc>\n```\n\n**功能说明：** 任务创建采用乐观锁机制防止并发冲突，后到的声明请求会收到 `AlreadyClaimedError` 错误。资料来源：[README.md:30-35]()\n\n### bootstrap-repo — 仓库引导\n\n`bootstrap-repo` 命令为消费仓库初始化 MCP 配置和 CLAUDE.md 片段，建立与 vault 的连接。\n\n```bash\nstoa --vault=/path/to/vault bootstrap-repo --target <repo-path>\n```\n\n**功能说明：** 该命令在目标仓库中写入 `.mcp.json` 配置文件和 `CLAUDE.md` 引导文件，完成自动化集成设置。资料来源：[src/cli/commands/bootstrap-repo.ts:1-20]()\n\n### new-wiki — 新建 Wiki\n\n`new-wiki` 命令脚手架化一个新的 wiki 空间，包括必要的文件夹结构和初始化文件。\n\n```bash\nstoa new-wiki <name> --mode <mode> --scope <scope>\n```\n\n**参数说明：**\n\n| 参数 | 必填 | 说明 |\n|------|------|------|\n| `<name>` | 是 | Wiki 名称 |\n| `--mode` | 是 | 创建模式：idea-map、project-doc、learning、mixed |\n| `--scope` | 是 | Wiki 作用域定义 |\n\n**功能说明：** 新建的 wiki 包含 `map.md`、`index.md`、wiki 本地的 `CLAUDE.md` 等标准文件。资料来源：[src/cli/commands/new-wiki.ts:1-18]()\n\n## 环境变量\n\n| 变量名 | 说明 | 优先级 |\n|--------|------|--------|\n| `STOA_VAULT_PATH` | 设置默认 vault 路径 | 高于 `.active-wiki` 文件 |\n| `STOA_DEFAULT_WIKI` | 设置默认 wiki 名称 | 高于配置文件 |\n| `STOA_DEFAULT_FAMILY` | 设置默认家族名称 | 高于配置文件 |\n\n环境变量设置后可省略 `--vault` 参数，直接使用命令主体。资料来源：[README.md:45-50]()\n\n## Wiki 参数解析顺序\n\n当命令涉及 wiki 作用域时，系统按以下优先级解析 wiki 标识：\n\n1. 显式 `wiki:` 参数\n2. `--default-wiki=<name>` 服务器启动参数\n3. vault 根目录的 `.active-wiki` 文件\n4. 无匹配时抛出错误\n\n资料来源：[README.md:40-45]()\n\n## 命令执行流程\n\n```mermaid\nsequenceDiagram\n participant CLI as 命令行\n participant CMD as 命令处理器\n participant CORE as 核心模块\n participant FS as 文件系统\n \n CLI->>CMD: 解析参数与选项\n CMD->>CMD: 加载上下文配置\n CMD->>CORE: 调用核心业务逻辑\n CORE->>FS: 读写 vault 数据\n FS-->>CORE: 返回操作结果\n CORE-->>CMD: 格式化输出\n CMD-->>CLI: 显示结果\n```\n\n## 输出格式\n\nCLI 命令的输出遵循统一格式，包含操作状态和结果数据：\n\n- **成功操作：** 返回 JSON 格式的结构化结果\n- **错误情况：** 返回错误码和描述信息\n- **列表查询：** 返回数组格式的多项结果\n\n## 相关命令索引\n\n| 分类 | 命令 | 功能 |\n|------|------|------|\n| 读取 | recall | 主题检索 |\n| 写入 | inbox | 快速捕获 |\n| 写入 | synthesize | 合成页面 |\n| 协作 | channel-post | 频道消息 |\n| 协作 | task-create | 任务创建 |\n| 系统 | bootstrap-repo | 仓库引导 |\n| 系统 | new-wiki | 新建 wiki |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：BrettNye/stoa\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1229401738 | https://github.com/BrettNye/stoa | host_targets=mcp_host, claude, claude_code\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1229401738 | https://github.com/BrettNye/stoa | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1229401738 | https://github.com/BrettNye/stoa | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1229401738 | https://github.com/BrettNye/stoa | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | release_recency=unknown\n\n<!-- canonical_name: BrettNye/stoa; human_manual_source: deepwiki_human_wiki -->\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：BrettNye/stoa\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1229401738 | https://github.com/BrettNye/stoa | host_targets=mcp_host, claude, claude_code\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1229401738 | https://github.com/BrettNye/stoa | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1229401738 | https://github.com/BrettNye/stoa | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1229401738 | https://github.com/BrettNye/stoa | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1229401738 | https://github.com/BrettNye/stoa | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# stoa - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 stoa 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Persistent shared memory for AI coding agents (MCP server + CLI) 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. concepts：核心概念。围绕“核心概念”模拟一次用户任务，不展示安装或运行结果。\n3. architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. eventbus：事件总线系统。围绕“事件总线系统”模拟一次用户任务，不展示安装或运行结果。\n5. recall-system：召回与检索系统。围绕“召回与检索系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. concepts\n输入：用户提供的“核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. eventbus\n输入：用户提供的“事件总线系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. recall-system\n输入：用户提供的“召回与检索系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / concepts：Step 2 必须围绕“核心概念”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / eventbus：Step 4 必须围绕“事件总线系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / recall-system：Step 5 必须围绕“召回与检索系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/BrettNye/stoa\n- https://github.com/BrettNye/stoa#readme\n- README.md\n- package.json\n- src/config.ts\n- src/core/wikis.ts\n- src/core/claims.ts\n- src/core/pages.ts\n- src/core/profiles.ts\n- src/core/scope-hash.ts\n- src/cli/index.ts\n- src/core/index.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 stoa 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：BrettNye/stoa\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm i -g @stoa-mcp/cli\n```\n\n来源：https://github.com/BrettNye/stoa#readme\n\n## 来源\n\n- repo: https://github.com/BrettNye/stoa\n- docs: https://github.com/BrettNye/stoa#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_413b9b2eea374cd085b8ac7ceb0dd907"
}