项目概述与目标

second-brain-joplin 是一个 MCP（Model Context Protocol）服务器，其核心目标是将本地 Joplin 知识库转换为任何支持 MCP 协议的 AI 客户端可调用的"可搜索记忆"。它是 second-brain-mcp（针对 Obsidian 实现）的 Joplin 版本，提供完全等价的工作流但适配 Joplin 的 REST API 接口 资料来源：README.md:1-15。

当前发布版本为 v0.1.0 引导版本（Bootstrap）——MCP 服务器能够启动，所有工具均已注册但仍处于桩（stub）状态 资料来源：CHANGELOG.md:33-56。真正的读工具实现计划在 v0.2 里程碑 完成（社区议题 #5–#8），语义搜索将在 v0.3 完成（议题 #9），人工把关的写入能力将在 v0.4 完成（议题 #10），正式发布则安排在 v1.0 资料来源：README.md:58-66。

系统架构

整体系统由三大部分构成：MCP 客户端（如 Claude Code / Cursor）、second-brain-joplin 服务器进程、以及本地运行的 Joplin Desktop 应用程序及其暴露的 Web Clipper REST API（默认监听 localhost:41184）。

flowchart LR
    A[Claude Code / Cursor<br/>MCP Client] -->|MCP / stdio| B[second-brain-joplin<br/>FastMCP Server]
    B -->|HTTP + token<br/>via httpx| C[Joplin Desktop<br/>Web Clipper :41184]
    C --> D[(本地 Joplin Notes<br/>& Notebooks)]
    B -.读取环境变量.-> E[JOPLIN_API_TOKEN<br/>JOPLIN_BASE_URL]

src/second_brain_joplin/__init__.py 仅声明包元数据与版本号 __version__ = "0.1.0" 资料来源：src/second_brain_joplin/__init__.py:1-4。运行时入口则由 src/second_brain_joplin/server.py 提供：CLI 通过 argparse 注册 serve 子命令，启动时调用 load_dotenv() 加载环境配置，再创建全局 JoplinClient 实例 资料来源：src/second_brain_joplin/server.py:17-33。

核心组件

JoplinClient（Joplin REST API 适配层）

JoplinClient 是对 Joplin Web Clipper API 的轻量封装。构造函数接收 base_url（去除尾部斜杠）与 token（作为 ?token= 查询参数附加），目前仅 ping() 方法可用——通过 httpx.AsyncClient 访问 /ping 端点，比对返回文本是否为 JoplinClipperServer 来确认连通性，并在 httpx.ConnectError 时返回 False 资料来源：src/second_brain_joplin/joplin_client.py:1-21。

get_notebooks、get_note、search、get_recent、create_note 五个方法在 v0.1 中显式抛出 NotImplementedError，对应的实现见社区议题 #4–#8 与 #10 资料来源：src/second_brain_joplin/joplin_client.py:23-39。这种"先定义接口占位、实现随版本推进"的设计有助于保持 CI 与 90% 覆盖率门槛始终通过 资料来源：CHANGELOG.md:44-56。

FastMCP Server 与桩工具

server.py 以 FastMCP("second-brain-joplin") 实例化服务器，并使用 @mcp.tool() 装饰器注册五个工具：joplin_overview、joplin_search、joplin_read、joplin_recent 与 joplin_create。在 v0.1 中，每个工具都返回 {"status": "not implemented", "tool": <name>, "issue": <num>}，使请求不会真正下到 JoplinClient 资料来源：src/second_brain_joplin/server.py:35-55。

_get_client() 借助模块级全局变量实现惰性单例，从环境变量读取 JOPLIN_API_TOKEN 与 JOPLIN_BASE_URL（后者默认 http://localhost:41184）资料来源：src/second_brain_joplin/server.py:17-33。这与 .env 经由 python-dotenv 自动加载的机制相配合，简化本地开发体验 资料来源：CONTRIBUTING.md:43-50。

数据流与请求生命周期

一次典型调用遵循以下路径：

