bookmark-research 0.5.0-beta.9 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/.agents/plugins/marketplace.json +1 -1
  2. package/.codex-plugin/plugin.json +6 -1
  3. package/README.md +78 -56
  4. package/README.zh.md +74 -52
  5. package/bin/bookmark-research.js +9 -1
  6. package/config/providers.json +41 -0
  7. package/config/settings.example.json +36 -0
  8. package/docs/bookmark-research-architecture.md +8 -119
  9. package/docs/canvas-tree-reading-acceptance.md +98 -0
  10. package/docs/configuration.en.md +70 -0
  11. package/docs/configuration.md +70 -0
  12. package/docs/details.en.md +35 -32
  13. package/docs/details.md +12 -13
  14. package/docs/distribution.md +4 -7
  15. package/docs/harness-compatibility.md +10 -299
  16. package/docs/installation.en.md +21 -47
  17. package/docs/installation.md +24 -56
  18. package/docs/instructions.en.md +3 -3
  19. package/docs/instructions.md +3 -3
  20. package/docs/prompt-reference.en.md +3 -3
  21. package/docs/prompt-reference.md +3 -3
  22. package/docs/user-guide.en.md +5 -4
  23. package/docs/user-guide.md +7 -6
  24. package/hosts/claude/commands/research.md +7 -0
  25. package/hosts/codex/delegate.md +3 -1
  26. package/hosts/dsh/plugin.js +5 -0
  27. package/hosts/dsh/workflow-call.py +8 -4
  28. package/hosts/shared/research-call.py +15 -3
  29. package/hosts/shared/research-flow.js +3 -1
  30. package/install.sh +8 -8
  31. package/package.json +3 -8
  32. package/scripts/bench_preflight.py +189 -0
  33. package/scripts/bench_sync.py +191 -0
  34. package/scripts/bench_tools_list.py +129 -0
  35. package/scripts/build_zip.py +1 -10
  36. package/scripts/evaluate_ladder.py +149 -0
  37. package/scripts/export_bundle.py +6 -68
  38. package/scripts/host_assets.py +31 -31
  39. package/scripts/host_clients.py +32 -61
  40. package/scripts/host_install.py +24 -12
  41. package/scripts/install.py +233 -77
  42. package/scripts/launcher.py +28 -5
  43. package/scripts/npm_source.py +41 -0
  44. package/scripts/verify_fixture.py +1 -1
  45. package/scripts/verify_live.py +2 -2
  46. package/scripts/verify_wiki_retrieval.py +158 -0
  47. package/skills/bookmark-research/SKILL.md +31 -31
  48. package/skills/bookmark-research/references/cli.md +20 -8
  49. package/skills/bookmark-research/references/deep-research.md +12 -4
  50. package/skills/bookmark-research/references/host-workflows.md +4 -23
  51. package/skills/bookmark-research/references/package-semantics.md +67 -10
  52. package/skills/bookmark-research/references/research-methods.md +1 -1
  53. package/skills/bookmark-research/references/research-services.md +25 -47
  54. package/skills/bookmark-research/references/research-workflow.md +8 -4
  55. package/skills/bookmark-research/references/settings-and-archive.md +29 -11
  56. package/skills/bookmark-research/references/wiki.md +92 -0
  57. package/skills/bookmark-research/references/zh/cli.md +20 -8
  58. package/skills/bookmark-research/references/zh/deep-research.md +12 -4
  59. package/skills/bookmark-research/references/zh/host-workflows.md +4 -23
  60. package/skills/bookmark-research/references/zh/package-semantics.md +67 -10
  61. package/skills/bookmark-research/references/zh/research-methods.md +1 -1
  62. package/skills/bookmark-research/references/zh/research-services.md +27 -47
  63. package/skills/bookmark-research/references/zh/research-workflow.md +8 -4
  64. package/skills/bookmark-research/references/zh/settings-and-archive.md +28 -10
  65. package/skills/bookmark-research/references/zh/skill-guide.md +26 -33
  66. package/skills/bookmark-research/references/zh/wiki.md +94 -0
  67. package/src/archive.py +560 -25
  68. package/src/bookmark_dependencies.py +56 -0
  69. package/src/bookmark_index.py +1237 -58
  70. package/src/browser_client.py +342 -0
  71. package/src/cli.py +399 -33
  72. package/src/context_output.py +53 -0
  73. package/src/credentials.py +2 -1
  74. package/src/deepseek.py +137 -0
  75. package/src/discovery.py +118 -0
  76. package/src/dsh_client.py +206 -0
  77. package/src/fetch_cache.py +60 -0
  78. package/src/grok_search.py +272 -0
  79. package/src/jina.py +1 -1
  80. package/src/jobs.py +349 -0
  81. package/src/junk.py +33 -0
  82. package/src/locate.py +862 -0
  83. package/src/mcp_dispatch.py +99 -0
  84. package/src/mcp_server.py +899 -93
  85. package/src/netscape.py +124 -0
  86. package/src/onboarding.py +339 -114
  87. package/src/package_paths.py +137 -0
  88. package/src/perplexity.py +78 -0
  89. package/src/raw_library.py +255 -48
  90. package/src/readiness.py +43 -9
  91. package/src/ref_codec.py +70 -0
  92. package/src/release.py +1 -1
  93. package/src/research.py +449 -41
  94. package/src/research_plan.py +171 -0
  95. package/src/research_services.py +48 -21
  96. package/src/routing.py +50 -16
  97. package/src/search_results.py +84 -3
  98. package/src/settings.py +135 -18
  99. package/src/source_inputs.py +156 -23
  100. package/src/source_manager.py +79 -15
  101. package/src/source_versions.py +115 -0
  102. package/src/source_watcher.py +4 -2
  103. package/src/storage.py +60 -0
  104. package/src/tui.py +5 -2
  105. package/src/url_classify.py +45 -0
  106. package/src/web_search.py +662 -70
  107. package/src/wiki.py +788 -47
  108. package/src/wiki_search.py +251 -0
  109. package/src/wiki_work.py +229 -0
  110. package/docs/cli-launcher-plan.md +0 -58
  111. package/docs/diff-review-2026-10-09.md +0 -36
  112. package/docs/harness-sources.json +0 -342
  113. package/docs/host-validation.json +0 -340
  114. package/docs/install-design-0.2.0.md +0 -57
  115. package/docs/knowledge-storage-plan.md +0 -43
  116. package/docs/mcp-aggregation-0.2.0.md +0 -92
  117. package/docs/multi-host-installation-plan.md +0 -163
  118. package/docs/provider-smoke-0.2.0.json +0 -235
  119. package/docs/release-notes-0.5.0-beta.1.md +0 -33
  120. package/docs/release-notes-0.5.0-beta.2.md +0 -23
  121. package/docs/release-notes-0.5.0-beta.3.md +0 -28
  122. package/docs/release-notes-0.5.0-beta.4.md +0 -39
  123. package/docs/release-notes-0.5.0-beta.5.md +0 -31
  124. package/docs/release-notes-0.5.0-beta.6.md +0 -30
  125. package/docs/release-notes-0.5.0-beta.7.md +0 -57
  126. package/docs/release-notes-0.5.0-beta.8.md +0 -34
  127. package/docs/release-notes-0.5.0-beta.9.md +0 -35
  128. package/docs/research-0.2.0.md +0 -140
  129. package/docs/research-sources-0.2.0.json +0 -9360
  130. package/docs/validation-0.2.0.md +0 -126
  131. package/docs/validation-0.4.0.md +0 -154
  132. package/docs/wiki-quality.md +0 -107
  133. package/docs/wiki-quality.zh.md +0 -107
  134. package/hosts/pi/register-workflow.py +0 -72
  135. package/hosts/pi/runtime.js +0 -18
  136. package/scripts/verify_quality.py +0 -87
  137. package/skills/bookmark-research/references/wiki-and-evaluation.md +0 -69
  138. package/skills/bookmark-research/references/zh/wiki-and-evaluation.md +0 -69
  139. package/src/evaluation.py +0 -337
