# https://github.com/phasespace-labs/palinode 项目说明书 生成时间：2026-06-25 01:34:31 UTC ## 目录 - [概述与系统架构](#page-overview) - [记忆引擎：存储、索引、检索与压缩](#page-memory-engine) - [接口与多平台集成](#page-interfaces) - [部署、运维与诊断](#page-deployment) ## 概述与系统架构 ### 相关页面 相关主题：[记忆引擎：存储、索引、检索与压缩](#page-memory-engine), [接口与多平台集成](#page-interfaces)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md) - [palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py) - [palinode/api/enrichment.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/enrichment.py) - [palinode/api/routers/memory.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py) - [palinode/api/ui/render.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/render.py) - [palinode/cli/init.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/init.py) - [palinode/cli/obsidian_sync.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py) - [palinode/cli/embedding_tools.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py) - [claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md)
# 概述与系统架构 ## 1. 项目定位与核心理念 Palinode 是一个**本地优先（local-first）的智能体记忆层（agent memory layer）**，其设计目标是为 AI 编程助手提供跨 IDE、跨会话的持久化记忆能力。根据 [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md) 的描述，Palinode 的核心理念可概括为四点： | 理念 | 含义 | | --- | --- | | **Your data, your files** | 记忆以纯 Markdown 文件形式存储，无云端依赖，导出即 `cp`，备份即 `git push` | | **Cross-IDE memory** | 一份记忆可同时被 Claude Code、Cursor、Windsurf、Zed 等 MCP 兼容编辑器访问 | | **Git operations as agent tools** | `diff`、`blame`、`rollback`、`push` 通过 MCP 暴露给智能体调用 | | **Operation-based compaction** | KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE DSL 由 LLM 提议，由确定性执行器落地为可审查的 git 提交 | 这种"git 作为真相之源"的范式使得每一次记忆压缩都可追溯，避免了 LLM 在 wiki 场景下"无引用综合、脱离源头仍不自知、呈现虚假确定性"的问题（参见 [issue #65](https://github.com/phasespace-labs/palinode/issues/65)）。 ## 2. 系统组件与分层架构 Palinode 在运行时由四个相互协作的进程/包组成： ```mermaid flowchart TB subgraph Editor["IDE / Agent (MCP Client)"] IDE[Claude Code / Cursor / Zed / VS Code] end subgraph MCP["MCP 层"] StdIO[palinode-mcp (stdio)] HTTP[palinode-api (HTTP :6340)] end subgraph Core["核心服务层"] Memory[memory_write.py / routers/memory.py] Enrich[enrichment.py (LLM 摘要)] Render[ui/render.py (Markdown 渲染)] end subgraph Store["存储层"] MD[(Markdown 文件)] Git[(git 历史)] Index[(嵌入向量 + FTS)] end IDE -->|JSON-RPC| StdIO StdIO --> HTTP HTTP --> Memory HTTP --> Enrich HTTP --> Render Memory --> MD Memory --> Git Memory --> Index ``` 各层职责如下： - **MCP 传输层**：[claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md) 指出 `palinode-mcp`（stdio）与 `palinode-api`（本地 HTTP，端口 6340）协同工作；客户端通过 `curl http://localhost:6340/status` 验证 `ollama_reachable` 状态。 - **路由与写入路径**：[palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py) 负责保存前的归一化：实体引用补全 `category/` 前缀、生成 `## See also` 自动页脚（带 `` 标记）、解析 `source` 归属。 - **LLM 富化层**：[palinode/api/enrichment.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/enrichment.py) 通过集中式 CHAT 客户端调用 Ollama，生成单句描述；失败时回退到首行抽取。 - **渲染与 UI**：[palinode/api/ui/render.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/render.py) 采用 `markdown-it-py`（禁用 HTML）+ `nh3` 双重消毒，专门防御来自智能体生成内容的 XSS 攻击。 - **CLI 工具集**：`palinode init`（[palinode/cli/init.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/init.py)）搭建 `people/`、`projects/`、`decisions/`、`insights/`、`research/` 等目录；`palinode obsidian-sync`（[palinode/cli/obsidian_sync.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py)）为存量文件回填 wiki 页脚；`palinode orphan-repair`（[palinode/cli/embedding_tools.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py)）通过语义相似度修复破损 `[[wikilink]]`。 ## 3. 记忆生命周期关键路径 Palinode 的记忆生命周期可拆解为四个核心动作： 1. **写入（Save）**：智能体调用 `/save` 端点，[palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py) 中的 `_apply_wiki_footer` 与 `_normalize_entities` 在落盘前补全 wikilink 页脚与实体前缀。同一函数保证幂等性：再次保存时已存在的页脚被原地替换。 2. **索引（Watch & Embed）**：文件系统变更触发 watcher，[palinode/api/routers/memory.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py) 中 `_generate_description` 仅对位于 `_MEMORY_CATEGORY_DIRS` 下的文件触发 LLM 调用；`daily/`、`archive/`、`specs/` 等结构文件被明确排除，避免无谓推理。 3. **检索（4-Phase Injection）**：根据 [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md) 的描述，注入分为 Core（始终注入）+ Topic（按回合检索）+ Associative（实体图谱）+ Triggered（前瞻式回忆）。 4. **压缩（Compaction）**：LLM 提议 KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE 操作，由确定性执行器落地为 git 提交；每次提交保留 `` 内联 ID 以便按事实寻址。 ## 4. 部署形态与社区关注点 当前 Palinode 主推**本地部署**：stdio 传输给本地 IDE、HTTP 暴露给同局域网的其他客户端。该形态直接导致了两个尚未完成的社区议题—— - **Anthropic Connectors Directory 提交**（[issue #62](https://github.com/phasespace-labs/palinode/issues/62)）被推迟，因为官方市场要求 MCPB 桌面扩展或远程 MCP，而 Palinode 的"本地优先"定位暂时无法满足； - **多平台安装文档**（[issue #24](https://github.com/phasespace-labs/palinode/issues/24)）要求补全 Claude Code、Cursor、Zed、VS Code 的差异化配置。 相反，已落地的扩展点包括 Nix flake + systemd 服务模块（[issue #7](https://github.com/phasespace-labs/palinode/issues/7)）与即将到来的 `llms-install.md`（[issue #61](https://github.com/phasespace-labs/palinode/issues/61)），后者专门为智能体自举（agent-bootstrap）补充 Ollama 检测与虚拟环境路径规范。v0.8.15 修复的 wheel 打包遗漏 `palinode.api.routers` 缺陷也提示我们：即便设计简洁，Python 包元数据（`pyproject.toml` 中的 `packages` 列表）仍是部署完整性的常见脆弱点。 ## See Also - 内存存储与目录约定 - MCP 集成与多 IDE 配置 - 压缩操作 DSL（KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE） - CLI 工具参考（`init`、`obsidian-sync`、`orphan-repair`） - 部署清单（Ollama 配置、venv 路径、`llms-install.md`） --- ## 记忆引擎：存储、索引、检索与压缩 ### 相关页面 相关主题：[概述与系统架构](#page-overview), [接口与多平台集成](#page-interfaces)
相关源码文件 以下源码文件用于生成本页说明： - [palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py) - [palinode/api/enrichment.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/enrichment.py) - [palinode/api/routers/memory.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py) - [palinode/cli/obsidian_sync.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py) - [palinode/cli/init.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/init.py) - [palinode/cli/import_vault.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/import_vault.py) - [palinode/cli/embedding_tools.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py) - [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md) - [claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md)
# 记忆引擎：存储、索引、检索与压缩 Palinode 的记忆引擎是一个本地优先（local-first）的智能体记忆层，它把 markdown 文件、git 历史、SQLite 矢量索引与一个 LLM 增强管线组合成一个完整的数据回路。其核心目标是用纯文本文件 + 单一嵌入式索引，让代理在不同 IDE 之间共享上下文，同时通过 git 提供完整审计追溯能力。 ## 总体架构 记忆引擎可分为四层：**存储层**（markdown + git）、**索引层**（SQLite-vec + FTS5 + 实体图）、**检索层**（MCP 工具集 + 4 阶段注入）与**整合层**（KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE 操作 + 自动描述/摘要）。四层之间通过 `palinode/api/routers/memory.py` 中描述的写入/回填流水线衔接：保存一条记忆 → 自动追加 `## See also` 页脚 → 异步生成 `description` / `summary` → 重建向量。 ```mermaid flowchart LR A[Markdown
+ Frontmatter] -->|git write| B[存储层] B -->|watcher| C[索引层
SQLite-vec + FTS5] C -->|hybrid search| D[检索层
4-phase injection] D -->|MCP tool| E[Agent / IDE] E -->|KEEP/UPDATE/
MERGE/SUPERSEDE/
ARCHIVE| F[整合层] F -->|deterministic
executor| B F -->|LLM one-liner| G[description
+ summary] G -->|write-back| B ``` ## 存储层：Markdown 即真相之源 存储层把记忆直接落到磁盘上的 markdown 文件，并在 YAML frontmatter 中携带元数据。元数据类别决定了文件归属哪一类实体前缀（用于 wikilink 解析）： | 目录 | 实体前缀 | 用途 | |------|---------|------| | `people/` | `person/` | 联系人、合作者 | | `projects/` | `project/` | 进行中与归档项目 | | `decisions/` | `decision/` | 架构与设计决策 | | `insights/` | `insight/` | 可复用经验 | | `research/` | `research/` | 背景资料 | | `inbox/` | `action/` | 待整理输入 | | `archive/` | — | 已被 SUPERSEDE/ARCHIVE 操作取代的内容 | 类别映射和实体归一化逻辑集中在 `palinode/api/memory_write.py` 的 `_CATEGORY_TO_ENTITY_PREFIX` 与 `_normalize_entities` 中：裸字符串（无 `/`）会根据当前记忆的 `category` 自动补上前缀，未知类别则回退到 `project/`。这样 `palinode save` 在写入时就能保证实体引用始终是 `category/slug` 的规范形式。资料来源：[palinode/api/memory_write.py:31-58]() 写入路径还会自动维护一个 `## See also` 自动页脚：`_apply_wiki_footer` 扫描正文里既有的 `[[wikilink]]`，对没有内联引用的实体生成可识别的 HTML 注释块 ``，以便 Obsidian Graph View 与 `palinode_blame` 能区分"用户写的链接"与"系统写的链接"。所有 slug 在嵌入 `[[...]]` 前都会通过 `_SAFE_SLUG_RE` 校验，防止注入 `]]bar[[` 这类破坏 markdown 结构的字符串。资料来源：[palinode/api/memory_write.py:80-148]() ## 索引层：双索引 + 实体图 引擎使用 **BGE-M3 + Ollama** 生成本地嵌入向量，向量与关键字分别存入两个嵌入式索引：向量索引使用 **SQLite-vec**（无需独立服务），关键字索引使用 **SQLite FTS5** 的 BM25（无需额外依赖）。这一选择直接写在 README 的 Stack 表中，强调"零配置、单一文件"。资料来源：[README.md]() 索引覆盖范围由 `_is_description_eligible` 等谓词控制——只有落在 `people/`、`projects/`、`decisions/`、`insights/`、`research/`、`inbox/` 这些内存目录下的文件才会进入待生成 `description` 的工作队列；`daily/`、`archive/`、`specs/` 与顶层文档的描述写回是无操作，否则会浪费推理预算在不会被持久化的输出上。资料来源：[palinode/api/memory_write.py:177-194](), [palinode/api/routers/memory.py:1-50]() 仓库移植能力来自 `palinode/cli/init.py`：它按上述目录结构脚手架化一个新工作区，并在 `.palinode/` 下维护内部索引状态——README 明确警告"不要编辑 `.palinode/`，那是守护进程管理的目录"。 ## 检索层：MCP 工具 + 4 阶段注入 检索层对外暴露统一的命名空间：每个工具既可通过 MCP 调用 `palinode_`，也可通过 CLI 调用 `palinode `，还可通过 REST API 调用 `POST/GET /`。README 列出的工具覆盖语义搜索（`search`）、实体召回（`get`）、历史回溯（`history`/`diff`/`blame`）、维基图谱维护（`cluster_neighbors` / `orphan_repair`）与诊断（`doctor` / `doctor_deep`）等场景。资料来源：[README.md](), [palinode/cli/embedding_tools.py:1-40]() 召回策略采用 4 阶段上下文注入：Core（始终注入的核心事实）+ Topic（按当前查询检索）+ Associative（沿实体图扩散）+ Triggered（前瞻性触发召回）。这意味着检索不是单一查询，而是一个把语义、关键字、实体图三类信号融合的流水线；`palinode_search` 与 `palinode_get` 都遵循这一模型。 对于已损坏的 `[[wikilink]]`，`palinode orphan-repair` 通过语义相似度（默认阈值、最小相似度）找到候选文件，用户可以据此重命名链接或新建目标条目，避免知识图谱出现死链。资料来源：[palinode/cli/embedding_tools.py:1-40]() ## 整合层：操作 DSL + 自动描述 整合层用五条结构化操作替代无差别追加：`KEEP` 保留、`UPDATE` 就地改写、`MERGE` 合并到现有文件、`SUPERSEDE` 取代旧条目（迁入 `archive/`）、`ARCHIVE` 直接归档。LLM 提议这些操作，确定性 executor（`palinode/consolidation/executor.py`）负责落地，每一次 compact 都是一次可 review、可回滚的 git commit。这种"git 操作即代理工具"是 README 中强调的差异化特性之一。资料来源：[README.md]() 写入流水线的另一端是 LLM 增强。`palinode/api/enrichment.py` 在新文件落盘后异步调用 Ollama 的 CHAT 端点生成 130 字符以内的 `description`（用于搜索摘要）与更长的 `summary`（用于 Core 注入）。提示词严格要求"一句完整的话、不被截断、不以 'The memory' 开头"，并把正文包在 `` 标签里以隔离提示注入。当 Ollama 超时或熔断器开启时，函数返回 `_DESCRIPTION_DEFERRED` 哨兵值，由 `routers/memory.py` 计数为瞬态错误，让 watcher 在下一轮重试，避免一次失败永久阻塞某个文件的描述生成。资料来源：[palinode/api/enrichment.py:1-80](), [palinode/api/routers/memory.py:1-50]() 对于历史遗留文件（写入时还没启用自动页脚），`palinode obsidian-sync` 是一条独立的回填命令：默认 dry-run，可通过 `--apply` 实际写盘，支持 `--include`/`--exclude` 限定范围，并以 `git_tools.write_memory_file` 走 git 提交路径，保证回填本身也进入审计追溯。资料来源：[palinode/cli/obsidian_sync.py:1-80]() ## 移植与互操作 当用户从已有知识库（Obsidian / Logseq / 一般 markdown 仓库）迁入时，`palinode import-vault` 会扫描源库、按类别映射到 `memory_dir//.md`、改写所有 `[[wikilink]]` 指向新 slug，并为每个文件注入最小化 frontmatter（`id`、`category`、`created_at`、`last_updated`、`source: vault-import`）。孤立的 wikilink 会被报告，建议迁移完成后跑一次 `palinode orphan-repair`。资料来源：[palinode/cli/import_vault.py:1-60]() 社区关注点 #17 指出，Palinode 的 KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE 操作词汇与 IETF Knowledge Unit 草案（`draft-farley-acta-knowledge-units`）中的生命周期操作不谋而合，这一互操作性使 Palinode 可以作为该标准的事实性实现之一。社区还提出了通过 CLAUDE.md 块复制实现"零摩擦接入"（#32）、自动项目级上下文检索（ADR-008, #28）等演进方向。 ## 常见失败模式 - **`palinode-mcp: command not found`**：MCP server 不在 PATH，重跑 `pip install -e .` 或检查 venv 的 `bin/` 是否在 PATH。资料来源：[claude-plugin/README.md]() - **`Failed to connect to Palinode API`**：`palinode-mcp`（stdio）依赖 `palinode-api`（HTTP `:6340`），先用 `curl http://localhost:6340/status` 确认 `ollama_reachable: true`。 - **`Embedder error: connection refused`**：Ollama 未运行或端口不可达，启动 `ollama serve` 后重试。 - **搜索返回空**：`palinode_status` 检查 `total_files` 与 `fts_chunks`，若都为 0 说明 watcher 尚未建索引。 ## 参见 - 见 `#17` 关于 KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE 与 IETF KU 生命周期的互操作讨论 - 见 `#28` 关于环境上下文检索（ADR-008） - 见 `#23` 通用 markdown 导入（Obsidian / 知识库） - 见 `#24` 多平台 MCP 安装文档（Claude Code / Cursor / Zed / VS Code） --- ## 接口与多平台集成 ### 相关页面 相关主题：[概述与系统架构](#page-overview), [记忆引擎：存储、索引、检索与压缩](#page-memory-engine)
相关源码文件 以下源码文件用于生成本页说明： - [palinode/cli/init.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/init.py) - [palinode/api/server.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/server.py) - [palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py) - [palinode/cli/obsidian_sync.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py) - [palinode/api/routers/memory.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py) - [palinode/api/ui/render.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/render.py) - [palinode/api/ui/templates/fact.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/fact.html) - [palinode/api/ui/templates/quality.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/quality.html) - [palinode/api/ui/templates/diffs.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/diffs.html) - [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md) - [claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md)
# 接口与多平台集成 ## 概述 Palinode 的接口与多平台集成层承担"一处记忆、多端可用"的核心承诺。系统采用双进程架构——`palinode-api` 作为 HTTP 后端服务（监听 6340 端口），`palinode-mcp` 作为 MCP stdio 客户端进程——IDE 与代理只需启动 stdio 进程即可读写同一份以纯 Markdown 文件为载体的记忆。README.md 明确指出这一承诺涵盖三大要点：**跨 IDE 记忆**、**多传输 MCP**（本地 stdio + 远程 Streamable HTTP）、**本地优先无供应商锁定**。资料来源：[README.md]() 社区长期关注该集成层的形态演化：open issue #24 指出 Claude Code、Cursor、Zed、VS Code 的安装步骤需要分平台文档化；issue #61 记录了 Cline 在空白开发机上仅凭 README 完成安装时遇到的 Ollama 检测缺口；issue #32 则推动 `palinode init` + CLAUDE.md 复制粘贴作为零摩擦接入路径。这些讨论共同决定了当前集成层以"标准化脚手架 + 可移植配置文件"作为对外契约。 ## 传输层与进程边界 集成层的第一条边界是进程边界。`claude-plugin/README.md` 中故障排查章节直接揭示了这一点：MCP 客户端进程（`palinode-mcp`，stdio 传输）与 HTTP 后端进程（`palinode-api`，监听 6340）是两个独立进程，前者作为协议适配器把 MCP 工具调用转发给后者的 REST 接口。健康检查通过 `curl http://localhost:6340/status` 完成，响应中的 `ollama_reachable` 字段是判断 Ollama 是否可达的最快信号。资料来源：[claude-plugin/README.md]() 这一解耦带来三个直接后果：第一，本地进程组天然适配 stdio 传输；第二，远程 IDE 可通过 Streamable HTTP 复用同一后端；第三，CLI 工具（如 `palinode obsidian-sync`）可直接调用 `palinode.api.server` 中的函数而无需启动 MCP 进程——`obsidian-sync` 直接导入 `_apply_wiki_footer` 并通过 `git_tools.write_memory_file` 落盘。资料来源：[palinode/cli/obsidian_sync.py]() ```mermaid flowchart LR subgraph IDE["IDE / Agent (Claude Code · Cursor · Zed · Cline)"] MCPClient["MCP stdio 客户端
palinode-mcp"] end subgraph Backend["本地后端进程"] API["palinode-api
HTTP :6340"] Router["routers/memory.py
+ search / consolidation"] Store[("Markdown 文件
+ git 历史")] end MCPClient -- "Streamable HTTP / stdio" --> API API --> Router Router --> Store Store -.->|git blame| API API -.->|/status JSON| MCPClient ``` ## 脚手架与 CLI 接入点 `palinode init` 是最直接的接入命令。`palinode/cli/init.py` 中的实现会在目标目录下创建七类记忆目录（`people/`、`projects/`、`decisions/`、`insights/`、`research/`、`archive/`、`.palinode/`），其中 `.palinode/` 由守护进程独占，用户不得手动编辑。该命令还支持 `--obsidian ` 模式，可向既有 Obsidian 仓库注入脚手架文件而保留用户已有内容。资料来源：[palinode/cli/init.py]() 针对"零摩擦接入"的目标，issue #32 推动 `palinode init` 与 `examples/CLAUDE.md` 配套使用：用户只需复制粘贴一段说明块，IDE 即可识别 Palinode 工具的语义。CLI 与 LLM 富集层（`palinode/api/enrichment.py`）通过 `_chat_primary_oneliner` 与 `_chat_fallback_oneliner` 串联，提供描述/摘要生成的链式回退路径，这是集成层在"工具调用"之外对"内容质量"另一条隐式契约。资料来源：[palinode/api/enrichment.py]() 集成层还通过路由器拆分暴露不同的能力面：`palinode/api/routers/memory.py` 中可见 `description` 与 `summary` 的资格判定函数 `_is_description_eligible`，其严格区分记忆分类目录与结构化目录（如 `daily/`、`archive/`、`specs/`），从而避免对永远不会被回写的文件浪费推理资源。资料来源：[palinode/api/routers/memory.py]() ## Obsidian 集成与 Wiki 契约 Obsidian 是 Palinode 最重要的非 MCP 集成面，因为它的图谱视图依赖 `[[wikilink]]` 链接。集成层通过 `_apply_wiki_footer` 函数维护一项"Wiki 契约"：当一篇记忆的 frontmatter 中声明了 `entities:` 但正文没有对应的内联 wikilink 时，自动在文末追加一个带哨兵标记的 `## See also` 区块，从而让 Obsidian 图谱拾取该链接。资料来源：[palinode/api/memory_write.py]() 该函数的关键不变式是**幂等性**：重写时扫描正文内的 `[[...]]` 时会先剥离自动区块自身，避免把自身的链接误判为用户已写的链接；同时通过 `_SAFE_SLUG_RE`（仅允许 `[A-Za-z0-9._-]`）拒绝任何会破坏 wikilink 语法或注入 markdown 结构的实体 slug。`palinode obsidian-sync` 是这条契约的批量维护入口——默认 dry-run，`--apply` 才会真正写入，写入通过 `git_tools.write_memory_file` 完成以保留审计链。资料来源：[palinode/cli/obsidian_sync.py]()、资料来源：[palinode/api/memory_write.py]() ## 常见失败模式与扩展路径 | 症状 | 触发条件 | 处理路径 | | --- | --- | --- | | `palinode-mcp: command not found` | Python 环境 `bin/` 不在 PATH | 重新执行 `pip install -e .` | | `Failed to connect to Palinode API` | 后端进程未启动或 6340 端口被占用 | `curl http://localhost:6340/status` 检查 | | `Embedder error: connection refused` | Ollama 未运行 | `ollama serve` 或启动 macOS 应用 | | 搜索无结果 | watcher 尚未建索引 | 调用 `palinode_status` 检查 `total_files` / `fts_chunks` | 社区中仍在追踪的扩展路径包括：Homebrew tap（issue #8，发布管线就绪后即可启用）、Nix flake + systemd 模块（issue #7，已并入主线）、向 Anthropic Connectors Directory 与社区目录（MCP Registry、Smithery、mcp.so、Cline）提交（issues #29、#35、#62，依赖 MCPB bundle 先行落地）。所有这些都建立在当前以 Markdown + git + MCP 为根的集成层之上。资料来源：[claude-plugin/README.md]()、资料来源：[README.md]() ## See Also - 记忆写入与 Wiki 契约：[palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py) - 后端 HTTP 路由：[palinode/api/routers/memory.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py) - 富集与回退链：[palinode/api/enrichment.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/enrichment.py) - 渲染与清洗：[palinode/api/ui/render.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/render.py) - CLI 初始化与同步：[palinode/cli/init.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/init.py)、[palinode/cli/obsidian_sync.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py) - Claude Code 插件接入：[claude-plugin/README.md](https://github.com/phasespace-labs/palinode/blob/main/claude-plugin/README.md) - 相关社区议题：#24（多平台 MCP 文档）、#32（CLAUDE.md 零摩擦）、#60（OpenClaw / Hermes-agent 集成）、#61（`llms-install.md`） --- ## 部署、运维与诊断 ### 相关页面 相关主题：[概述与系统架构](#page-overview), [接口与多平台集成](#page-interfaces)
相关源码文件 以下源码文件用于生成本页说明： - [palinode/cli/init.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/init.py) - [palinode/cli/obsidian_sync.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/obsidian_sync.py) - [palinode/cli/import_vault.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/import_vault.py) - [palinode/cli/embedding_tools.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/cli/embedding_tools.py) - [palinode/api/routers/memory.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/routers/memory.py) - [palinode/api/enrichment.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/enrichment.py) - [palinode/api/ui/templates/quality.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/quality.html) - [palinode/api/ui/templates/diffs.html](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/ui/templates/diffs.html) - [palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py) - [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md)
# 部署、运维与诊断 ## 概述 Palinode 是一个本地优先（local-first）的 AI 智能体记忆系统，采用"你的数据就是 markdown 文件"的设计哲学——存储即 `cp`，备份即 `git push`，灾难时 `cat` 仍可读。这一形态决定其部署与运维工作与传统数据库系统截然不同：初始化产物是文件系统脚手架，运维命令是 git 子命令集，诊断信号则内嵌在 UI 仪表板中。本页聚焦从首次部署到日常运维、再到故障定位的完整生命周期。资料来源：[README.md:5-15]() ## 1. 首次部署：脚手架与目录布局 `palinode init` 命令承担首次部署职责，会在 `~/.palinode/memory/`（或由 `PALINODE_DIR` 覆盖的路径）下创建一份受管目录树。已存在的文件**默认保留**（仅跳过新建），加 `--force` 时被覆盖。资料来源：[palinode/cli/init.py:7-42]() | 目录 | 用途 | |------|------| | `daily/` | 时间日志，访问最高频 | | `inbox/` | 待分类动作项 | | `people/` | 联系人/协作者/实体 | | `projects/` | 进行中与归档的项目笔记 | | `decisions/` | 架构与设计决策记录 | | `insights/` | 可复用的发现 | | `research/` | 背景资料与参考 | | `archive/` | 已被 SUPERSEDE 的旧内容 | | `.palinode/` | 内部索引状态——**禁止手工编辑** | `--obsidian ` 标志会同时让脚手架在指定 vault 下重建（用户已编辑文件保持原样），便于把已有 Obsidian 知识库并入 Palinode 仓库。资料来源：[palinode/cli/init.py:42-50]() ## 2. 持续运维：Wiki 合约、孤儿链接与 vault 导入 ### 2.1 Wiki 合约回填 所有 `palinode_save` 写出的新文件会自动追加 `` 标记的 `## See also` 块，把 `entities` 列表转成 `[[wikilink]]` 以便 Obsidian 图谱视图拾取。资料来源：[palinode/api/memory_write.py:13-21]() 对于 v0.6.0 之前遗留的文件，`palinode obsidian-sync` 批量回填这一合约：默认**干运行**，打印"would update: …"清单；加 `--apply` 后才落盘。`--include` / `--exclude` 支持 fnmatch 过滤。退出码 0 = 全成功，1 = 至少一个文件解析或写入失败。资料来源：[palinode/cli/obsidian_sync.py:1-40]() ### 2.2 孤儿链接修复 `palinode orphan-repair` 接收一个损坏的 `[[wikilink]]` 目标，按语义相似度返回 top-k 候选文件，运维人员可据此选择重定向或新建。资料来源：[palinode/cli/embedding_tools.py:14-36]() ### 2.3 Vault 导入 `palinode import-vault [--into ] [--apply]` 把外部 markdown 库映射到 `memory_dir//.md`，**重写** `[[wikilink]]` 至新 slug 化的目标，并在 frontmatter 中写入 `source: "vault-import"`。孤立的 wikilink 不会被自动改写，而是被报告给后续的 `palinode orphan-repair`。默认干运行。资料来源：[palinode/cli/import_vault.py:1-24]() ## 3. 诊断：UI 仪表板与质量队列 `/quality` 页面把 `lint` 输出的待办按队列分组（矛盾、未归档、孤儿链接等），每项直接链接到对应的 fact 文件。空队列显示"Nothing here — clean."，便于一眼判断存储健康度。资料来源：[palinode/api/ui/templates/quality.html:1-30]() `/diffs` 页面按天聚合最近 N 天的 git 提交，commit hash 与时间戳并列，点击文件名跳转至该 fact 视图。无提交时显示"No memory changes in the last N days (or the store is not a git repo)."——后者同时充当"是否成功初始化 git 仓库"的诊断信号。资料来源：[palinode/api/ui/templates/diffs.html:1-30]() `/memory/` 渲染单条 fact 的 detail 页，包含 provenance 侧栏；若 `broken_seal` 标志被设置，pill 显示"tampered"与"✕ seal broken"，否则为"verified"与"✓ chain intact"——这提供了**写入路径完整性**的视觉判断。资料来源：[palinode/api/ui/templates/fact.html:1-22]() ## 4. 常见失败模式与退避 `save_api` 写盘后若启用了 `auto_summary`，会调用本地 Ollama 生成描述/摘要。`_generate_summary` 在 `OllamaTimeout` 或 `OllamaCircuitOpen` 异常下返回空串，由 watcher 在下一轮重试——避免单次慢请求阻塞整个保存路径。`description` 同样使用 `_DESCRIPTION_DEFERRED` 哨兵值区分"成功但为空"与"被熔断跳过"，确保仅在合法条件下计入 `desc_count`。资料来源：[palinode/api/routers/memory.py:8-30]() 资料来源：[palinode/api/enrichment.py:1-20]() 正文与 frontmatter 中的实体引用必须经 `_normalize_entities` 加 `category/` 前缀；裸 slug 通过 `CATEGORY_TO_ENTITY_PREFIX` 映射（`people→person`、`decisions→decision` 等），未知 category 兜底为 `project/`。资料来源：[palinode/api/memory_write.py:1-12]() 实体 slug 在作为 `[[wikilink]]` 输出前会被 `_SAFE_SLUG_RE` 校验，禁止 `[ ] |` 与空白字符——防止恶意 slug 注入额外 markdown 结构破坏图谱渲染。资料来源：[palinode/api/memory_write.py:22-30]() ## 部署流程示意 ```mermaid flowchart TD A[palinode init] --> B[脚手架 + git init] B --> C{首次使用?} C -- 是 --> D[palinode save / MCP 写入] C -- 否，已有 vault --> E[palinode import-vault] D --> F[自动生成 description/summary] F --> G[Git commit 写入] E --> H[palinode orphan-repair] G --> I{旧文件?} I -- 是 --> J[palinode obsidian-sync --apply] I -- 否 --> K[健康仪表板 /quality /diffs] H --> K J --> K K --> L{异常?} L -- 描述延迟 --> M[watcher 下一轮重试] L -- seal broken --> N[人工 git fsck / 回滚] ``` ## See Also - [README.md](https://github.com/phasespace-labs/palinode/blob/main/README.md) — 项目总览与设计哲学 - [palinode/api/memory_write.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/memory_write.py) — 写入路径归一化与脚注合并 - [palinode/api/enrichment.py](https://github.com/phasespace-labs/palinode/blob/main/palinode/api/enrichment.py) — LLM 摘要/描述生成的退避策略 - Issue #61 — 关于 `llms-install.md`（Ollama 检测与 venv 路径规范）的运维摩擦点 - Issue #8 — `brew install palinode` 计划，将封装上述 CLI 入口为 Homebrew formula --- --- ## Doramagic 踩坑日志 项目：phasespace-labs/palinode 摘要：发现 34 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: Add llms-install.md for agent-bootstrap (Ollama detection + venv-path discipline)。 ## 1. 安装坑 · 失败模式：installation: Add llms-install.md for agent-bootstrap (Ollama detection + venv-path discipline) - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Add llms-install.md for agent-bootstrap (Ollama detection + venv-path discipline) - 对用户的影响：Developers may fail before the first successful local run: Add llms-install.md for agent-bootstrap (Ollama detection + venv-path discipline) - 证据：failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/61 | Add llms-install.md for agent-bootstrap (Ollama detection + venv-path discipline) ## 2. 安装坑 · 失败模式：installation: Anthropic Connectors Directory submission (after MCPB bundle ships) - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Anthropic Connectors Directory submission (after MCPB bundle ships) - 对用户的影响：Developers may fail before the first successful local run: Anthropic Connectors Directory submission (after MCPB bundle ships) - 证据：failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/62 | Anthropic Connectors Directory submission (after MCPB bundle ships) ## 3. 安装坑 · 失败模式：installation: Build in public — show Palinode building Palinode - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Build in public — show Palinode building Palinode - 对用户的影响：Developers may fail before the first successful local run: Build in public — show Palinode building Palinode - 证据：failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/33 | Build in public — show Palinode building Palinode ## 4. 安装坑 · 失败模式：installation: CLAUDE.md integration — zero-friction adoption path - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: CLAUDE.md integration — zero-friction adoption path - 对用户的影响：Developers may fail before the first successful local run: CLAUDE.md integration — zero-friction adoption path - 证据：failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/32 | CLAUDE.md integration — zero-friction adoption path ## 5. 安装坑 · 失败模式：installation: Directory submissions — MCP Registry, Smithery, mcp.so, Cline - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Directory submissions — MCP Registry, Smithery, mcp.so, Cline - 对用户的影响：Developers may fail before the first successful local run: Directory submissions — MCP Registry, Smithery, mcp.so, Cline - 证据：failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/35 | Directory submissions — MCP Registry, Smithery, mcp.so, Cline ## 6. 安装坑 · 失败模式：installation: Docs: public integration guide for OpenClaw and Hermes-agent - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Docs: public integration guide for OpenClaw and Hermes-agent - 对用户的影响：Developers may fail before the first successful local run: Docs: public integration guide for OpenClaw and Hermes-agent - 证据：failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/60 | Docs: public integration guide for OpenClaw and Hermes-agent ## 7. 安装坑 · 失败模式：installation: Homebrew tap (brew install palinode) - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Homebrew tap (brew install palinode) - 对用户的影响：Developers may fail before the first successful local run: Homebrew tap (brew install palinode) - 证据：failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/8 | Homebrew tap (brew install palinode) ## 8. 安装坑 · 失败模式：installation: Multi-platform MCP and integration docs (Claude Code, Cursor, Zed, VS Code) - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Multi-platform MCP and integration docs (Claude Code, Cursor, Zed, VS Code) - 对用户的影响：Developers may fail before the first successful local run: Multi-platform MCP and integration docs (Claude Code, Cursor, Zed, VS Code) - 证据：failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/24 | Multi-platform MCP and integration docs (Claude Code, Cursor, Zed, VS Code) ## 9. 安装坑 · 失败模式：installation: v0.8.13 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.8.13 - 对用户的影响：Upgrade or migration may change expected behavior: v0.8.13 - 证据：failure_mode_cluster:github_release | https://github.com/phasespace-labs/palinode/releases/tag/v0.8.13 | v0.8.13 ## 10. 安装坑 · 失败模式：installation: v0.8.15 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.8.15 - 对用户的影响：Upgrade or migration may change expected behavior: v0.8.15 - 证据：failure_mode_cluster:github_release | https://github.com/phasespace-labs/palinode/releases/tag/v0.8.15 | v0.8.15 ## 11. 安装坑 · 来源证据：Add llms-install.md for agent-bootstrap (Ollama detection + venv-path discipline) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add llms-install.md for agent-bootstrap (Ollama detection + venv-path discipline) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/phasespace-labs/palinode/issues/61 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 12. 安装坑 · 来源证据：Build in public — show Palinode building Palinode - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Build in public — show Palinode building Palinode - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/phasespace-labs/palinode/issues/33 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 13. 安装坑 · 来源证据：CLAUDE.md integration — zero-friction adoption path - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：CLAUDE.md integration — zero-friction adoption path - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/phasespace-labs/palinode/issues/32 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 14. 安装坑 · 来源证据：Docs: public integration guide for OpenClaw and Hermes-agent - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs: public integration guide for OpenClaw and Hermes-agent - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/phasespace-labs/palinode/issues/60 | 来源类型 github_issue 暴露的待验证使用条件。 ## 15. 安装坑 · 来源证据：Homebrew tap (brew install palinode) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Homebrew tap (brew install palinode) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/phasespace-labs/palinode/issues/8 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 16. 安装坑 · 来源证据：Migrate plugin from before_agent_start to before_prompt_build - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Migrate plugin from before_agent_start to before_prompt_build - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/phasespace-labs/palinode/issues/2 | 来源类型 github_issue 暴露的待验证使用条件。 ## 17. 安装坑 · 来源证据：Multi-platform MCP and integration docs (Claude Code, Cursor, Zed, VS Code) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Multi-platform MCP and integration docs (Claude Code, Cursor, Zed, VS Code) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/phasespace-labs/palinode/issues/24 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 18. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/phasespace-labs/palinode | host_targets=openclaw, mcp_host, claude_code, claude, cursor, codex ## 19. 配置坑 · 失败模式：configuration: Ambient context search: automatic project-aware retrieval (ADR-008) - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Ambient context search: automatic project-aware retrieval (ADR-008) - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Ambient context search: automatic project-aware retrieval (ADR-008) - 证据：failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/28 | Ambient context search: automatic project-aware retrieval (ADR-008) ## 20. 配置坑 · 失败模式：configuration: Anthropic Connectors Directory: submission prep - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Anthropic Connectors Directory: submission prep - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Anthropic Connectors Directory: submission prep - 证据：failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/29 | Anthropic Connectors Directory: submission prep ## 21. 配置坑 · 失败模式：configuration: Interop: Palinode's KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE maps to IETF KU lifecycle - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Interop: Palinode's KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE maps to IETF KU lifecycle - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Interop: Palinode's KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE maps to IETF KU lifecycle - 证据：failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/17 | Interop: Palinode's KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE maps to IETF KU lifecycle ## 22. 配置坑 · 失败模式：configuration: v0.8.12 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.8.12 - 对用户的影响：Upgrade or migration may change expected behavior: v0.8.12 - 证据：failure_mode_cluster:github_release | https://github.com/phasespace-labs/palinode/releases/tag/v0.8.12 | v0.8.12 ## 23. 配置坑 · 失败模式：configuration: v0.8.14 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.8.14 - 对用户的影响：Upgrade or migration may change expected behavior: v0.8.14 - 证据：failure_mode_cluster:github_release | https://github.com/phasespace-labs/palinode/releases/tag/v0.8.14 | v0.8.14 ## 24. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/phasespace-labs/palinode | README/documentation is current enough for a first validation pass. ## 25. 维护坑 · 失败模式：migration: Migrate plugin from before_agent_start to before_prompt_build - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this migration risk before relying on the project: Migrate plugin from before_agent_start to before_prompt_build - 对用户的影响：Developers may hit a documented source-backed failure mode: Migrate plugin from before_agent_start to before_prompt_build - 证据：failure_mode_cluster:github_issue | https://github.com/phasespace-labs/palinode/issues/2 | Migrate plugin from before_agent_start to before_prompt_build ## 26. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/phasespace-labs/palinode | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/phasespace-labs/palinode | no_demo; severity=medium ## 28. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/phasespace-labs/palinode | no_demo; severity=medium ## 29. 安全/权限坑 · 来源证据：Anthropic Connectors Directory submission (after MCPB bundle ships) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Anthropic Connectors Directory submission (after MCPB bundle ships) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/phasespace-labs/palinode/issues/62 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 30. 安全/权限坑 · 来源证据：Anthropic Connectors Directory: submission prep - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Anthropic Connectors Directory: submission prep - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/phasespace-labs/palinode/issues/29 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 31. 安全/权限坑 · 来源证据：Directory submissions — MCP Registry, Smithery, mcp.so, Cline - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Directory submissions — MCP Registry, Smithery, mcp.so, Cline - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/phasespace-labs/palinode/issues/35 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 32. 安全/权限坑 · 来源证据：Interop: Palinode's KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE maps to IETF KU lifecycle - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Interop: Palinode's KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE maps to IETF KU lifecycle - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/phasespace-labs/palinode/issues/17 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 33. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/phasespace-labs/palinode | issue_or_pr_quality=unknown ## 34. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/phasespace-labs/palinode | release_recency=unknown