1. MCP 客户端通过 stdio 发送 tools/call 请求（例如调用 joplin_search）。
2. FastMCP 调度至对应装饰器函数；v0.1 立即返回带 status: "not implemented" 的字典。
3. 待 v0.2 实现完成后，函数将调用 _get_client() 获取 JoplinClient，再通过 httpx.AsyncClient 发起 HTTP 请求，附 ?token=<JOPLIN_API_TOKEN> 鉴权 资料来源：src/second_brain_joplin/joplin_client.py:9-14。
4. 服务器通过 stdio 通道将 JSON-RPC 响应回传给客户端。

设计上的一个关键原则是：v0.1 不做任何静默写入——只有读取型的桩工具以及一个计划中需要人工把关的 joplin_create 工具被注册 资料来源：SECURITY.md:18-23。

与同类项目的对比

资料来源：README.md:48-57。

安全与隐私模型

整套设计坚持"本地优先"原则：服务器仅与 localhost 上的 Joplin API 通信，不会把笔记外发至第三方服务；API 令牌通过环境变量传入而非提交至版本控制；采用最低权限原则——任何 MCP 客户端可读取的内容，连接的 AI 同样可读取，因此应避免暴露含凭证的笔记本 资料来源：SECURITY.md:9-23。v0.1 不写入任何数据，v0.4 计划引入的人工把关机制将进一步保障写入安全 资料来源：README.md:73-79。

See Also

• CHANGELOG.md — 版本演进与 CI/CD 重构记录
• CONTRIBUTING.md — 开发环境、CI 工作原理、标签约定
• SECURITY.md — 漏洞上报与数据处理策略
• README.md — 快速安装、客户端配置与里程碑总览
• 社区议题：#3（包骨架）、#5 (joplin_overview)、#6 (joplin_search)、#7 (joplin_read)、#8 (joplin_recent)、#9（语义搜索）、#10（人工把关写入）、#11（v1.0 发布）、#12（PyPI trusted publisher）

MCP 工具与 JoplinClient 实现

概述与范围

second-brain-joplin 是 v0.1.0 阶段的 MCP 服务器骨架，其核心目标是把 Joplin Desktop 的 Web Clipper 本地 REST API（默认 http://localhost:41184）封装为 MCP 工具，供 Claude Code、Cursor 等 MCP 客户端调用，从而让 AI 直接读取与查询本地 Joplin 笔记库。

资料来源：src/second_brain_joplin/__init__.py:1-3、CHANGELOG.md:1-12

在当前 v0.1.0（Bootstrap 版本）中：

• 服务器可以正常启动并通过 serve 子命令暴露 stdio 传输。
• 全部 5 个 MCP 工具已注册到 FastMCP，但均返回 {"status": "not implemented"} 占位响应，未真正调用后端。
• JoplinClient 中只有 ping() 是可用实现，其余方法（get_notebooks、get_note、search、get_recent、create_note）显式抛出 NotImplementedError，等待 v0.2 里程碑落地。

资料来源：CHANGELOG.md:24-37、src/second_brain_joplin/server.py:20-49、src/second_brain_joplin/joplin_client.py:18-39

架构与数据流

整个调用链路为「MCP 客户端 → FastMCP 服务器 → JoplinClient → Joplin REST API → 本地笔记」。服务器进程在 main() 中调用 load_dotenv() 加载 .env，然后通过 argparse 解析 serve 子命令并执行 mcp.run()。_get_client() 是一个惰性单例工厂：首次调用时读取 JOPLIN_API_TOKEN 与 JOPLIN_BASE_URL 环境变量（后者默认 http://localhost:41184），并构造 JoplinClient。

资料来源：src/second_brain_joplin/server.py:1-20、src/second_brain_joplin/server.py:54-78、README.md:1-30

flowchart LR
    A[MCP 客户端<br/>Claude Code / Cursor] -- stdio / MCP --> B[FastMCP 服务器<br/>second-brain-joplin serve]
    B -- JoplinClient 单例 --> C[JoplinClient<br/>base_url + token]
    C -- HTTP + token 查询参数 --> D[Joplin Web Clipper<br/>localhost:41184]
    D --> E[(本地 Joplin 笔记)]

MCP 工具一览

下表汇总了 v0.1 中已经通过 @mcp.tool() 注册的 5 个工具。所有工具都是存根，直接返回带 issue 编号的占位字典，不会触达 JoplinClient：

资料来源：src/second_brain_joplin/server.py:25-49、README.md:51-58、CHANGELOG.md:30-37

