内容
# 项目首页
为 Codex 项目行添加一个仅悬停可见的主页图标。点击它或在项目线程中按 `Cmd+Shift+H`，会为该项目打开项目首页视图。
V1 包括一个按项目划分的看板，用于类似 Linear 的问题管理：
- 列：待办事项、待处理、进行中、评审中、已完成
- 从看板或列标题创建问题
- 在列之间拖动问题
- 右键单击或使用问题省略号菜单编辑、移动或删除
- 问题存储在 JSON 数据库中，按项目路径索引
该微调还包括 `mcp-server.js`，一个由相同问题存储支持的标准输入输出 MCP 服务器。工具：
- `project_home_help` — 自我文档；传递 `tool: "<name>"` 以获取聚焦帮助
- `project_home_columns`
- `project_home_list_issues`
- `project_home_search_issues`
- `project_home_get_issue`
- `project_home_create_issue`
- `project_home_update_issue`
- `project_home_add_comment`
- `project_home_move_issue`
- `project_home_delete_issue`
- `project_home_linear_sync`
不熟悉服务器的代理可以调用 `project_home_help`（无参数）来发现可用的工具、状态/优先级枚举和 `author: "Codex"` 约定。
问题 ID 使用从项目文件夹名称的前 2-3 个字母数字字符派生的每个项目前缀（例如，`…/tweaks/` 下的问题变为 `TWE-1`、`TWE-2`，...）。现有的 `PH-*` ID 将被保留。
评论支持 `author` 字段。MCP 在 `project_home_add_comment` (`author`) 和 `project_home_create_issue` / `project_home_update_issue` (`newCommentAuthor`) 上公开它。 当存在时，看板渲染 `author · timestamp`。代理在留下注释时应传递 `author: "Codex"`。
## 在 Codex 中注册 MCP
Codex++ 目前不将 `manifest.json#mcp` 转发到 Codex 的自己的 MCP 运行时，因此代理在您手动注册服务器之前将看不到这些工具。 将以下块添加到 `~/.codex/config.toml` 并重启 Codex：
```toml
[mcp_servers.project-home]
command = "node"
args = ["/ABSOLUTE/PATH/TO/codex-plusplus/tweaks/co.bennett.project-home/mcp-server.js"]
```
在 macOS 上，绝对路径通常为 `/Users/<you>/Library/Application Support/codex-plusplus/tweaks/co.bennett.project-home/mcp-server.js`。
要验证，请询问 Codex “你能看到哪些 MCP？” — `project-home` 应该出现，并带有 `project_home_*` 工具。 当上游 Codex++ 自动注册 MCP 条目来自微调清单时，可以取消此手动步骤。
## Linear 同步
`project_home_linear_sync` 通过 Linear 的 GraphQL API 将 Project Home 问题推送到 Linear。 设置：
```bash
export LINEAR_API_KEY="lin_api_..."
export LINEAR_TEAM_ID="<team uuid>" # 可选；省略时使用第一个可访问的团队
```
然后使用 `projectPath` 调用 MCP 工具。传递 `issueId` 以同步一个问题，或省略它以同步项目中的所有问题。传递 `dryRun: true` 以预览创建/更新而不写入 Linear 或本地问题元数据。
成功写入后，本地问题存储 `linear.id`、`linear.identifier`、`linear.url` 和 `linear.syncedAt`。后续同步更新该 Linear 问题，而不是创建重复问题。
您还可以打开 Codex++ 设置 > 项目首页并保存每个项目的 Linear 同步配置。设置页面存储所需的 `apiKey` 以及可选的 `teamId`、`apiUrl` 和默认同步模式，在 MCP 服务器使用的同一个按项目划分的 Project Home 数据库中。它包括一个链接到 Linear API 设置的链接，用于创建个人 API 密钥和选择团队访问权限。
> 注意：Codex 的 Rust MCP 传输在标准输入输出上使用换行分隔的 JSON（NDJSON），而不是 LSP 样式的 `Content-Length` 分帧。`mcp-server.js` 按照约定每行写入一个 JSON 消息。
## 通过 Codex 进行一次性安装
不想手动编辑 TOML？ 打开 Codex 聊天窗口并粘贴下面的块。 Codex 将定位 MCP 服务器，将 `[mcp_servers.project-home]` 条目添加到 `~/.codex/config.toml`（幂等），验证服务器启动，并告诉您重启 Codex。
````
为我安装 project-home MCP。步骤如下：
1. 解析 `mcp-server.js` 的绝对路径以备用于 project-home 微调。在 macOS 上，这是：
`/Users/$USER/Library/Application Support/codex-plusplus/tweaks/co.bennett.project-home/mcp-server.js`
在 Linux 上，这是：`${XDG_DATA_HOME:-$HOME/.local/share}/codex-plusplus/tweaks/co.bennett.project-home/mcp-server.js`
在继续之前，请使用 `ls -la` 确认文件存在。
2. 读取 `~/.codex/config.toml`。如果已经存在具有正确 `command` 和 `args` 的 `[mcp_servers.project-home]` 块，则不执行任何操作并跳至步骤 4。否则，备份文件到
`~/.codex/config.toml.bak.$(date +%s)` 并追加：
```toml
[mcp_servers.project-home]
command = "node"
args = ["<绝对路径 from 步骤 1>"]
```
3. 运行 `codex mcp list`（路径：macOS 上的 `/Applications/Codex.app/Contents/Resources/codex`）并
确认 `project-home` 显示为 `enabled`。
4. 通过直接运行服务器并使用换行分隔的 JSON（NDJSON）发送 `initialize` 请求来测试服务器。使用以下示例一行程序进行测试：
```bash
node -e '
const {spawn}=require("child_process");
const c=spawn("node",["<path>"]);
c.stdin.write(JSON.stringify({jsonrpc:"2.0",id:1,method:"initialize",params:{protocolVersion:"2024-11-05"}})+"\n");
let out=""; c.stdout.on("data",d=>{out+=d; if(out.includes("project-home")){console.log("OK"); c.kill(); process.exit(0)}});
setTimeout(()=>{console.log("FAIL",out); c.kill(); process.exit(1)},2000);
'
```
5. 反馈以下信息：您使用的路径，配置是否已经存在或新添加，备份文件名（如果有），以及一行确认 `initialize` 返回 `OK`。 然后告诉我完全退出并重新打开 Codex（macOS 上为 Cmd+Q），以便拾取新的 MCP。
如果出现任何问题，请停止并显示确切的错误信息，而不是猜测。 请勿修改 `config.toml` 的其他部分。
````
重启后，询问 Codex “你能看到哪些 MCP？” — `project_home` 应该出现在列表中。
## 测试
```bash
npm test
```
运行 `tests/mcp.test.js`，一个端到端的烟雾测试，启动 `mcp-server.js`，驱动每个工具进行标准输入输出（NDJSON JSON-RPC），并断言 MCP 问题和 Linear 同步路径。 测试使用 `CODEX_PLUSPLUS_DATA_DIR` 指向临时目录，因此永远不会触及您的问题数据库。 无外部依赖 — Node >= 18 就足够了。