package/docs/details.md CHANGED
@@ -21,21 +21,21 @@
21
21
 
22
22
  不需要固定提示词。完整数据包研究保留所有原始 URL 和重复书签语境;只有明确限定卡片、分组或专题时才缩小范围。搜索摘要、搜索结果的第一页和外部报告都不能代替原始网页审阅。
23
23
 
24
- 一个插件保留一个 MCP 聚合入口和一个执行 Skill;后端服务数量与入口数量无关。MCP 内置 Exa、Parallel、Tavily 搜索/读取适配器、Jina HTTP 接口和 OpenAI/Parallel 研究 API 客户端。Skill 负责根据任务选择并执行三种流程:
24
+ 一个插件保留一个 MCP 聚合入口和一个执行 Skill;后端服务数量与入口数量无关。MCP 内置 Exa、Parallel、Tavily 搜索/读取适配器、Jina HTTP 接口、可选的 DeepSeek Search/Fetch 与 Perplexity Search 接口、Grok 和自定义 OpenAI 兼容 Agentic 搜索通道,以及 OpenAI/Parallel 研究 API 客户端。普通 URL 来源由 `search_web` 聚合;模型回答和引用单独返回,不参加 URL 排名。自定义模型是否联网由上游能力决定,工具会标明引用未经独立核验。Skill 负责根据任务选择并执行三种流程:
25
25
 
26
26
  | 场景 | 基础流程 | 检索与委派支持 |
27
27
  | --- | --- | --- |
28
28
  | URL 直读 | 当前模型读取已知页面并回答 | Exa 未读到的 URL 交给 Parallel + Jina Reader 并发读取;可配置 Tavily 提取。 |
29
- | Agentic Web Search | 当前宿主模型先规划 → 搜索/读文 → 判断证据 → 针对缺口补查 | Exa + Parallel 提供搜索结果;无有效网址的查询再交给 Tavily + 有 key 的 Jina。普通问题无需完整研究会话。 |
30
- | Deep Research | 在宿主研究循环上增加持续调查、按需协作、独立核验、覆盖检查与报告 | 优先利用宿主现有子代理/工作流;外部 Research MCP/API 可承担宿主判断后的子问题或用户明确指定的任务。 |
29
+ | Agentic Web Search | 当前宿主模型先规划 → 搜索/读文 → 判断证据 → 针对缺口补查 | 优先使用当前宿主实际暴露的搜索工具;`search_web` 聚合已配置服务(Exa + Parallel 默认并发对冲,Perplexity 可选;未解析查询交给 Tavily + Jina)。需要 Grok/X 或已配置的自定义模型通道时按需调用 `agentic_search`,由宿主评估独立回答和未经核验的引用。普通问题无需完整研究会话。 |
30
+ | Deep Research | 直接向研究 API 提交完整问题,观察进度并审阅报告 | 可选 OpenAI/Parallel API;宿主已有研究能力亦可使用。完整清单与覆盖审计按需启用。 |
31
31
 
32
- 四个基座共用这套方法:Codex 原生子代理、Claude 普通子代理或已启用团队、Pi 扩展、已配置的 DSH 子代理/工作流;具体差异与官方依据见 [宿主兼容说明](harness-compatibility.md)。整包脚本用于分组研究。保存的 API 偏好只排列外部服务,显式 provider 才直接指定服务;明确路线失败可继续换路,运行中、结果未知或已取消任务不自动重建。
32
+ 三个基座共用这套方法:Codex 原生子代理、Claude 普通子代理或已启用团队、已配置的 DSH 子代理/工作流;具体差异与官方依据见 [宿主兼容说明](harness-compatibility.md)。整包脚本用于分组研究。API 可独立调用,无需先运行宿主调查或创建本地研究会话。运行中和结果未知的任务先观察,保留 operation ID,避免重复创建。
33
33
 
34
34
  “备用”表示已加入回退列表;“需要配置”表示条件未满足时跳过;“仅调研”表示没有接入,失败也不会自动安装。OpenAI/Parallel 研究 API 默认关闭,需启用并提供凭据。宿主已加载的 Exa `agent_run`、完整 Parallel Task MCP 会被路由识别,实际认证仍以调用结果为准。Scrapling、Firecrawl、MarkItDown 等调研项目没有集成成自动后端。
35
35
 
36
36
  ## 数据包与保存位置
37
37
 
38
- JSON/`.canvas` 是源数据,SQLite 是可重建的本地查询索引,无需单独数据库服务器。插件不会回写原始画布包。
38
+ JSON/`.canvas` 是源数据,SQLite 是可重建的本地查询索引,无需单独数据库服务器。插件不会回写原始画布包。导出的 `AGENTS.md`/`CLAUDE.md` 可能把本插件列为可选的只读辅助;这个提及不授予写入权限,包内修改仍以该指南为准。
39
39
 
40
40
  | 来源 | 默认行为 |
41
41
  | --- | --- |
@@ -57,21 +57,21 @@ JSON/`.canvas` 是源数据,SQLite 是可重建的本地查询索引,无
57
57
  - `wiki/`:主题/实体页和不可变修订;每次写入更新 `index.md`(目录)并追加 `log.md`(时间线)。
58
58
  - `raw-library.sqlite3`:`search_archive` 的全文索引,覆盖 `knowledge/` 与所有研究证据,可重建。
59
59
 
60
- 配置默认为 `~/.config/bookmark-research/settings.json`。`wiki.after_research` 决定研究结束后的 Wiki 整理:`suggest`(默认,先建议再问)、`auto`、`off`。支持 XDG 和显式路径覆盖,多宿主可共享数据。索引更新不会自动抓网页、运行 LLM 或改写 Wiki;来源变化时提示复核,旧研究与证据保留。
60
+ 配置默认为 `~/.config/bookmark-research/settings.json`。`wiki.after_research` 决定研究结束后的 Wiki 整理:`suggest`(默认,遵循已有授权,否则先建议)、`auto`、`off`。支持 XDG 和显式路径覆盖,多宿主可共享数据。索引更新不会自动抓网页、运行 LLM 或改写 Wiki;来源变化时提示复核,旧研究与证据保留。
61
61
 
62
62
  `research_record` 支持单条 `entry` 或每批至多 50 条的 `entries`,按顺序校验后一次保存,返回精简编号;稳定的 `batch_id` 可避免重试产生重复记录。依赖新 claim ID 的记录在读取返回值后另批提交。`resume` 和 `external_run` 仍需单条调用,详见 [证据记录](../skills/bookmark-research/references/zh/deep-research.md)。
63
63
 
64
64
  ## 搜索、配置与语言
65
65
 
66
- `search.providers` 为第一轮,`search.fallback_providers` 为无结果时的备用列表;设为空数组可关闭搜索回退。读取单独配置 `fetch.provider` 和 `fetch.providers`。调用时明确指定 provider/providers 则只用指定服务。已有配置若只设置过搜索 providers,会保留原来的服务范围;新研究冻结当时的选择,旧记录重放不会增加请求。瀑布流按轮补缺,同轮服务并发;已发出的请求仍需等待结束或超时。普通网页归档开启,深度研究始终保存任务证据。
66
+ `search.providers` 为第一轮,`search.fallback_providers` 为无结果时的备用列表;设为空数组可关闭搜索回退。第一轮策略由 `search.strategy` 选择(默认 hedged 全并发对冲;staggered 错峰、sequential 顺序、wait_all 等全部),按 `search.grace_seconds`(默认 2)与 `search.deadline_seconds`(默认 10)约束:超限的 provider 被放弃或不再调用,分别记入 `routing.abandoned_providers` 与 `routing.not_attempted_providers`,被放弃的请求可能仍消耗额度;研究任务保持等待全部。读取单独配置 `fetch.provider` 和 `fetch.providers`,策略由 `fetch.strategy` 选择(默认 staggered:当前提供商停滞超过 `fetch.grace_seconds` 才并行下一家;hedged 全并发、sequential 逐家;被放弃者记入 `abandoned_providers`)。`fetch.reuse_seconds` 可在窗口内直接复用已存正文(返回 `reused_sources`,不联网、不占抓取预算),`search.cache_seconds` 让重复的相同搜索走短期缓存(批次标记 `cached:true`)。调用时明确指定 provider/providers 则只用指定服务。已有配置若只设置过搜索 providers,会保留原来的服务范围;新研究冻结当时的选择,旧记录重放不会增加请求。瀑布流按轮补缺,同轮服务并发;已发出的请求仍需等待结束或超时。普通网页归档开启,深度研究始终保存任务证据。
67
67
 