每个工具的实现极其简短，例如：

@mcp.tool()
async def joplin_search(query: str) -> dict:
    """Search notes by keyword across all notebooks."""
    return {"status": "not implemented", "tool": "joplin_search", "issue": 6}

工具签名（包括 docstring）将在 v0.2 里程碑实现时直接对接 JoplinClient 的对应方法。

JoplinClient 实现现状

JoplinClient 是一个基于 httpx.AsyncClient 的轻量包装器。构造时把传入的 base_url 去掉末尾 /，并把 token 作为查询参数保存（用于 ?token=... 鉴权）。当前版本中唯一具有真实行为的接口是 ping()：

• 调用 GET {base_url}/ping，超时 3 秒；
• 当响应正文为字符串 "JoplinClipperServer" 时返回 True；
• 捕获 httpx.ConnectError 并返回 False，避免在 Joplin 未运行时抛出未处理异常。

其余 5 个方法（get_notebooks、get_note、search、get_recent、create_note）目前都直接 raise NotImplementedError。注释明确说明：v0.1 的 MCP 工具会在到达这些方法之前短路返回占位响应，因此这些异常在实际运行中不会被触发。

资料来源：src/second_brain_joplin/joplin_client.py:1-39、CHANGELOG.md:30-37

配置、错误处理与后续里程碑

环境变量与 `.env`

服务器通过 python-dotenv 加载 .env。必需/可选配置项如下：

资料来源：README.md:36-58、src/second_brain_joplin/server.py:12-20

CLI

build_parser() 定义 second-brain-joplin 程序名，并提供：

• --version：打印 __version__（当前 0.1.0）；
• serve 子命令：调用 mcp.run() 启动 stdio 传输的 MCP 服务器；
• 无子命令时打印帮助。

资料来源：src/second_brain_joplin/server.py:62-78

常见失败模式

1. Joplin 未启动或 Web Clipper 未启用：ping() 会捕获 ConnectError 并返回 False；调用任何已实现工具时，连接将超时或失败。需要在 Joplin 中开启 Tools → Options → Web Clipper → Enable Web Clipper Service。
2. 令牌缺失或错误：_get_client() 会以空 token 构造客户端，请求会因为缺失 ?token= 而被 Joplin 拒绝。
3. 调用未实现的工具：在 v0.1 中这是预期行为，工具会返回 {"status": "not implemented", ...}；若绕过 MCP 工具直接调用 JoplinClient.get_note() 等，会得到 NotImplementedError。

资料来源：src/second_brain_joplin/joplin_client.py:14-25、src/second_brain_joplin/server.py:25-49、README.md:36-58

后续里程碑

根据 README 与 CHANGELOG 的路线图：

• v0.2：实现 4 个读取类工具（joplin_overview、joplin_search、joplin_read、joplin_recent）和对应 JoplinClient 方法；
• v0.3：基于 bge-m3 与向量索引（如 ChromaDB / FAISS）实现 joplin_semantic_search；
• v0.4：实现 joplin_create，并加入人工确认（human-in-the-loop）门控；
• v1.0：通过 OIDC 受信任发布把包推送至 PyPI，补全文档与 PARA 笔记模板。

资料来源：README.md:67-75、CHANGELOG.md:1-23、SECURITY.md:13-21

参见

• README — 项目整体说明与快速开始
• CHANGELOG — 版本变更与路线图
• CONTRIBUTING — 开发流程与 CI 闸门
• SECURITY — 数据本地化与最小权限原则

开发工作流、CI/CD 与发布

本页面介绍 second-brain-joplin 项目面向贡献者的本地开发工作流、CI/CD 流水线设计以及经由 PyPI 的发布链路。读者将了解从 uv 安装、pre-commit 门禁、mypy 静态检查、测试覆盖率门槛,到「可复用 checks 工作流」再到 OIDC trusted publisher 全链路的工程化策略。

本地开发工作流

工具链与依赖锁

项目以 uv 为统一工具链,通过 pyproject.toml 与 uv.lock 锁定依赖。推荐的标准克隆与同步流程如下,提交前还要安装 pre-commit 钩子,以保证本地与 CI 行为完全一致:

