Semantic Hub
Quick summary
Collaborative task and project management for Human + AI Agent teamwork. Organize your work on visual boards (Kanban) with drag-and-drop columns (like To Do, Doing, Done), view tasks in a table layout, or plan on a calendar — whatever works best for you. AI agents interact with shared boards via REST API — they can list boards, create and update tasks, add comments, upload files and attach them to cards or comments, filter and search work items, and view activity history. Agents operate under role-based access control as scoped contributor-level team members.
Board owners create boards in the dashboard, then generate per-agent API keys and grant agents access to specific boards. Agents cannot delete cards, manage settings, or modify members.
Authentication
INLINECODE0 is always required. This is the agent's API key generated by the board owner in the dashboard at https://dashboard.simplysemantics.com/hub. It authenticates the agent's requests and is scoped to specific boards only — it does not grant access to any board the agent has not been explicitly granted access to. The board owner can revoke and rotate the key at any time.
Privacy & data handling
- - What data is sent: Only card data (titles, descriptions, comments, status changes) and board metadata. No user PII, agent secrets, source code, or environment variables are ever transmitted.
- What data is NOT sent: No user credentials, private keys, environment variables, file contents, agent configuration, or personal information of any kind.
- Data retention: Board and card data is stored in your account, isolated per account and per board.
- API key handling: Your
SEMANTIC_HUB_API_KEY is used solely for request authentication. It is never logged in plaintext, shared, or transmitted to third parties. - No cross-service data sharing: Your Semantic Hub data is not shared with other Simply Semantics services.
- Logging: API requests are logged for rate-limiting and abuse prevention only. Logs contain API key hash (not the key), endpoint, and timestamp. Retained for 30 days.
When to use this skill (activation triggers)
Activate Semantic Hub when the user or agent:
- - Needs to create, update, or manage tasks/cards/meetings on a board.
- Wants to check the status of cards, filter by priority/status/assignee, or list tasks.
- Asks to "add a card", "create a task", "create a meeting", "create an idea", "update the status", "move to done", "what's on my board", "what's on our agenda".
- Needs to add a comment or view comments on a card.
- Wants to upload a file or attach a file/URL to a card or comment.
- Asks to "attach this file", "upload a screenshot", "add this link to the card".
- Wants to see activity history for a card.
- Needs to list board members or check who is assigned to tasks.
- Wants to filter cards (e.g. "show me all high priority tasks", "what's assigned to me").
Do NOT use for:
- - Creating or deleting boards (admin-only, not available to agents).
- Managing board settings, columns, or card types (admin-only).
- Adding or removing team members (admin-only).
- Managing other agents or API keys (admin-only).
- Deleting cards (blocked for agents).
How to use (instructions for the agent)
1. List boards the agent has access to
GET INLINECODE2
Headers:
CODEBLOCK0
Response:
CODEBLOCK1
2. Get board details
GET INLINECODE3
Headers:
CODEBLOCK2
Response:
CODEBLOCK3
3. List cards on a board
GET INLINECODE4
Headers:
CODEBLOCK4
Response:
CODEBLOCK5
4. Filter and search cards
GET INLINECODE5
Headers:
CODEBLOCK6
Query parameters (all optional):
- -
priority — Critical, High, Medium, Low - INLINECODE7 — column name (e.g. "To Do", "Doing", "Done")
- INLINECODE8 — card type (e.g. "Task", "Idea", "Meeting")
- INLINECODE9 — email or "agent:AgentName"
- INLINECODE10 — "priority", "createdAt", "updatedAt", "title" (default: "createdAt")
Example:
CODEBLOCK7
5. Create a card
POST INLINECODE11
Headers:
CODEBLOCK8
Body:
CODEBLOCK9
Only title is required. All other fields have sensible defaults.
Response:
CODEBLOCK10
6. Update a card
PATCH INLINECODE13
Headers:
CODEBLOCK11
Body (send only the fields to update):
CODEBLOCK12
Response:
CODEBLOCK13
7. Add a comment to a card
POST INLINECODE14
Headers:
CODEBLOCK14
Body:
CODEBLOCK15
Response:
CODEBLOCK16
8. Get comments on a card
GET INLINECODE15
Headers:
CODEBLOCK17
Response:
CODEBLOCK18
9. Get card activity history
GET INLINECODE16
Headers:
CODEBLOCK19
Response:
CODEBLOCK20
10. Get card attachments
GET INLINECODE17
Headers:
CODEBLOCK21
Response:
CODEBLOCK22
11. Upload a file
Upload a file to get a hosted URL, then attach it to a card or comment. File uploads are subject to per-tier limits on file size and total upload count (URL-based attachments are not limited).
POST INLINECODE18
Headers:
CODEBLOCK23
Body (multipart form):
- -
file — the file to upload
Response:
CODEBLOCK24
Upload limits by tier:
- - Free: 2 MB per file, 10 uploads total
- Pro: 10 MB per file, 100 uploads total
- Enterprise: 50 MB per file, unlimited uploads
Errors:
- -
413 — File too large for your tier - INLINECODE21 — Upload count limit reached for your tier
12. Attach a file or URL to a card
Link an attachment to a card. Use the URL from the upload endpoint, or provide any external URL.
POST INLINECODE22
Headers:
CODEBLOCK25
Body:
CODEBLOCK26
INLINECODE23 and url are required. size is optional (bytes).
Response:
CODEBLOCK27
13. Attach a file or URL to a comment
Link an attachment to a comment. Attachments must be added at the same time as the comment — first create the comment, then attach.
POST INLINECODE26
Headers:
CODEBLOCK28
Body:
CODEBLOCK29
Response:
CODEBLOCK30
14. Get comment attachments
GET INLINECODE27
Headers:
CODEBLOCK31
Response:
CODEBLOCK32
15. List board members
GET INLINECODE28
Headers:
CODEBLOCK33
Response:
CODEBLOCK34
16. Edge cases
- - 401/403 → "Missing or invalid SEMANTICHUBAPI_KEY. Set the env var to use this skill."
- 403 with
upgrade_url → "Tier limit reached — upgrade your plan." - 404 → "Card or board not found, or agent does not have access."
- 413 → "File too large for your plan tier."
- 429 → "Upload limit reached for your plan tier."
- 500 → "Service temporarily unavailable. Try again shortly."
Output format
Present results clearly to the user:
CODEBLOCK35
CODEBLOCK36
Semantic Hub
快速摘要
面向人类与AI代理协作的协同任务与项目管理工具。通过拖拽式看板列（如待办、进行中、已完成）在可视化看板上组织工作，支持表格视图查看任务，或使用日历进行规划——任您选择最适合的方式。AI代理可通过REST API与共享看板交互：它们能列出看板、创建和更新任务、添加评论、上传文件并关联到卡片或评论、筛选和搜索工作项，以及查看活动历史。代理在基于角色的访问控制下运作，作为限定范围的贡献者级团队成员。
看板创建者在仪表盘中创建看板，然后为每个代理生成API密钥，并授予代理访问特定看板的权限。代理不能删除卡片、管理设置或修改成员。
身份认证
SEMANTICHUBAPI_KEY 始终必需。这是看板创建者在仪表盘（https://dashboard.simplysemantics.com/hub）中为代理生成的API密钥。它用于验证代理的请求，且仅限定于特定看板——不会授予代理访问未被明确授权看板的权限。看板创建者可随时撤销或轮换该密钥。
隐私与数据处理
- - 发送的数据：仅包含卡片数据（标题、描述、评论、状态变更）和看板元数据。绝不传输任何用户个人身份信息、代理密钥、源代码或环境变量。
- 不发送的数据：不发送任何用户凭证、私钥、环境变量、文件内容、代理配置或任何类型的个人信息。
- 数据保留：看板和卡片数据存储在您的账户中，按账户和看板隔离。
- API密钥处理：您的SEMANTICHUBAPI_KEY仅用于请求身份验证。绝不会以明文形式记录、共享或传输给第三方。
- 无跨服务数据共享：您的Semantic Hub数据不会与其他Simply Semantics服务共享。
- 日志记录：API请求仅用于速率限制和滥用预防。日志包含API密钥哈希（而非密钥本身）、端点和时间戳。保留30天。
何时使用此技能（激活触发器）
当用户或代理出现以下情况时，激活Semantic Hub：
- - 需要在看板上创建、更新或管理任务/卡片/会议。
- 想要检查卡片状态、按优先级/状态/负责人筛选，或列出任务。
- 要求添加卡片、创建任务、创建会议、创建想法、更新状态、移至已完成、我的看板上有什么、我们的议程上有什么。
- 需要在卡片上添加评论或查看评论。
- 想要上传文件或将文件/URL关联到卡片或评论。
- 要求关联此文件、上传截图、将此链接添加到卡片。
- 想要查看卡片的操作历史。
- 需要列出看板成员或检查谁被分配了任务。
- 想要筛选卡片（例如显示所有高优先级任务、分配给我的任务是什么）。
不要用于：
- - 创建或删除看板（仅限管理员，代理不可用）。
- 管理看板设置、列或卡片类型（仅限管理员）。
- 添加或移除团队成员（仅限管理员）。
- 管理其他代理或API密钥（仅限管理员）。
- 删除卡片（对代理已阻止）。
如何使用（代理操作指南）
1. 列出代理可访问的看板
GET https://dashboard.simplysemantics.com/hub/boards
请求头：
text
x-api-key: ${SEMANTICHUBAPI_KEY}
响应：
json
[
{
id: abc-123,
name: 冲刺看板,
description: 当前冲刺任务,
cardCount: 12,
columnCount: 3,
role: Agent
}
]
2. 获取看板详情
GET https://dashboard.simplysemantics.com/hub/boards/:boardId
请求头：
text
x-api-key: ${SEMANTICHUBAPI_KEY}
响应：
json
{
id: abc-123,
name: 冲刺看板,
columns: [
{ id: col-1, name: 待办, order: 0 },
{ id: col-2, name: 进行中, order: 1 },
{ id: col-3, name: 已完成, order: 2 }
],
cardTypes: [任务, 想法, 会议],
cards: [...],
members: [
{ email: user@example.com, role: Admin }
],
agents: [
{ name: MyAgent, id: agent-456 }
]
}
3. 列出看板上的卡片
GET https://dashboard.simplysemantics.com/hub/boards/:boardId/cards
请求头：
text
x-api-key: ${SEMANTICHUBAPI_KEY}
响应：
json
[
{
id: CARD-A1B2C3D4,
title: 修复登录错误,
type: 任务,
priority: 高,
status: 待办,
assignee: dev@example.com,
start_date: null,
end_date: null,
created_at: 2026-03-01T10:00:00.000Z
}
]
4. 筛选和搜索卡片
GET https://dashboard.simplysemantics.com/hub/boards/:boardId/cards/filter
请求头：
text
x-api-key: ${SEMANTICHUBAPI_KEY}
查询参数（均为可选）：
- - priority — 紧急、高、中、低
- status — 列名称（例如待办、进行中、已完成）
- type — 卡片类型（例如任务、想法、会议）
- assignee — 邮箱或agent:AgentName
- sortBy — priority、createdAt、updatedAt、title（默认：createdAt）
示例：
GET /hub/boards/abc-123/cards/filter?priority=高&status=待办&sortBy=priority
5. 创建卡片
POST https://dashboard.simplysemantics.com/hub/boards/:boardId/cards
请求头：
text
x-api-key: ${SEMANTICHUBAPI_KEY}
Content-Type: application/json
请求体：
json
{
title: 实现认证流程,
description: 添加OAuth2登录支持,
type: 任务,
priority: 高,
status: 待办,
assignee: agent:MyAgent,
start_date: 2026-03-03T09:00,
end_date: 2026-03-03T17:00
}
仅title为必填项。其他字段均有合理的默认值。
响应：
json
{
id: CARD-X9Y8Z7W6,
board_id: abc-123,
title: 实现认证流程,
type: 任务,
priority: 高,
status: 待办,
assignee: agent:MyAgent,
created_at: 2026-03-03T10:30:00.000Z
}
6. 更新卡片
PATCH https://dashboard.simplysemantics.com/hub/cards/:cardId
请求头：
text
x-api-key: ${SEMANTICHUBAPI_KEY}
Content-Type: application/json
请求体（仅发送需要更新的字段）：
json
{
status: 已完成,
priority: 低
}
响应：
json
{
id: CARD-X9Y8Z7W6,
title: 实现认证流程,
status: 已完成,
priority: 低,
updated_at: 2026-03-03T14:00:00.000Z
}
7. 在卡片上添加评论
POST https://dashboard.simplysemantics.com/hub/cards/:cardId/comments
请求头：
text
x-api-key: ${SEMANTICHUBAPI_KEY}
Content-Type: application/json
请求体：
json
{
text: 认证流程已实现并测试通过。移至已完成。
}
响应：
json
{
id: comment-789,
card_id: CARD-X9Y8Z7W6,
text: 认证流程已实现并测试通过。移至已完成。,
user_id: agent-456,
created_at: 2026-03-03T14:05:00.000Z
}
8. 获取卡片上的评论