68
68
  可以读取公开 GitHub 仓库页面、README、文件和 issues;读取 README 不等于遍历整个代码仓库。代码审查按任务选择具体文件或宿主已有 GitHub 工具,插件未额外安装 GitHub MCP。
69
69
 
70
- 网络访问依赖服务方的认证与额度。可运行 `python3 src/cli.py setup` 隐藏输入密钥,或在宿主环境设置 `EXA_API_KEY`、`PARALLEL_API_KEY`、`TAVILY_API_KEY`、`JINA_API_KEY`、`OPENAI_API_KEY`。密钥默认保存为配置旁仅当前用户可读的 `credentials.json`,环境变量优先。无需给宿主研究额外填写一套模型地址。
70
+ 网络访问依赖服务方的认证与额度。可运行 `python3 src/cli.py setup` 隐藏输入密钥,或在宿主环境设置 `EXA_API_KEY`、`PARALLEL_API_KEY`、`TAVILY_API_KEY`、`JINA_API_KEY`、`DEEPSEEK_API_KEY`、`PERPLEXITY_API_KEY`、`XAI_API_KEY`、`CUSTOM_AGENTIC_API_KEY`、`OPENAI_API_KEY`。密钥默认保存为配置旁仅当前用户可读的 `credentials.json`,环境变量优先。Perplexity 是结构化搜索来源;Grok 和自定义模型通过独立 `agentic_search` 返回模型回答和引用,不会自动并入 `search_web` 的 URL 聚合。
71
71
 
72
- Skill 在每个联网研究新问题前调用 `research_readiness`,默认首次、配置/密钥变化或 15 分钟过期时刷新。向导可改为每题检查或仅手动检查;本地查询不联网。结果区分密钥配置、目录可达、实际检索与宿主 OAuth,检查不会启动专业研究任务。
72
+ 需要诊断服务访问问题时,可从高级工具面调用 `research_readiness`,显式检查默认在首次、配置/密钥变化或 15 分钟过期时刷新。向导可改为每题检查或仅手动检查;本地查询不联网。结果区分密钥配置、目录可达、实际检索与宿主 OAuth,检查不会启动专业研究任务。
73
73
 
74
- 中英文用户共用一个插件;回答、报告正文和 Wiki 章节跟随用户指定语言。原始引用和 URL 保留原文,译文另列。执行 Skill 和 11 篇方法参考以英文维护,配完整中文阅读对照;子代理和工作流也会接收本次输出语言。详见[指令与提示索引](instructions.md)。工具字段、技术诊断和部分固定元数据标签使用英文。
74
+ 中英文用户共用一个插件;回答、报告正文和 Wiki 章节跟随用户指定语言。原始引用和 URL 保留原文,译文另列。执行 Skill 和方法参考以英文维护,配完整中文阅读对照;子代理和工作流也会接收本次输出语言。详见[指令与提示索引](instructions.md)。工具字段、技术诊断和部分固定元数据标签使用英文。
75
75
 
76
76
  ## 宿主与验证范围
77
77
 
@@ -79,10 +79,9 @@ Skill 在每个联网研究新问题前调用 `research_readiness`,默认首
79
79
  | --- | --- | --- |
80
80
  | Codex | 原生 Plugin + Skill + MCP | 隔离配置中的原生安装/更新与 stdio 检查。 |
81
81
  | Claude Code | 持久 marketplace/插件和 Dynamic Workflow | 隔离配置中的原生安装/更新/缓存检查;模型调用另行验证。 |
82
- | Pi | Skill + CLI/stdio 桥 | 适配器隔离验证;子代理工作流依赖已有扩展。 |
83
82
  | DSH | 可搬移 bundle,包含 Skill 与 MCP | 安装器/适配器验证;工作流仍需宿主服务与引擎。 |
84
83
 
85
- 另有 Agent Plugins 1.0.0 标准格式导出。适配器存在不代表每个宿主都已完成真实研究。Wiki 保存引用、审阅和修订;评测根据实际运行数据及显式评审标签计算,示例分数不能证明研究质量。
84
+ 适配器存在不代表每个宿主都已完成真实研究。Wiki 保存引用、审阅和修订;来源完整性与语义支持分别判断,工具检查通过不能证明研究质量。
86
85
 
87
86
  ## 开发与来源
88
87
 
@@ -92,4 +91,4 @@ python3 scripts/verify_fixture.py --output /tmp/bookmark-research-verification
92
91
  python3 scripts/export_bundle.py --format codex --output exports/codex/bookmark-research