git clone https://github.com/jomkz/second-brain-joplin
cd second-brain-joplin
uv sync
uv run pre-commit install

在不便使用 uv 的环境,文档同时给出了 pip + venv 的回退方案(pip install -e ".[test]")。资料来源:CONTRIBUTING.md:L1-L20。

代码规范、静态检查与测试

工程上把 lint / format 的单一真实源放在 .pre-commit-config.yaml,CI 直接执行 uvx pre-commit run --all-files,从而避免「本地 ruff 版本 vs 远端 ruff 版本」的漂移。

uvx pre-commit run --all-files   # ruff lint + format
uv run mypy src                  # 静态类型检查
uv run pytest                    # 运行测试(打印覆盖率)

关键的两点约定值得注意:

1. 覆盖率门槛只在 CI 强制。 90% 的 --cov-fail-under=90 从 addopts 中移出,放进 CI 命令,这样本地跑部分测试不会因为未覆盖而误报失败。资料来源:CONTRIBUTING.md:L21-L36。
2. mypy 采用务实基线。 在 pyproject.toml 中仅启用 ignore_missing_imports = true、warn_unused_ignores、warn_redundant_casts,作用域限制在 src,这是因为 FastMCP 的 @mcp.tool() 装饰器没有类型标注,直接 strict = true 会立刻报错。社区正在推进 issue #19,计划逐步收紧并覆盖 tests/。

测试栈使用 pytest + respx(后者用来 mock httpx 异步调用,例如 JoplinClient.ping)。资料来源:src/second_brain_joplin/joplin_client.py:L11-L17。

启动本地服务

cp .env.example .env       # 编辑后填入 JOPLIN_API_TOKEN
uv run second-brain-joplin serve

CLI 通过 argparse 暴露 serve 子命令与 --version,在 main() 中先调用 load_dotenv() 再解析参数。资料来源:src/second_brain_joplin/server.py:L18-L36。

CI/CD 流水线

重构后的可复用 `checks` 工作流

CI/CD 在 v0.1.0 之后被整体重组为单一可复用工作流 .github/workflows/checks.yml,集中包含 lint、typecheck、test 矩阵(3.11 / 3.12 / 3.13)与 build(uv build + twine check + wheel smoke test)。ci.yml 在 push/PR 触发并调用它,release.yml 在打 tag 后也复用同一套流程,做到构建一次、测试一次、再发布。资料来源:CHANGELOG.md:L8-L26、CONTRIBUTING.md:L42-L52。

flowchart LR
    PUSH[push/PR 到 main]
    TAG[v*.*.* tag]
    CI[ci.yml]
    RL[release.yml]
    CHK[checks.yml<br/>可复用工作流]
    LINT[lint<br/>pre-commit]
    TC[typecheck<br/>mypy src]
    TEST[test 矩阵<br/>3.11/3.12/3.13]
    BUILD[build<br/>uv build + twine check + wheel smoke]
    PYPI[PyPI Trusted Publisher]

    PUSH --> CI --> CHK
    TAG  --> RL --> CHK
    CHK  --> LINT
    CHK  --> TC
    CHK  --> TEST
    CHK  --> BUILD
    RL   --> PYPI

安全与并发控制

CI 显式设置了最小 permissions、并使用 concurrency 取消同一分支上的旧运行;安装方式升级为 uv sync --locked,一旦 uv.lock 漂移任务立即失败,使 PR 阶段就能拦截依赖不一致问题。资料来源:CHANGELOG.md:L8-L26。

PR 标签自动化缺口

.github/labeler.yml 已经定义了 component:* 路径 globs,docs/project-management.md 与 CONTRIBUTING.md 都声明 PR 上的 component:* 标签应自动应用,但目前没有真正运行的 actions/labeler 工作流——这是社区跟踪中的 issue #18,被列入优先事项。

发布流程

版本与里程碑

