1. 项目定位与核心理念

Palinode 是一个本地优先（local-first）的智能体记忆层（agent memory layer），其设计目标是为 AI 编程助手提供跨 IDE、跨会话的持久化记忆能力。根据 README.md 的描述，Palinode 的核心理念可概括为四点：

这种"git 作为真相之源"的范式使得每一次记忆压缩都可追溯，避免了 LLM 在 wiki 场景下"无引用综合、脱离源头仍不自知、呈现虚假确定性"的问题（参见 issue #65）。

2. 系统组件与分层架构

Palinode 在运行时由四个相互协作的进程/包组成：

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 指出 palinode-mcp（stdio）与 palinode-api（本地 HTTP，端口 6340）协同工作；客户端通过 curl http://localhost:6340/status 验证 ollama_reachable 状态。
• 路由与写入路径：palinode/api/memory_write.py 负责保存前的归一化：实体引用补全 category/ 前缀、生成 ## See also 自动页脚（带 <!-- palinode-auto-footer --> 标记）、解析 source 归属。
• LLM 富化层：palinode/api/enrichment.py 通过集中式 CHAT 客户端调用 Ollama，生成单句描述；失败时回退到首行抽取。
• 渲染与 UI：palinode/api/ui/render.py 采用 markdown-it-py（禁用 HTML）+ nh3 双重消毒，专门防御来自智能体生成内容的 XSS 攻击。
• CLI 工具集：palinode init（palinode/cli/init.py）搭建 people/、projects/、decisions/、insights/、research/ 等目录；palinode obsidian-sync（palinode/cli/obsidian_sync.py）为存量文件回填 wiki 页脚；palinode orphan-repair（palinode/cli/embedding_tools.py）通过语义相似度修复破损 [[wikilink]]。

3. 记忆生命周期关键路径

Palinode 的记忆生命周期可拆解为四个核心动作：

1. 写入（Save）：智能体调用 /save 端点，palinode/api/memory_write.py 中的 _apply_wiki_footer 与 _normalize_entities 在落盘前补全 wikilink 页脚与实体前缀。同一函数保证幂等性：再次保存时已存在的页脚被原地替换。
2. 索引（Watch & Embed）：文件系统变更触发 watcher，palinode/api/routers/memory.py 中 _generate_description 仅对位于 _MEMORY_CATEGORY_DIRS 下的文件触发 LLM 调用；daily/、archive/、specs/ 等结构文件被明确排除，避免无谓推理。
3. 检索（4-Phase Injection）：根据 README.md 的描述，注入分为 Core（始终注入）+ Topic（按回合检索）+ Associative（实体图谱）+ Triggered（前瞻式回忆）。
4. 压缩（Compaction）：LLM 提议 KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE 操作，由确定性执行器落地为 git 提交；每次提交保留 <!-- fact:slug --> 内联 ID 以便按事实寻址。

4. 部署形态与社区关注点

当前 Palinode 主推本地部署：stdio 传输给本地 IDE、HTTP 暴露给同局域网的其他客户端。该形态直接导致了两个尚未完成的社区议题——

• Anthropic Connectors Directory 提交（issue #62）被推迟，因为官方市场要求 MCPB 桌面扩展或远程 MCP，而 Palinode 的"本地优先"定位暂时无法满足；
• 多平台安装文档（issue #24）要求补全 Claude Code、Cursor、Zed、VS Code 的差异化配置。

相反，已落地的扩展点包括 Nix flake + systemd 服务模块（issue #7）与即将到来的 llms-install.md（issue #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）

总体架构

记忆引擎可分为四层：存储层（markdown + git）、索引层（SQLite-vec + FTS5 + 实体图）、检索层（MCP 工具集 + 4 阶段注入）与整合层（KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE 操作 + 自动描述/摘要）。四层之间通过 palinode/api/routers/memory.py 中描述的写入/回填流水线衔接：保存一条记忆 → 自动追加 ## See also 页脚 → 异步生成 description / summary → 重建向量。

flowchart LR
    A[Markdown<br/>+ Frontmatter] -->|git write| B[存储层]
    B -->|watcher| C[索引层<br/>SQLite-vec + FTS5]
    C -->|hybrid search| D[检索层<br/>4-phase injection]
    D -->|MCP tool| E[Agent / IDE]
    E -->|KEEP/UPDATE/<br/>MERGE/SUPERSEDE/<br/>ARCHIVE| F[整合层]
    F -->|deterministic<br/>executor| B
    F -->|LLM one-liner| G[description<br/>+ summary]
    G -->|write-back| B

存储层：Markdown 即真相之源

存储层把记忆直接落到磁盘上的 markdown 文件，并在 YAML frontmatter 中携带元数据。元数据类别决定了文件归属哪一类实体前缀（用于 wikilink 解析）：

类别映射和实体归一化逻辑集中在 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 注释块 <!-- palinode-auto-footer -->，以便 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_<name>，也可通过 CLI 调用 palinode <name>，还可通过 REST API 调用 POST/GET /<name>。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' 开头"，并把正文包在 <user_content> 标签里以隔离提示注入。当 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/<category>/<slug>.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）

概述

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

flowchart LR
    subgraph IDE["IDE / Agent (Claude Code · Cursor · Zed · Cline)"]
        MCPClient["MCP stdio 客户端<br/>palinode-mcp"]
    end
    subgraph Backend["本地后端进程"]
        API["palinode-api<br/>HTTP :6340"]
        Router["routers/memory.py<br/>+ search / consolidation"]
        Store[("Markdown 文件<br/>+ 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 <vault-path> 模式，可向既有 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

常见失败模式与扩展路径

社区中仍在追踪的扩展路径包括：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
• 后端 HTTP 路由：palinode/api/routers/memory.py
• 富集与回退链：palinode/api/enrichment.py
• 渲染与清洗：palinode/api/ui/render.py
• CLI 初始化与同步：palinode/cli/init.py、palinode/cli/obsidian_sync.py
• Claude Code 插件接入：claude-plugin/README.md
• 相关社区议题：#24（多平台 MCP 文档）、#32（CLAUDE.md 零摩擦）、#60（OpenClaw / Hermes-agent 集成）、#61（llms-install.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

--obsidian <vault-path> 标志会同时让脚手架在指定 vault 下重建（用户已编辑文件保持原样），便于把已有 Obsidian 知识库并入 Palinode 仓库。资料来源：palinode/cli/init.py:42-50

2. 持续运维：Wiki 合约、孤儿链接与 vault 导入

2.1 Wiki 合约回填

所有 palinode_save 写出的新文件会自动追加 <!-- palinode-auto-footer --> 标记的 ## 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 <source-vault> [--into <category>] [--apply] 把外部 markdown 库映射到 memory_dir/<category>/<slug>.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/<file_path> 渲染单条 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

部署流程示意

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 — 项目总览与设计哲学
• palinode/api/memory_write.py — 写入路径归一化与脚注合并
• palinode/api/enrichment.py — LLM 摘要/描述生成的退避策略
• Issue #61 — 关于 llms-install.md（Ollama 检测与 venv 路径规范）的运维摩擦点
• Issue #8 — brew install palinode 计划，将封装上述 CLI 入口为 Homebrew formula

Pitfall Log / 踩坑日志

项目：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