内容
# 开源代码 Palantir
[](https://www.npmjs.com/package/@openontology/opencode-palantir)
[](https://www.npmjs.com/package/@openontology/opencode-palantir)
OpenCode 插件，提供：
- Palantir 公共文档工具，支持本地 Parquet 数据库
- Foundry MCP 启动助手（命令、代理和可选的自动启动）
NPM 包：https://www.npmjs.com/package/@openontology/opencode-palantir
## 支持的操作系统
- 支持：macOS、Linux
- Windows：不支持（WSL2 可能有效，但我们不调试 Windows 特定问题）
## 安装（OpenCode）
在 OpenCode 配置文件（`opencode.jsonc`）中添加插件：
```jsonc
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@openontology/opencode-palantir@^0.1.4"]
}
```
重启 OpenCode。
启用插件后，OpenCode 将自动注册：
- 工具：`get_doc_page`、`list_all_docs`
- 命令：`/refresh-docs`、`/refresh-docs-rescrape`、`/setup-palantir-mcp`、`/rescan-palantir-mcp-tools`
- 代理：`foundry-librarian`、`foundry`
### 版本：如何获取最新版本
优先使用**固定版本**或**版本号范围**安装（例如 `@^0.1.4`），并有意更新。
避免在配置文件中使用 `@latest`：
- 它可能会使启动变慢（npm 解析/启动时安装）
- 它使行为不确定
- 根据缓存，您可能不会获得预期的升级行为
要查找最新版本和更改日志：
- NPM 版本：https://www.npmjs.com/package/@openontology/opencode-palantir
- GitHub 版本：https://github.com/anand-testcompare/opencode-palantir/releases
- 仓库更改日志：`CHANGELOG.md`
### （可选）按项目安装
在项目仓库中，将插件作为依赖项添加到 `.opencode/` 中（将插件依赖项与应用程序依赖项分开）：
```bash
mkdir -p .opencode
cat > .opencode/package.json <<'EOF'
{
"dependencies": {
"@openontology/opencode-palantir": "^0.1.4"
}
}
EOF
(cd .opencode && bun install)
```
然后在 `.opencode/plugins/` 中创建一个小包装文件：
```bash
mkdir -p .opencode/plugins
cat > .opencode/plugins/opencode-palantir.js <<'EOF'
import plugin from '@openontology/opencode-palantir';
export default plugin;
EOF
```
OpenCode 在启动时会自动加载 `.opencode/plugins/` 中的 `.js`/`.ts` 文件。
## 环境变量（Foundry MCP）
此插件从不将 Foundry 环境值写入磁盘。在 `opencode.jsonc` 中，`FOUNDRY_URL` 和 `FOUNDRY_TOKEN` 被引用为 `{env:FOUNDRY_URL}` 和 `{env:FOUNDRY_TOKEN}`。
### 变量
- `FOUNDRY_URL`
- Foundry 基本 URL（用于自动启动、`/setup-palantir-mcp` 和 `/rescan-palantir-mcp-tools`）
- 示例：`https://YOUR-STACK.palantirfoundry.com`
- `FOUNDRY_TOKEN`
- Foundry token，用于 `palantir-mcp` 进行工具发现
- 必须导出（而不仅仅是在 shell 中设置）
### 推荐设置（zsh，macOS/Linux）
使用现有的 shell 机密文件。例如，如果您已经从 `~/.zshrc` 导入 `~/.shell_secrets`，请添加：
```zsh
export FOUNDRY_URL='https://YOUR-STACK.palantirfoundry.com'
export FOUNDRY_TOKEN='YOUR_TOKEN'
```
锁定它：
```bash
chmod 600 ~/.shell_secrets
```
确保 `~/.zshrc` 导入它：
```zsh
if [ -f "$HOME/.shell_secrets" ]; then
source "$HOME/.shell_secrets"
fi
```
如果您仍然看到“token not exported”错误，请验证 `echo $FOUNDRY_TOKEN` 打印一个值，并且它在启动 OpenCode 的环境中已导出。
## 文档工具（Palantir 公共文档）
文档数据库是一个本地文件：
- `data/docs.parquet`（在您的仓库根目录中）
### 首次运行行为
在启动和工具使用时，插件会自动确保 `data/docs.parquet` 存在，使用预构建的快照（下载/复制）。在大多数仓库中，文档工具应该在无需手动设置的情况下工作。
### 刷新命令
- `/refresh-docs`（推荐）
- 从预构建的快照强制刷新（无实时重刮）
- `/refresh-docs-rescrape`（不安全/实验性备用）
- 实时刮取 palantir.com 文档并重建 `data/docs.parquet`
- 仅在快照下载/复制被阻止时使用
### 工具
- `get_doc_page`
- 按 URL 检索文档页面，或按查询模糊匹配
- `list_all_docs`
- 列出文档并分页，可选查询/范围过滤
## Foundry MCP 助手
此插件在启动时自动注册 Foundry 命令和代理（基于配置）。
### 自动启动（无需命令）
如果您设置了 `FOUNDRY_TOKEN` 和 `FOUNDRY_URL`，插件将自动且幂等地修补仓库根目录 `opencode.jsonc` 以初始化：
- `mcp.palantir-mcp` 本地服务器配置
- 全局工具拒绝：`tools.palantir-mcp_* = false`
- 每个代理的允许/拒绝切换在 `foundry-librarian` 和 `foundry` 下
### 引导设置和维护
- `/setup-palantir-mcp`
- 创建/修补仓库根目录 `opencode.jsonc`
- 添加 `mcp.palantir-mcp`（如果丢失）作为本地 `npx palantir-mcp --foundry-api-url ...` 服务器，由 `{env:FOUNDRY_URL}` 支持
- 强制全局拒绝：`tools.palantir-mcp_* = false`
- 创建 `foundry-librarian` 和 `foundry` 代理
- 发现 `palantir-mcp` 工具并在每个代理下编写显式 `true/false` 切换
- `/rescan-palantir-mcp-tools`
- 重新发现 `palantir-mcp` 工具列表并添加缺少的显式切换
- 从不覆盖现有的 `palantir-mcp_*` 切换
### 关于 palantir-mcp 版本（重要）
生成的 MCP 服务器默认使用 `npx -y palantir-mcp ...`。
注意：
- 首次运行可能很慢（npx 可能需要下载/安装）。
- `@latest` / 未固定的安装不确定。
建议：一旦您设置完成，请在 `opencode.jsonc` 中固定版本号：
```jsonc
{
"mcp": {
"palantir-mcp": {
"type": "local",
"command": [
"node",
"-e",
"const { spawn } = require('node:child_process'); const raw = (process.env.FOUNDRY_URL || '').trim(); const withScheme = /^https?:\\/\\//i.test(raw) ? raw : `https://${raw}`; const url = new URL(withScheme); const foundryUrl = `${url.protocol}//${url.host}`; const command = process.platform === 'win32' ? 'npx.cmd' : 'npx'; const child = spawn(command, ['-y', 'palantir-mcp@<version>', '--foundry-api-url', foundryUrl], { stdio: 'inherit' }); child.on('exit', (code) => process.exit(code ?? 1));"
],
"environment": {
"FOUNDRY_URL": "{env:FOUNDRY_URL}",
"FOUNDRY_TOKEN": "{env:FOUNDRY_TOKEN}"
}
}
}
}
```
## 开发（此仓库）
### 设置
```bash
mise run setup
```
### 常见任务
- 构建：`mise run build`
- 测试：`mise run test`
- Lint：`mise run lint`
- 类型检查：`mise run typecheck`
- 格式化：`mise run format`
### 烟雾测试构建产物
```bash
mise run smoke
```
### 获取文档 parquet（本地开发）
获取所有 Palantir 文档到 `data/docs.parquet`（~2 分钟，~17MB 文件）：
```bash
bun run src/docs/fetch-cli.ts
```
### Parquet 架构（本地开发）
Parquet 文件包含一个行组，包含以下列：
| 列名 | 类型 | 描述 |
| ------------ | ------- | --------------------------- |
| `url` | 字符串 | 页面 URL 路径（例如 `/foundry/...`） |
| `title` | 字符串 | 页面标题 |
| `content` | 字符串 |完整页面内容（Markdown） |
| `word_count` | 整数 | 内容字数 |
| `meta` | 字符串 | JSON 编码的元数据 |
| `fetched_at` | 字符串 | 获取的 ISO 8601 时间戳 |
示例（Bun）：
```typescript
import { parquetReadObjects } from 'hyparquet';
const file = await Bun.file('data/docs.parquet').arrayBuffer();
// 列出所有页面（仅 url + title）
const pages = await parquetReadObjects({ file, columns: ['url', 'title'] });
console.log(`${pages.length} pages`);
```
## 版本说明
对于维护人员，请参阅 `RELEASING.md`。
## 作者
Anand Pant <anand@shpit.dev>
