✨ TPC Server ✨

TPC Server

用于 AI 与人类协作的 Node.js/Express API，初期使用 JSON 文件存储想法和计划。

安装与使用

1. 安装依赖：npm install
2. 启动服务：node server.js
3. 服务运行于 http://localhost:3001

更新日志

详细的版本说明请参阅 CHANGELOG.md。

测试

运行 npm test（或 npm run test:unit）以执行 Jest API/集成测试。 运行 npm run test:e2e 以执行 Playwright UI 测试。 运行 npm run smoke:mcp 以确定性验证 MCP 计划/想法生命周期。

生产环境安全

生产环境默认禁用 /tpc.db 下载。 如需明确允许下载，请设置 EXPOSE_TPC_DB=true。

运维端点

• GET /health 返回基本存活状态信息。
• GET /ready 返回就绪状态信息和数据库路径。

数据契约（REST + MCP）

• ID：计划/想法使用 SQLite 自动递增整数 ID。
• 时间戳：
  • thoughts.timestamp、plans.timestamp = ISO8601 字符串。
  • plans.created_at、plans.last_modified_at = 纪元毫秒数。
• 标签：数据库列中以 JSON 编码的字符串数组。

项目结构

• server.js：模块化结构的主要 Express 服务（db/、routes/、middleware/）。
• mcp-server.js：面向 AI 客户端的 MCP 服务（stdio 传输）。运行 npm run mcp。
• data/tpc.db：用于持久存储想法和计划的 SQLite 数据库。
• tests/：测试文件（Jest 单元测试、MCP 测试）。
• public/：静态单页 UI。

使用示例

REST API

• 获取所有想法：curl http://localhost:3001/thoughts
• 获取所有计划：curl http://localhost:3001/plans
• 创建想法：curl -X POST http://localhost:3001/thoughts -H "Content-Type: application/json" -d '{"content": "My thought"}'
• 创建计划：curl -X POST http://localhost:3001/plans -H "Content-Type: application/json" -d '{"title": "My Plan", "description": "Plan details"}'
• 更新计划状态：curl -X PATCH http://localhost:3001/plans/1 -H "Content-Type: application/json" -d '{"status": "in_progress"}'
• 搜索计划/想法：curl "http://localhost:3001/search?q=AI&type=plans&tags=urgent&limit=5"
• 为计划添加标签：curl -X PATCH http://localhost:3001/plans/1/tags -H "Content-Type: application/json" -d '{"tag": "ai"}'（追加）或 {"tags": ["ai", "urgent"]}（替换）
• 按标签筛选计划：curl "http://localhost:3001/plans?tags=ai,urgent"
• 查看 UI：启动服务后，访问 http://localhost:3001/index.html。

MCP 服务

• 启动 MCP 服务：npm run mcp
• 通过 stdio 连接 — 将 MCP 客户端配置为使用此服务
• 可用工具：list_plans、get_plan、create_plan、update_plan、list_thoughts、create_thought、search_thoughts、get_context
• 可用资源：tpc://plans、tpc://thoughts、tpc://context

功能

• MCP 服务：为 AI 客户端完整实现 MCP 协议。运行 npm run mcp（stdio 传输）。
• 模块化服务架构：按 db/、routes/ 和 middleware/ 组织，便于维护 API。
• SQLite 持久化：使用单个 data/tpc.db 存储想法和计划，并支持幂等架构迁移。
• 全面的测试：使用 Jest 进行单元测试（端点、验证、集成），使用 Playwright 进行 E2E UI 测试（渲染、交互）。
• 专注 AI 协作：/context 等端点聚合数据以供 Agent 记忆使用；支持带审核标记的人类编辑。
• 富文本支持：计划描述支持 Markdown 格式（粗体、列表等），并使用 marked.js 在 UI 中显示。
• 搜索与整理：全文搜索 API（/search?q=），支持类型/标签/数量限制筛选；UI 支持搜索输入和基于标签的筛选/编辑。
• 标签系统：通过 API/UI 为计划/想法添加、编辑和筛选标签，便于分类（例如，['ai', 'urgent']）。

v2.7 - 搜索与整理

已实现的功能

• 全文搜索端点（GET /search?q=<query>），支持可选参数 ?type=plans|thoughts、?tags=tag1,tag2、?limit=N，以获取目标结果。
• 标签系统：在 plans/thoughts 表中添加 tags 列（JSON 数组）；通过 POST/PUT/PATCH /plans/:id/tags（以及 thoughts 对应端点）进行管理。
• 标签筛选：列表端点（/plans、/thoughts、/search）支持 ?tags=ai,urgent（AND 逻辑）。
• 增强 /context，支持使用 ?search=<query> 筛选聚合数据。
• UI：全局搜索输入框、详情页中的标签编辑，以及列表中的标签筛选下拉菜单。

使用方法

• API 搜索：curl "http://localhost:3001/search?q=collaboration&type=plans&tags=ai"
• 为计划添加标签：curl -X PATCH http://localhost:3001/plans/1/tags -H "Content-Type: application/json" -d '{"tags": ["ai", "urgent"]}'（替换标签）或 {"tag": "new"}（追加标签）。
• 按标签筛选：curl "http://localhost:3001/plans?tags=ai,urgent"
• UI：在搜索框中输入查询内容；在计划/想法视图中点击标签即可编辑或筛选。

重要变更

• 架构变更：在 plans/thoughts 表中新增 tags TEXT 列（默认值为 '[]'）；提供向后兼容的迁移，并回填数据。
• 新路由：/search，用于统一查询。
• 基于 v2.6 的 Markdown 支持和模块化结构构建。