包版本以 __version__ = "0.1.0" 声明在 src/second_brain_joplin/__init__.py 中,对应 README 中的 v0.1 Bootstrap 里程碑。后续目标依次为: v0.2(核心读工具,issues #5–#8)、v0.3(语义搜索,issue #9)、v0.4(人工把关写入,issue #10)、v1.0(PyPI & 完整文档,issue #11)。资料来源:src/second_brain_joplin/__init__.py:L1-L3、README.md:L38-L48。

Trusted Publisher 上 PyPI

发布走 issue #12 的方案:不再走 TestPyPI,而是通过 OIDC trusted publisher 直接发布到 PyPI。.github/workflows/release.yml 在 v*.*.* tag 触发后调用 checks.yml,待所有闸门通过后用官方 pypa/gh-action-pypi-publish 上传 同一份已校验的 artifact,并启用 skip-existing 防止重复推送。这条路径已经经过 issue #12 与 issue #2 中提到的工作完整验证。资料来源:CHANGELOG.md:L8-L26。

Changelog 规约

变更日志遵循 Keep a Changelog 与 SemVer,Unreleased 区段记录了「CI/CD 重组为可复用 checks 工作流」「静态类型检查入闸」「覆盖率门槛移出 addopts」等近期演进。资料来源:CHANGELOG.md:L1-L40。

提交、PR 与安全

• Commit 风格:简短的祈使句,可选用 git commit -s 加 DCO sign-off(暂不强制)。资料来源:CONTRIBUTING.md:L68-L88。
• PR 规约:目标分支 main,每次 PR 只做一个逻辑改动并附测试,CI 全绿方可合并。资料来源:CONTRIBUTING.md:L68-L88。
• 安全策略:可疑漏洞通过 GitHub Security Advisories 私下提交。服务器只与 localhost 的 Joplin Web Clipper 通信,从不把笔记外发;v0.1 不做任何静默写入,v0.4 计划显式人工确认后再创建笔记。资料来源:SECURITY.md:L1-L25。

See Also

• README.md — 项目总览与里程碑
• CONTRIBUTING.md — 开发与提交细节
• CHANGELOG.md — 版本变更
• SECURITY.md — 漏洞与数据处理
• 社区议题:#2 搭建 CI、#12 PyPI trusted publish、#18 PR labeler 自动化、#19 mypy 走向 strict

配置、安全、隐私与路线图

本页汇总 second-brain-joplin 项目的运行时配置、安全模型、隐私边界以及公开的版本路线图，便于使用者评估部署风险并规划集成时序。

1. 运行时配置

服务器在 main() 中调用 load_dotenv() 自动加载 .env 文件，再通过惰性初始化的 _get_client() 从环境变量读取运行时参数并构造单例 JoplinClient 资料来源：src/second_brain_joplin/server.py:30-37。两个核心环境变量为：JOPLIN_API_TOKEN（必填，Joplin Web Clipper 鉴权令牌）与 JOPLIN_BASE_URL（默认 http://localhost:41184，Web Clipper REST API 本地地址）资料来源：src/second_brain_joplin/server.py:24-28。

命令行入口 second-brain-joplin 由 build_parser() 定义，暴露 serve 子命令与 --version 标志；版本字符串 0.1.0 由 __version__ 常量提供 资料来源：src/second_brain_joplin/__init__.py:3-4 资料来源：src/second_brain_joplin/server.py:55-65。Claude Code 注册示例：

claude mcp add -s user second-brain-joplin \
  -e JOPLIN_API_TOKEN=your-token-here \
  -- uvx second-brain-joplin serve

本地开发可通过 cp .env.example .env 复制模板后填入真实令牌，再运行 uv run second-brain-joplin serve 资料来源：CONTRIBUTING.md:36-44。

2. 安全与隐私

服务器遵循"本地优先、最小特权、显式写入"四项原则 资料来源：SECURITY.md:11-29：

• 本地 API：仅与 localhost 上的 Joplin Web Clipper REST API 通信，笔记不会外发到任何第三方服务。
• 本地运行：MCP 服务器由客户端在本机启动；Joplin 令牌仅从环境变量读取，严禁提交到版本控制。
• 最小特权：MCP 客户端可读即 AI 可读——应避免在笔记中保存凭证、受监管数据或他人隐私，并按需划分笔记本。
• 无静默写入：v0.1 全部工具均为只读桩；v0.4 的笔记创建将被设计为显式人工门控（human-gated）流程，AI 不会在无确认情况下写入。

漏洞披露请通过 GitHub Security Advisories 私下提交，而非公开 issue 资料来源：SECURITY.md:5-7。

3. 路线图与版本

公开里程碑涵盖从骨架到 v1.0 发布的完整路径 资料来源：README.md:78-87：

v0.1 已交付的核心改动包括 CLI 入口、五大 stub 工具（joplin_overview、joplin_search、joplin_read、joplin_recent、joplin_create）、JoplinClient.ping()、.env 支持、pytest + respx 测试套件以及 90% 覆盖率门控 资料来源：CHANGELOG.md:37-51。Unreleased 段进一步将 lint/typecheck/测试矩阵/打包构建收敛到可复用的 .github/workflows/checks.yml，并新增 mypy 静态类型检查门控 资料来源：CHANGELOG.md:5-19。

4. 部署注意事项

• 令牌管理：.env 必须加入 .gitignore；CI 与 PyPI 发布均经 OIDC trusted publisher 完成，流程中不接触用户令牌 资料来源：README.md:64-67。
• 依赖 Joplin 运行：与 Obsidian 版（second-brain-mcp）不同，本服务依赖 Joplin Desktop 与 Web Clipper 服务持续在线 资料来源：README.md:70-77。
• 健康探测：JoplinClient.ping() 命中 /ping，返回 JoplinClipperServer 即视为可用；若 httpx.ConnectError 触发则返回 False 资料来源：src/second_brain_joplin/joplin_client.py:14-22。

See Also / 参见

• README.md — 项目总览与快速开始
• docs/install.md — 各 MCP 客户端安装指南
• docs/project-management.md — 里程碑与标签体系
• docs/notebook-structure.md — PARA 笔记本推荐结构
• 相关 GitHub issue：#5 joplin_overview、#10 Human-gated note creation、#11 PyPI publish、#12 Trusted publisher

Pitfall Log / 踩坑日志

项目：jomkz/second-brain-joplin

摘要：发现 32 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: Add PR labeler workflow (actions/labeler)。

1. 安全/权限坑 · 失败模式：security_permissions: Add PR labeler workflow (actions/labeler)

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Add PR labeler workflow (actions/labeler)
• 对用户的影响：Developers may expose sensitive permissions or credentials: Add PR labeler workflow (actions/labeler)
• 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/18 | Add PR labeler workflow (actions/labeler)

2. 安全/权限坑 · 失败模式：security_permissions: Set up CI pipeline (lint + test matrix)

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Set up CI pipeline (lint + test matrix)
• 对用户的影响：Developers may expose sensitive permissions or credentials: Set up CI pipeline (lint + test matrix)
• 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/2 | Set up CI pipeline (lint + test matrix)

3. 安装坑 · 失败模式：installation: Bootstrap second-brain-joplin (v0.1)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Bootstrap second-brain-joplin (v0.1)
• 对用户的影响：Developers may fail before the first successful local run: Bootstrap second-brain-joplin (v0.1)
• 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/1 | Bootstrap second-brain-joplin (v0.1)

4. 安装坑 · 来源证据：Bootstrap second-brain-joplin (v0.1)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bootstrap second-brain-joplin (v0.1)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：Semantic search via embedding index (v0.3)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Semantic search via embedding index (v0.3)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/9 | 来源类型 github_issue 暴露的待验证使用条件。

6. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/jomkz/second-brain-joplin | host_targets=mcp_host, claude_code, claude, cursor

7. 配置坑 · 失败模式：configuration: Implement core read MCP tools (v0.2)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Implement core read MCP tools (v0.2)
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Implement core read MCP tools (v0.2)
• 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/4 | Implement core read MCP tools (v0.2)

8. 配置坑 · 失败模式：configuration: Implement package skeleton and stubbed MCP server

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Implement package skeleton and stubbed MCP server
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Implement package skeleton and stubbed MCP server
• 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/3 | Implement package skeleton and stubbed MCP server

9. 配置坑 · 失败模式：configuration: PyPI publish, full docs, and Joplin templates (v1.0)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: PyPI publish, full docs, and Joplin templates (v1.0)
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: PyPI publish, full docs, and Joplin templates (v1.0)
• 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/11 | PyPI publish, full docs, and Joplin templates (v1.0)

10. 配置坑 · 来源证据：Tighten mypy toward strict and cover tests/

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Tighten mypy toward strict and cover tests/
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/19 | 来源类型 github_issue 暴露的待验证使用条件。

11. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/jomkz/second-brain-joplin | README/documentation is current enough for a first validation pass.

12. 运行坑 · 来源证据：Implement joplin_read tool

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Implement joplin_read tool
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/7 | 来源类型 github_issue 暴露的待验证使用条件。

13. 运行坑 · 来源证据：Implement joplin_search tool

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Implement joplin_search tool
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/6 | 来源类型 github_issue 暴露的待验证使用条件。

14. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/jomkz/second-brain-joplin | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/jomkz/second-brain-joplin | no_demo; severity=medium

16. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/jomkz/second-brain-joplin | no_demo; severity=medium

17. 安全/权限坑 · 来源证据：Add PR labeler workflow (actions/labeler)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add PR labeler workflow (actions/labeler)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/18 | 来源类型 github_issue 暴露的待验证使用条件。

18. 安全/权限坑 · 来源证据：Implement core read MCP tools (v0.2)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Implement core read MCP tools (v0.2)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/4 | 来源类型 github_issue 暴露的待验证使用条件。

19. 安全/权限坑 · 来源证据：Implement joplin_overview tool

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Implement joplin_overview tool
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/5 | 来源类型 github_issue 暴露的待验证使用条件。

20. 安全/权限坑 · 来源证据：Implement package skeleton and stubbed MCP server

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Implement package skeleton and stubbed MCP server
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

21. 安全/权限坑 · 来源证据：Publish package to PyPI (trusted publisher)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Publish package to PyPI (trusted publisher)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/12 | 来源类型 github_issue 暴露的待验证使用条件。

22. 安全/权限坑 · 来源证据：Set up CI pipeline (lint + test matrix)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Set up CI pipeline (lint + test matrix)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/jomkz/second-brain-joplin/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

23. 能力坑 · 失败模式：capability: Human-gated note creation (v0.4)

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Human-gated note creation (v0.4)
• 对用户的影响：Developers may hit a documented source-backed failure mode: Human-gated note creation (v0.4)
• 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/10 | Human-gated note creation (v0.4)

24. 能力坑 · 失败模式：capability: Implement joplin_overview tool

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Implement joplin_overview tool
• 对用户的影响：Developers may hit a documented source-backed failure mode: Implement joplin_overview tool
• 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/5 | Implement joplin_overview tool

25. 能力坑 · 失败模式：capability: Implement joplin_read tool

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Implement joplin_read tool
• 对用户的影响：Developers may hit a documented source-backed failure mode: Implement joplin_read tool
• 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/7 | Implement joplin_read tool

26. 能力坑 · 失败模式：capability: Implement joplin_recent tool

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Implement joplin_recent tool
• 对用户的影响：Developers may hit a documented source-backed failure mode: Implement joplin_recent tool
• 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/8 | Implement joplin_recent tool

27. 能力坑 · 失败模式：capability: Implement joplin_search tool

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Implement joplin_search tool
• 对用户的影响：Developers may hit a documented source-backed failure mode: Implement joplin_search tool
• 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/6 | Implement joplin_search tool

28. 能力坑 · 失败模式：capability: Semantic search via embedding index (v0.3)

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Semantic search via embedding index (v0.3)
• 对用户的影响：Developers may hit a documented source-backed failure mode: Semantic search via embedding index (v0.3)
• 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/9 | Semantic search via embedding index (v0.3)

29. 能力坑 · 失败模式：capability: Tighten mypy toward strict and cover tests/

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Tighten mypy toward strict and cover tests/
• 对用户的影响：Developers may hit a documented source-backed failure mode: Tighten mypy toward strict and cover tests/
• 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/19 | Tighten mypy toward strict and cover tests/

30. 能力坑 · 失败模式：conceptual: Publish package to PyPI (trusted publisher)

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: Publish package to PyPI (trusted publisher)
• 对用户的影响：Developers may hit a documented source-backed failure mode: Publish package to PyPI (trusted publisher)
• 证据：failure_mode_cluster:github_issue | https://github.com/jomkz/second-brain-joplin/issues/12 | Publish package to PyPI (trusted publisher)

31. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/jomkz/second-brain-joplin | issue_or_pr_quality=unknown

32. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/jomkz/second-brain-joplin | release_recency=unknown