93
92
  ```
94
93
 
95
- 研究来源与演进见[设计调研](research-0.2.0.md)、[宿主兼容性](harness-compatibility.md)和[Wiki/评测](wiki-quality.zh.md)。项目源自 Bookmark Canvas,沿用 [GPL-3.0](../LICENSE)。
94
+ 研究来源与演进见[宿主兼容性](harness-compatibility.md)和[Wiki](../skills/bookmark-research/references/zh/wiki.md);早期设计与验证记录可从 Git 历史查阅。项目源自 Bookmark Canvas,沿用 [GPL-3.0](../LICENSE)。
@@ -6,14 +6,13 @@
6
6
  | --- | --- | --- |
7
7
  | `npx bookmark-research@latest install codex` | npm 发布包 → Codex 格式 | Codex 原生命令 |
8
8
  | `npx bookmark-research@latest install claude` | 同一个 npm 包 → Claude 格式 | Claude Code 原生命令 |
9
- | `npx bookmark-research@latest install pi` | 同一个 npm 包 → Pi 格式 | `pi install` |
10
9
  | `npx bookmark-research@latest install dsh --profile web` | 同一个 npm 包 → DSH bundle | `dsh plugin --profile web add` |
11
10
  | GitHub `install.sh` | 转交上述 npm 入口 | 所选宿主原生命令 |
12
11
  | Codex GitHub marketplace | 清单中固定的 npm 版本 | Codex 直接下载和登记 |
13
12
 
14
- 统一的是发布内容和来源。不同宿主需要不同清单,安装器只生成所需格式,用户配置、宿主登记及缓存仍交给宿主命令。Pi 的基础路径提供 Skill 和 CLI;其他宿主按各自适配提供 MCP。
13
+ 统一的是发布内容和来源。不同宿主需要不同清单,安装器只生成所需格式,用户配置、宿主登记及缓存仍交给宿主命令。Claude Code、Codex 和 DSH 按各自适配提供 MCP 或 Skill。
15
14
 
16
- 默认安装器记录 `npm:bookmark-research`(`latest`),更新时重新下载,不依赖已清理的 npx 缓存。显式 `--source npm:bookmark-research@VERSION` 会保留版本;要测试同一个固定发布版,在四个宿主使用相同参数。Codex 原生 marketplace 使用清单固定版本,跟随清单更新。需要新版安装器时运行 `npx bookmark-research@latest update`,或先更新全局 npm 安装。
15
+ 默认安装器保留当前启动包的内容快照,`update` 继续使用这一构建,不依赖已清理的 npx 缓存。采用新发布版时运行 `npx bookmark-research@latest install` 并确认升级覆盖;Codex 非交互方式添加 `--replace-source`。显式 `--source npm:bookmark-research` 记录 `latest` 并在更新时重新下载;`--source npm:bookmark-research@VERSION` 固定版本。要测试同一个固定发布版,在三个宿主使用相同参数。Codex 原生 marketplace 使用清单固定版本,跟随清单更新。需要新版安装器时使用 `npx bookmark-research@latest`,或先更新全局 npm 安装;采用新版发布内容需运行 `install` 并确认升级覆盖。
17
16
 
18
17
  源码开发使用 `python3 scripts/install.py install --source PATH`,也可显式选择 Git 仓库和 `--ref`。旧 Git/本地安装保留来源,不静默转成 npm;切换时先用宿主命令处理旧登记。源码导出、ZIP 和测试包脚本保留为开发工具,CI 的验证产物仍可包含 npm `.tgz` 与 SHA-256 校验文件,但不作为 GitHub Release 下载入口。GitHub 自动生成的 Source code 压缩包是源码快照,不能单独关闭,不作为安装包。
19
18
 
@@ -21,7 +20,7 @@
21
20
 
22
21
  候选版本在 `release/` 分支同步三个版本清单并运行 CI。该分支的 registry 集成测试使用当前已发布渠道版本,源码测试、原生安装测试和 npm 打包检查仍验证候选内容;主分支的 registry 测试始终验证 marketplace 固定版本。发布通过 CI 的 npm 包并核验 registry 后,再将候选分支合入主分支,避免默认安装清单提前指向未发布版本。
23
22
 
24
- 测试版使用 npm 的 `beta` 标签;若创建 GitHub 版本说明,则标记为预发布。不会自动移动 npm 的 `latest` 标签。安装测试版时同时固定安装器与内容来源,例如 `npx bookmark-research@0.5.0-beta.9 install --source npm:bookmark-research@0.5.0-beta.9`。仅将 npx 改为 `@beta` 不会改变默认内容来源 `latest`;已固定的旧版安装也不会自动换成测试版。
23
+ 发布时保持 npm 的 `latest` 标签始终指向最新构建,用户直接使用 `npx bookmark-research install`(或 `npx bookmark-research@latest install`)即可默认安装最新版。启动器会自动读取当前运行包版本并固定内容来源,无需重复指定 `--source`。已存在的宿主配置支持无缝覆盖升级。
25
24
 
26
25
  ## 官方资料与项目实例
27
26
 
@@ -29,9 +28,7 @@
29
28
 
30
29
  - [OpenAI:Package your plugin](https://developers.openai.com/plugins/build/plugins):marketplace 可指向本地、Git 或 npm;npm 内容下载不执行生命周期脚本。
31
30
  - [Claude Code:Plugin marketplaces](https://code.claude.com/docs/en/plugin-marketplaces#npm-packages):支持 npm、GitHub、Git URL 和本地目录等来源。
32
- - [Pi:Packages](https://pi.dev/docs/latest/packages):支持 npm、Git 和本地路径;版本化 npm 来源保持固定。
33
31
  - [DSH:Package and install a plugin](https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/publish):支持 Git 安装,也建议发布已构建的 npm 包或 tarball,免去用户安装时构建。
34
- - [Superpowers](https://github.com/obra/superpowers):按宿主提供不同安装方式,Pi 使用 Git 仓库,Claude Code 使用 marketplace,并非 npm 唯一来源。
35
- - [pi-skills](https://github.com/badlogic/pi-skills):跨宿主 Skill 集合,文档仍提供 Git 克隆安装。
32
+ - [Superpowers](https://github.com/obra/superpowers):按宿主提供不同安装方式;Claude Code 使用 marketplace,并非 npm 唯一来源。
36
33
 
37
34
  这些资料说明“宿主安装方式不同”是正常的;本项目统一发布包后仍保留必要的宿主适配。
@@ -1,306 +1,17 @@
1
- # 宿主兼容、工作流与打包
1
+ # 三宿主接入与验证边界
2
2
 
3
- 更新日期:2026-10-08。四宿主共用同一 Skill、Python CLI、stdio MCP 和研究档案。当前宿主模型负责规划、搜索/阅读、判断证据、按缺口补查及综合;原生协作支持独立分工。Deep Research 在这条流程上增加持续调查、独立核验、覆盖检查和报告。外部研究 API 可承担具体子问题,缺少它们仍能研究。
3
+ Codex、Claude Code、DeepSeek Harness 共用同一 Skill、Python CLI、stdio MCP、归档和 Wiki。宿主负责推理、搜索策略、协作与最终表达;插件默认提供 22 个日常工具。`search_web` 聚合插件配置的来源;Perplexity 是可选结构化搜索来源,Grok 则通过独立 `agentic_search` 返回模型回答与引用。研究 API 可独立使用,完整资料审计及持久化研究记录通过 `deep` 预设按需启用。
4
4
 
5
- **正文依据、文件生成、隔离脚本检查、真实 MCP 调用和宿主端到端研究是不同验证层级。** 本轮在 DSH 桌面版 profile `desktop` 上完成了一次真实安装,并观察到 Skill 注册与 MCP 工具实际应答;Pi 仍未安装,未改全局配置,未启动付费研究模型。具体脚本调用和研究规则见 [宿主工作流参考](../skills/bookmark-research/references/host-workflows.md)。
6
-
7
- | 宿主 | 协作基础与本插件入口 | 生命周期与限制 |
5
+ | 宿主 | 接入 | 协作 |
8
6
  | --- | --- | --- |
9
- | Codex | `hosts/codex/delegate.md`+原生子代理;`prepare.py` 读取全量分页、仅输出分组 | 使用当前会话原生工具,不假设有 JavaScript workflow runtime,不安装全局 agent 定义 |
10
- | Claude Code | 普通 `Agent`/旧版 `Task`;可选已启用的 Agent Teams;整包可用 `/bookmark-research:bookmark-research` | 普通子代理可继承受过滤的 MCP 工具,Skill 需预载或读取;团队默认关闭且不继承主代理历史;Dynamic Workflow 为独立可选入口 |
11
- | Pi | 已加载的 `subagent` 扩展;整包可用登记后的 `pi_subagent_workflow` | 核心不内置子代理或 MCP;官方扩展示例支持单任务、并发和链式任务;具体工具与等待方式以已加载扩展为准 |
12
- | DSH | 已配置的 subagent;整包可将 `hosts/dsh/workflow-call.py` 生成的 `{meta,script,args}` 交给 `workflow` | profile 需提供相应服务与工具;`workflow` 等完整流程后返回结果,不能当作后台 start/poll 接口 |
13
-
14
- 本次通过插件的 Exa 检索并读取官方正文,新增依据为 [W12–W16],并重读 [W3][W7]。这验证能力文档,没有执行四宿主完整研究。子代理须获得具体问题、范围、相关 Skill 内容和共享 MCP/CLI 数据入口,不能假定父代理上下文在四宿主间以相同方式继承。
15
-
16
- 本次默认流程调整通过 369 项单元测试、Skill/插件校验及新安装缓存的真实 stdio MCP 检查;5 个选路场景通过,61 个导出文件与缓存一致。这里只验证选路与工具接入,四宿主端到端研究仍未运行。记录见 [host-validation.json](host-validation.json) 的 `host_first_review`。
17
-
18
- `research_route` 对普通 Agentic Search 优先选择当前模型的搜索/阅读循环,不强制完整研究会话;深度任务优先原生协作,整包 `batch_research` 才按偏好选择分组脚本。已保存 API 偏好只排列外部服务,显式 provider 才直接指定服务。路由依据当前工具和已加载能力,不凭宿主名称推断;没有子代理时主代理继续,并准确说明复核方式。
19
-
20
- 三种脚本和 Codex 委派均执行全量清单 → 分组阅读 → 独立核验 → 全量差集补查 → 保存完整分析 → 引用报告。保留全部 `u-` ID 及书签实例;`sN` 证据 ID 不能代替原始输入清单。每个 coverage filter 单独跟随 `next_offset` 到结束,差集长度须与 `difference_counts` 一致。抓取失败或全排除不能完成研究。
21
-
22
- 报告子代理通过 `research_record external_run` 保存完整分析 JSON,返回实际的 `recorded.result_path` 和 `recorded.result_sha256`。其中 `local:<run_key>` 明确是本地关联号;该观察记录已结束的分析阶段,不冒充原生宿主 run ID 或整项研究完成。最终仍由 `research_finish` 检查证据、问题和覆盖门槛。主代理收到宿主返回后,还须直接读取 `research_status` 和完整 coverage 分页,对照实际产物与附件哈希;脚本自身成功或报告子代理返回路径都不能代替核验。
23
-
24
- | 本机检查(2026-09-11) | 结果与边界 |
25
- | --- | --- |
26
- | Codex 0.153.4 | `multi_agent` 为 stable、enabled;实际委派仍以会话可见工具为准 |
27
- | Claude Code 2.1.247 | `claude plugin validate --strict` 通过、无警告;并未执行付费工作流 |
28
- | 本地宿主测试 | 8 项通过,含 36 项隔离脚本检查;真实 stdio MCP 验证 207 项完整分页和完整结果附件回读 |
29
- | Pi / DSH | PATH 中未安装;本机 Node 22.17.0 低于 Pi workflow 要求的 22.19 |
30
- | 端到端研究 | 本轮未运行;不能由上述检查推断四宿主的完整研究已通过 |
31
-
32
- 正文 SHA-256、原生校验和检查记录见 [host-validation.json](host-validation.json)。本轮 [W1–W8] 来自 2026-09-10 保存的 Exa 提取正文,完整性为 unknown,来源站实时新鲜度未建立;补充接口资料于 2026-09-11 读取。Pi 两项扩展的作者文档不等于 Pi 核心能力承诺。
33
-
34
- | ID | 已读依据 |
35
- | --- | --- |
36
- | W1 | [Claude Workflows](https://code.claude.com/docs/en/workflows) |
37
- | W2 | [Introducing dynamic workflows](https://claude.com/blog/introducing-dynamic-workflows-in-claude-code) |
38
- | W3 | [Codex customization](https://developers.openai.com/codex/concepts/customization) |
39
- | W4 | [Codex workflows](https://developers.openai.com/codex/workflows) |
40
- | W5 | [pi-subagents-workflows](https://pi.dev/packages/pi-subagents-workflows) |
41
- | W6 | [pi-subagents](https://github.com/nicobailon/pi-subagents) |
42
- | W7 | [DSH Workflow subsystem](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/workflow) |
43
- | W8 | [DSH workflow tool](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/workflow/tool-workflow/README.md) |
44
- | W9 | [Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents)(旧官方 URL 重定向后的已读页面) |
45
- | W10 | [Pi extension workflows](https://github.com/nicobailon/pi-subagents/blob/main/docs/workflows.md) |
46
- | W11 | [Pi extension tool reference](https://github.com/nicobailon/pi-subagents/blob/main/docs/tool-reference.md) |
47
- | W12 | [Codex subagents](https://developers.openai.com/codex/subagents),2026-09-13 经 Exa 重读:并发委派、等待、配置继承及显式委派规则 |
48
- | W13 | [Claude subagents](https://code.claude.com/docs/en/sub-agents):普通子代理、MCP 工具过滤、Skill 预载与任务上下文 |
49
- | W14 | [Claude Agent Teams](https://code.claude.com/docs/en/agent-teams):实验开关、共享任务、代理通信及上下文边界 |
50
- | W15 | [Pi usage](https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/docs/usage.md):核心不内置 MCP/子代理,通过扩展和包提供 |
51
- | W16 | [Pi 官方 subagent 示例](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/examples/extensions/subagent):单任务、并发和链式调用 |
52
-
53
- 下文保留 2026-09-07 至 09-10 的基础打包核验及 Codex 路径规则。H / P / D 来源见 [harness-sources.json](harness-sources.json),历史版本测试见 [0.2.0 验证记录](validation-0.2.0.md)。
54
-
55
- | 目标 | 真实入口 | Skill/MCP 如何接入 | 本项目的最小路线 |
56
- | --- | --- | --- | --- |
57
- | OpenAI Codex 插件 | `.codex-plugin/plugin.json` | manifest 指向 skills、MCP 配置等组件 | 原生 Codex 包;具体安装与验证按本项目 README |
58
- | Claude Code 插件 | `.claude-plugin/plugin.json`;当前文档允许省略 manifest 后按约定发现组件 | 根 `skills/`、`.mcp.json` 或 manifest 配置 | 单独保留 Claude manifest/MCP 配置 |
59
- | Agent Plugins 1.0.0 标准包 | **根 `plugin.json`**,必填 `$schema` 与 `name` | 固定发现根 `skills/`、`mcp.json` | 从同一源码独立导出标准包 |
60
- | Pi | `package.json` 的 `pi` 字段,或资源目录约定 | 原生 skills/extensions;MCP 要靠扩展 | `pi.skills`+Skill 调用 CLI;多组任务另登记项目工作流 |
61
- | DeepSeek Harness(DSH) | 包在 `package.json` 声明 `dsh.bundle.patch`,由 `dsh plugin` 或插件管理器安装;`--patch` 仍可手工加载 Cordis 配置 | 原生 Skill provider;官方 `dsh-mcp-client` 桥接 MCP tools | 发布包自带按安装位置解析的 `bundle.patch.yml`,registry 可直接安装;绝对路径 `cordis.patch.yml` 仅作手工适配 |
62
-
63
- 这些入口不是同一文件的不同别名。符合 Agent Skills 的 `SKILL.md` 和 MCP 协议是主要复用边界;某个客户端能加载 Skill,并不表示它已经支持 Agent Plugins 的根 manifest。[H01][H04][H05][P02][D02]
64
-
65
- **1.稳定数据位置与共用入口**
66
-
67
- 本项目的 stdio MCP 启动方式:
68
-
69
- ```sh
70
- python3 /absolute/path/to/bookmark-research/src/cli.py --db /absolute/path/to/plugin-data/index.sqlite3 serve
71
- ```
72
-
73
- 省略 `--db` 时,CLI 使用 `BOOKMARK_RESEARCH_DATA_DIR/index.sqlite3`;未设置时使用 `${XDG_DATA_HOME}/bookmark-research/index.sqlite3`,其中 `XDG_DATA_HOME` 默认是 `~/.local/share`。索引不放在插件安装缓存或原始书签包内。多个载体若要访问同一库,应明确指向同一个数据库路径;只保留相同插件名称并不会共享数据。
74
-
75
- Codex 的 stdio MCP 需要显式允许转发自定义环境变量([官方说明](https://developers.openai.com/codex/mcp#stdio-servers))。本插件原生 manifest 的 `env_vars` 列出 `BOOKMARK_RESEARCH_DATA_DIR`、`BOOKMARK_RESEARCH_CONFIG`、`XDG_DATA_HOME`、`XDG_CONFIG_HOME`、`EXA_API_KEY`、`PARALLEL_API_KEY`、`TAVILY_API_KEY`;只在启动进程中设置变量而未透传时,MCP 可能仍读取默认目录。已使用全新临时目录核验空来源列表和虚构数据导入。
76
-
77
- 本项目五种导出均保留上述 CLI 行为,**不强制传入 `--db` 或 `${PLUGIN_DATA}`**。需要共库时,在各载体实际启动 MCP/CLI 子进程的环境中设置相同的 `BOOKMARK_RESEARCH_DATA_DIR`,或修改启动参数,显式指定同一 `--db` 路径。客户端可能过滤环境变量,不能仅凭外部终端已设置就断言子进程一定继承。
78
-
79
- Agent Plugins 标准的 `PLUGIN_DATA` 是**每个客户端管理的、属于该安装实例的数据目录**,规范要求升级时保留,但没有保证不同客户端的目录相同。如果使用者选择把数据库放入该目录,它可以跨该插件的升级保存,却不自动与 CLI 默认库或另一载体的库共享。[H01]
80
-
81
- Skill 中应通过当前载体实际提供的工具或 CLI 调用能力,不把模型固定工具名前缀当成可移植协议。尤其 DSH 会把 MCP 工具映射成 `mcp__<serverName>__<tool>`;其他客户端的呈现方式由它们决定。[D04]
82
-
83
- **2.Pi:Skill、CLI 与保存工作流**
84
-
85
- 多组工作流需要 Node 22.19+、Pi 0.83+、`pi-subagents` 0.43.0+,以及同一父会话中加载的 `pi-subagents-workflows`。运行 `python3 hosts/pi/register-workflow.py --project PATH` 只登记该项目的 `.pi/subagent-workflows/bookmark-research/`,不修改 Pi settings 或安装扩展。项目必须受信任。相同定义幂等,不同定义保留并报冲突。[W5]
86
-
87
- 脚本使用有序的 `runs.all` 结果,逐项检查 `run.error` 与 `ok`,从 `structuredOutput` 取结构化内容;声明参数为 `outputSchema`,不是 `schema`。脚本只使用顶层 await 与 Promise 链,避免运行时禁止的嵌套 async helper。`delegate` 需已有研究 MCP,或通过 Bash 调用本包 `hosts/shared/research-call.py`。该 Python 桥真实执行同一 stdio 服务,登记器把稳定包路径绑定到参数,迁移后须重新登记。[W10][W11]
88
-
89
- 本轮 Pi 官网与官方仓库指向 `earendil-works/pi`,当前包名是 `@earendil-works/pi-coding-agent`。历史教程里的 `badlogic/pi-mono`、`@mariozechner/...` 不应无核验地作为当前安装示例。[P01][P02]
90
-
91
- Pi 的包声明可只包含共享 Skill:
92
-
93
- ```json
94
- {
95
- "name": "bookmark-research",
96
- "version": "0.2.0",
97
- "keywords": ["pi-package"],
98
- "pi": {
99
- "skills": ["./skills"]
100
- }
101
- }
102
- ```
103
-
104
- 这会让 Pi 发现 `skills/bookmark-research/SKILL.md`,不意味着注册了名为 `search_bookmarks` 的 Pi 原生工具。Skill 可以引导模型调用已有 Python CLI;此时复用的是同一个查询程序和数据库。[P02][P03]
105
-
106
- 先导出 Pi 的原生 Skill 包,再按实际导出路径单次加载:
107
-
108
- ```sh
109
- python3 scripts/export_bundle.py --format pi --output /private/tmp/bookmark-research-pi
110
- pi --skill /private/tmp/bookmark-research-pi/skills/bookmark-research/SKILL.md
111
- ```
112
-
113
- 进入 Pi 后用 `/skill:bookmark-research` 加载工作流。若以后决定持久注册此本地包,可使用:
114
-
115
- ```sh
116
- pi install /private/tmp/bookmark-research-pi
117
- ```
118
-
119
- `pi install` 默认修改 `~/.pi/agent/settings.json`;`-l` 使用项目 `.pi/settings.json`。本地路径包不复制文件,只将位置加入设置。本文未执行这些命令。[P02]
120
-
121
- Pi 官方 `usage.md` 明确写明核心不内建 MCP;它希望通过扩展或包添加这种能力。不能把 Codex/Claude 的 `.mcp.json` 放进包里,就声称 Pi 会原生连接该服务器。[P05]
122
-
123
- 将来需要模型直接调用结构化 Pi 工具时,有两个扩展方向:
124
-
125
- - 编写薄 Pi extension,通过 `pi.registerTool()` 调用本项目 CLI 或 MCP。官方扩展入口是接收 `ExtensionAPI` 的默认导出工厂函数;当前类型入口是 `@earendil-works/pi-coding-agent`,参数 schema 示例使用 `typebox`。[P04]
126
- - 明确选择并验证一个 MCP adapter 扩展。Pi 官方包目录可以列出第三方 adapter,但收录不等于 Pi 核心实现,更不等于本项目已经测试该 adapter。本版不自动引入某个第三方桥。
127
-
128
- 只有实际提供相应文件后,才把 `pi.extensions` 指向扩展路径。当前包提供 Pi Skill、保存工作流与 Python 工具桥,没有声明一个 Pi 原生工具 extension。
129
-
130
- Pi 支持全局 `~/.pi/agent/skills/`、`~/.agents/skills/`、项目 `.pi/skills/`/`.agents/skills/`、包内 skills、设置路径与重复的 `--skill`。Pi 的递归发现比 Agent Plugins 标准宽松,但共享包仍应使用 `skills/<name>/SKILL.md` 的一层布局,并让目录名与 skill name 一致,兼顾更严格的客户端。[P03]
131
-
132
- **3.DeepSeek Harness:配置 bundle 和运行插件是两层**
133
-
134
- 当前导出还提供原生工作流调用定义。`python3 hosts/dsh/workflow-call.py --research-id RID --run-key review-1` 输出完整工具参数,`meta`、无 export 的 `script` 与对象 `args` 分开。所选 profile 必须预先配置 workflow service、worker-thread engine 和 tool;只加载下方 MCP patch 不会自动启用 workflow。普通失败保留,fatal schema / cap 错误由宿主传播。完整分析结果显式保存到共享研究档案,不依赖宿主渲染摘要。[W7][W8]
135
-
136
- DSH 当前官方 README 将项目标为 developer preview,并明确存在兼容性变化;因此这里依据当前 `master` 文档描述接口,没有承诺未来版本保持不变。[D01]
137
-
138
- DSH 的原生运行插件是 Cordis 模块,可导出 `name`、`inject` 和 `apply(ctx, config)`。如果使用 tools 服务,就声明 `inject = ['tools']`;框架等依赖就绪后加载。对象和类形式也受支持。这与 Codex/Claude 的“目录 manifest 包装一组 Skill 和 MCP”不是同一个运行入口。[D03]
139
-
140
- 但本项目**无需为了接入 DSH 重写原生查询插件**。官方 `@deepseek-ai/dsh-mcp-client` 已经负责连接 stdio 或 Streamable HTTP MCP,调用 `tools/list` 并注册工具。它每个实例接一个 MCP server,支持取消、超时、重连及工具重新同步;本轮文档明确只桥接 tools,Resources/Prompts 尚未提供对应消费者。[D04][D05]
141
-
142
- 下面是导出到 `/private/tmp/bookmark-research-dsh` 时的 `cordis.patch.yml` 内容:
143
-
144
- ```yaml
145
- - insert:
146
- - id: bookmark-research-mcp
147
- name: '@deepseek-ai/dsh-mcp-client'
148
- config:
149
- serverName: bookmark-research
150
- transport: stdio
151
- command: python3
152
- args:
153
- - /private/tmp/bookmark-research-dsh/src/cli.py
154
- - serve
155
- failOnStartupError: true
156
- ```
157
-
158
- `command` 与 `args` 分开传递。不要在这个 DSH 片段里假设 `${PLUGIN_ROOT}` 会像 Codex/Agent Plugins 一样展开;本轮核实的 MCP 客户端并未定义这种插件根占位符约定。绝对路径片段适合本机 checkout;搬迁或重新安装到其他位置后需要重新生成。DSH 的 patch 文件位置也不会改变模块路径解析所依据的 profile 目录。[D03][D05]
159
-
160
- 发布包现在**自带** `bundle.patch.yml` 并在 `package.json` 声明 `dsh.bundle.patch`,因此 `dsh plugin --profile <name> add bookmark-research@<version>`(以及 DSH 插件管理界面)可以直接从 registry 安装;`dsh` 的 bundle 对账逻辑会把声明了 `dsh.bundle` 且 patch 存在的包自动加入 `dsh.profile.bundles`。层内不写死本机路径:`command`、`args`、`cwd` 与转发的环境变量都由入口模块 `hosts/dsh/plugin.js` 在加载时提供(`bookmarkResearchPaths.python/mcpArgs/env`),模块用与 npm 启动器相同的顺序发现 Python 3.9+/SQLite,所以导出副本、registry 安装和 Windows 都不需要重生成 patch。统一安装器仍导出带校验和的固定副本,用于可验证的托管安装;对不含该文件的旧发布包或旧 Git ref,导出器按模块的旧契约生成等价层,安装不回归。[D02][D03]
161
-
162
- DSH 桌面版把 profile 名 `desktop` 保留给 Electron 载体:启动器对该名字拒绝一切 boot/dump(`--dump-config` 亦然),只有载体自身可以管理其插件。因此对 `desktop` 的安装须用桌面版自带 CLI(`--dsh "<App>/Contents/Resources/runtime/cli/bin/dsh"`,它自带 pnpm,无需 PATH 中的 pnpm),安装器的验证改为读取持久层:profile 依赖指向该包、`dsh.bundle.patch` 与入口模块按包目录相对解析且文件存在、层内包含 Skill 与 MCP 行。2026-10-08 在本机(macOS、桌面运行时 0.2.0-rc.2、发布包 0.5.0-beta.5)实测:注册后 Skill 出现在宿主目录,`mcp__bookmark-research__*` 工具正常应答,运行中的 MCP 子进程解析到已安装包目录。[D02][D08]
163
-
164
- 导出及查看合并配置的形式是:
165
-
166
- ```sh
167
- python3 scripts/export_bundle.py --format dsh --output /private/tmp/bookmark-research-dsh
168
- dsh --profile web --patch /private/tmp/bookmark-research-dsh/cordis.patch.yml --dump-config
169
- ```
170
-
171
- 实际启动可使用 `dsh web --patch <绝对配置路径>`。该手工路线仍属待客户端验证的接入说明,且不覆盖保留的 `desktop` profile。新建任意名称的 profile 默认只有 base bundle;`web` profile 才会按官方模板包含 Web 表面,不应把“创建一个任意 profile”描述成自动创建了完整 Web 应用。[D02][D08]
172
-
173
- `dsh plugin` 在 profile 目录中通过 pnpm 管理依赖,并把声明了 `dsh.bundle` 的包加入 `dsh.profile.bundles`。没有该声明的 npm 包仍能作为普通依赖安装,但不会自动增加插件配置层。后层 patch 会替换命中行的整个 `config`,不做深度合并。[D02][D08]
174
-
175
- DSH 的 Skill 可直接复用共享 `SKILL.md`。本轮官方 Skill provider 的默认发现顺序为:
176
-
177
- 1. 项目 `.dsh/skills/`;
178
- 2. 项目 `.agents/skills/`;
179
- 3. 显式 `customSkillDirs`;
180
- 4. 用户 `$DSH_HOME/skills`,默认 `~/.dsh/skills`;
181
- 5. 用户 `$DSH_AGENTS_HOME/skills`,默认 `~/.agents/skills`;
182
- 6. 配置过的 bundled skill root。
183
-
184
- 目录包采用 `<name>/SKILL.md`,不递归寻找任意层级的 `**/SKILL.md`。要加载源码树中的 `skills/`,应由现有 Skill provider 的 `customSkillDirs` 指向其绝对路径,或通过被识别的 skills 根分发。仅把 `skills/` 放到任意 DSH npm 包根目录,不会因为它同时是 Codex/Pi 的 Skill 目录就自动被发现。[D06][D07]
185
-
186
- **4.Agent Plugins 1.0.0:独立生成标准导出包**
187
-
188
- 规范的入口是根 `plugin.json`,不是 `.agents/plugin.json`、`.codex-plugin/plugin.json` 或 `.claude-plugin/plugin.json`。根 manifest 的顶层字段是封闭 schema,不能在其中加 Codex 风格的 `skills`、`mcpServers`、`interface` 字段。标准包从固定位置发现 skills 与 MCP。[H01][H02]
189
-
190
- 实际导出形状:
191
-
192
- ```text
193
- bookmark-research-agent-plugins/
194
- ├── plugin.json
195
- ├── mcp.json
196
- ├── skills/
197
- │ └── bookmark-research/
198
- │ └── SKILL.md
199
- ├── src/
200
- │ ├── cli.py
201
- │ └── … 所需的共享 Python 模块
202
- ├── config/
203
- │ └── providers.json
204
- └── README.md
205
- ```
206
-
207
- 根 `plugin.json`:
208
-
209
- ```json
210
- {
211
- "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
212
- "name": "bookmark-research",
213
- "version": "0.2.0",
214
- "description": "Query Bookmark Canvas packages through reusable skills and MCP tools."
215
- }
216
- ```
217
-
218
- 根 `mcp.json`:
219
-
220
- ```json
221
- {
222
- "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
223
- "mcpServers": {
224
- "bookmark-research": {
225
- "type": "stdio",
226
- "command": "python3",
227
- "args": [
228
- "${PLUGIN_ROOT}/src/cli.py",
229
- "serve"
230
- ]
231
- }
232
- }
233
- }
234
- ```
235
-
236
- 本示例与实际导出器一致,保留 CLI 的数据位置规则。标准提供 `PLUGIN_DATA` 这一能力,并不要求应用必须把数据库放在那里;本项目没有用它覆盖 `BOOKMARK_RESEARCH_DATA_DIR`。
237
-
238
- 需要遵守的实际边界:
239
-
240
- - 标准 `mcp.json` 必须同时有 `$schema` 与 `mcpServers`,每个 stdio server 必须有 `type: "stdio"` 与 `command`。[H03]
241
- - `command` 是一个可执行名称或 `./` 开头的包内可执行路径;不会展开占位符。Python 是外部运行时,所以这里用裸名称 `python3`,脚本位置放入 args。
242
- - `args`、`env`、`cwd` 可以展开 `${PLUGIN_ROOT}`/`${PLUGIN_DATA}`。省略 cwd 时使用插件根;不能假定任意 `${ENV_VAR}` 都会被标准客户端展开。
243
- - 不在 env 中自行定义 `PLUGIN_ROOT`/`PLUGIN_DATA`;两者由客户端提供。客户端应在启动前创建并保留可写 `PLUGIN_DATA`。
244
- - 包内可发现/执行文件的真实路径应留在插件根内。导出要复制需要的文件,不能用指向开发工作区外部的 symlink 冒充自包含包。
245
- - `skills/` 只发现立即子目录中的 `SKILL.md`,标准不要求客户端递归寻找深层 Skill。
246
- - §8 要求客户端专用数据放在客户端拥有的 reverse-domain namespace 中。标准导出包应排除 `.codex-plugin/`、`.claude-plugin/`、Pi/DSH 专用入口和 `skills/*/agents/openai.yaml` 等元数据;后者是为避免把客户端特定文件混入规范包而采取的保守导出策略。不要自行冒用 `com.openai` 或 `com.anthropic` namespace。
247
- - 规范没有给整个文件系统根目录列一个封闭白名单;不能推导出通用 `src/`、`bin/`、`docs/` 被禁止。闭合的是 manifest JSON 字段,客户端专用文件另受 §8 约束。
248
-
249
- 可共用同一源码树并生成多种包,但“标准包通过 schema 检查”不等于 Codex、Claude、Pi、DSH 的现有版本都能直接安装它。本文没有核实这些客户端已经将根 `plugin.json` 作为它们原生 manifest 的等价入口。[H01]
250
-
251
- **5.Codex 与 Claude:保留各自原生包装,不混用校验规则**
252
-
253
- OpenAI 官方文档要求 `.codex-plugin/plugin.json`。只把这个文件放进该隐藏目录,skills、MCP 配置、hooks 等留在插件根。当前官方文档对 MCP 文件示例采用 direct server map 或 `mcp_servers` wrapper;本地插件工具与客户端版本可能使用不同表示,应该分别验证实际生成的包装,不把一种文档示例自动当成所有客户端的通用形状。[H04]
254
-
255
- **Codex 0.153.4 的原生 MCP 路径需要显式设置 `cwd`。** 本次本机启动诊断确认:原生配置中的 `args: ["${PLUGIN_ROOT}/src/cli.py", "serve"]` 被原样传给子进程,未指定 `cwd` 时仍使用会话目录,子进程也没有收到 `PLUGIN_ROOT`/`CLAUDE_PLUGIN_ROOT` 注入。改用下面的 server 配置,使相对脚本路径基于安装后的插件目录解析:
256
-
257
- ```json
258
- {
259
- "command": "python3",
260
- "args": ["src/cli.py", "serve"],
261
- "cwd": "."
262
- }
263
- ```
264
-
265
- 精确版本源码 [`rust-v0.153.4` 的 `plugin_config.rs`](https://github.com/openai/codex/blob/rust-v0.153.4/codex-rs/codex-mcp/src/plugin_config.rs) 中,`normalize_plugin_mcp_server_value` 对 Host 来源只把显式相对 `cwd` 改成 `root.join(cwd)`,不展开 `command`/`args` 中的插件根占位符。Host 未设置 `cwd` 时,本函数保持未设置;executor-owned 分支另有默认根目录逻辑,不能把这一默认值套用于所有本机加载。官方文档对 hooks 的变量注入说明也不能直接用于原生 MCP。[H04][H06]
266
-
267
- 这项修正用于 Codex 原生包装。Agent Plugins 标准格式由另一套解析器处理,Claude 也有自己的变量约定,因此保留这两种导出的既有路径配置。修复后的插件安装与实际调用结果以本项目的客户端验证记录为准。[H01][H05][H06]
268
-
269
- Claude 当前文档的 manifest 路径是 `.claude-plugin/plugin.json`;有 manifest 时 name 必填,manifest 本身可省略。它还支持更多客户端组件。Claude 的根 `.mcp.json` 配置与 `CLAUDE_PLUGIN_ROOT` 等约定属于其原生格式;canonical Agent Plugins 采用的文件名是无点前缀的 `mcp.json`,占位符是 `PLUGIN_ROOT`/`PLUGIN_DATA`,不能机械复制后宣称格式相同。[H05]
270
-
271
- 当前 Claude 导出还在 manifest 中声明 `workflows: "./workflows"`。脚本包含 `export const meta`,通过 `/bookmark-research:bookmark-research` 接收结构化 `args`。自带 `/deep-research` 从 2.1.218 起需要显式调用,不能自动保证插件的全量清单覆盖。把 `ultracode` 写进 Skill、普通 `-p` 输入或未标注 human origin 的 SDK 输入不能触发工作流;插件不修改用户的 effort 或启用设置。[W1]
272
-
273
- 本项目应分别记录:
274
-
275
- | 验证层级 | 可以宣称什么 |
276
- | --- | --- |
277
- | 阅读官方文档/源码 | 已核实入口与接口形状 |
278
- | 生成 manifest 和配置 | 已提供对应格式的包/适配文件 |
279
- | 运行 CLI、协议与本地数据测试 | 已验证本项目核心功能与 MCP 行为 |
280
- | 在目标客户端实际加载并调用 | 该版本客户端的实际兼容性已验证 |
281
-
282
- 只有最后一层经过实际执行后,才应写“Pi/DSH/Claude 已验证可用”。本文对这些载体提供的是有第一方依据的导出包与适配说明;不会因为它们具备扩展机制就把尚未测试的客户端接入写成现成功能。
283
-
284
- **6.实际导出与验证方式**
285
-
286
- 在仓库工作区根目录运行:
287
-
288
- ```sh
289
- python3 scripts/export_bundle.py --format codex --output /private/tmp/bookmark-research-codex
290
- python3 scripts/export_bundle.py --format agent-plugin --output /private/tmp/bookmark-research-standard
291
- python3 scripts/export_bundle.py --format claude --output /private/tmp/bookmark-research-claude
292
- python3 scripts/export_bundle.py --format pi --output /private/tmp/bookmark-research-pi
293
- python3 scripts/export_bundle.py --format dsh --output /private/tmp/bookmark-research-dsh
294
- ```
295
-
296
- `--output` 必须是新目录或空目录。已存在的非空目录、文件及 symlink 会被拒绝;导出先在临时目录组装,再发布到输出路径,不向已有内容合并文件。要重新导出,请选择另一个新目录,或自行归档旧产物后使用空目录。
7
+ | Codex | 原生插件 manifest、Skill、stdio MCP | 使用会话实际提供的子代理;`hosts/codex/delegate.md` 与 `prepare.py` 仅辅助完整审计 |
8
+ | Claude Code | 原生插件 manifest、Skill、stdio MCP、研究命令 | 使用实际可见的 Agent/Task;分组工作流需宿主启用 |
9
+ | DeepSeek Harness | npm 包的 `dsh.bundle.patch`、原生 Skill provider、MCP client | 当前 profile 提供 subagent/workflow;工具名采用宿主实际映射 |
297
10
 
298
- 导出范围仅为共享 `src/`、`config/`、`skills/` 及按格式生成的 manifest/README。导出器过滤数据库、常见缓存、隐藏文件、测试与构建产物,拒绝源目录中的可导出 symlink;四种跨客户端包均排除 `agents/openai.yaml` 这一 Codex 显示元数据。现有数据库、网页缓存和运行时 API key 不打包,也不会安装客户端或更改其配置。
11
+ MCP 默认命令为 `python3 <plugin-root>/src/cli.py serve`。数据库和存储位于插件与画布包外。多宿主共库时须显式共享相同数据目录和配置;插件同名不代表共享存储。Codex 的自定义环境变量须由 MCP 注册转发,DSH 由插件启动配置传递。
299
12
 
300
- 本地验证命令:
13
+ 高级 MCP 工具需要 `tool_scope_preset:"deep"` 或显式白名单。CLI 工作流桥接只为本次高级子进程启用完整目录,保留显式范围,不改变保存的日常预设。所有子代理须收到问题、范围、相关 Skill 和实际数据入口;上下文继承以宿主实际行为为准。
301
14
 
302
- ```sh
303
- python3 -B -m unittest discover -s tests -p test_export_bundle.py -v
304
- ```
15
+ 分组工作流只有在用户要求完整清单和覆盖审计时使用,见[宿主工作流](../skills/bookmark-research/references/host-workflows.md)。普通调研按主 Skill 的上下文、检索、阅读、综合、Wiki 存储流程执行。
305
16
 
306
- 测试检查五种入口文件的形状,在移除源 fixture 后从独立工作目录运行导出 CLI,并验证 provider 配置、stdio MCP 初始化与工具发现、继承指定的数据目录、缓存过滤及不覆盖已有内容。四种跨客户端导出排除 Codex 显示元数据,Codex 导出保留它。它验证的是导出产物与共享运行时,不能替代 Pi/DSH/Claude 客户端的实际加载测试。
17
+ 打包检查、协议测试、真实 stdio MCP 调用和三宿主模型的端到端研究属于不同验证层级。离线测试和导出成功不能证明原生代理或付费 API 执行成功。历史验证记录与旧版配置说明可从 Git 历史查阅;当前接口和步骤以本项目现有文档为准。