智能体能做什么¶

通过 MCP 服务器，AI 智能体（AI agent）几乎可以完成你在 Specivo 界面里能做的大部分操作。服务器提供约 40 个工具，全部以 specivo_ 为前缀。你很少需要直接按名字调用它们：只要描述想做什么，客户端就会选出合适的工具。本页按领域对这些工具分组，让你对能做的事有个整体印象。

按领域划分的工具目录¶

领域	智能体能做什么
工作项与评论	列出工作项，筛选方式与工作项列表相同：状态、负责人（登录名、`me` 或 `none`）、标签、版本（版本名或 `none`）、冲刺、父工作项和元数据值；读取、创建和更新工作项；编辑描述和核心字段；设置或更改工作项的父工作项并列出其子工作项；把工作项移动到另一个项目；添加评论并读取评论历史，或读取完整的变更历史，其中包含变更所涉及的状态、人员和版本的名称。
搜索	使用 Specivo 的混合搜索（关键词 + 语义）在工作项、维基等内容中搜索。
维基	列出、读取、创建、编辑维基页面并向页面追加内容，支持按章节读取和编辑，以及查看历史记录和恢复。
元数据与架构	读取和设置工作项元数据的值，并列出可用的元数据架构。
标签	列出项目的标签，为工作项和维基页面打标签（创建时也可以）；拥有管理项目权限时，还能创建、重命名、修改颜色和删除标签。
关联	用带类型的关联（关联到、阻塞、重复于等）链接工作项，也能移除关联。
链接	沿着工作项、维基页面和评论之间的链接查看：`specivo_show_issue` 和 `specivo_read_wiki` 会列出一个条目链接到了什么，以及哪些内容链接到它（反向链接）；`specivo_get_links` 以 JSON 返回周边的链接网络，最多两跳，可按类型筛选。智能体只能看到密钥有权打开的条目之间的链接。
开发	`specivo_issue_development(issue_ref, kinds=[...], limit, offset)` 以 JSON 返回工作项的开发动态，与 REST API 返回的文档相同：提交、拉取请求、代码评审、CI 运行、部署（含环境类型）和发布，并附带摘要和分页时间线。`specivo_show_issue` 会用一行 `Development:` 概括这些信息。智能体只能看到密钥有权打开的工作项的开发动态。
版本	列出和管理版本（里程碑/发布版本），并查看每个版本包含哪些工作项。
冲刺	列出冲刺，查看冲刺中的工作项，并管理计划、开始、完成的生命周期。
重复任务	创建、列出、更新和删除重复模板；跳过某一次计划内的重复项；预览即将到来的重复项。模板的主题和描述支持日期宏（`{{month}}`、`{{weekday}}` 等），会按模板的时区在每个重复项中展开。
时间	为工作项或项目记录工时并指定活动类型，或使用自己的计时器：在工作项上启动、查看、停止以记录工时，或者直接丢弃。
AI 使用	`specivo_log_ai_usage` 记录 AI 工具在某个工作项或项目上消耗的 token；`specivo_ai_usage` 用于列出、读取、更正、排除和重新纳入 AI 使用记录。智能体自己的每条记录都标注了来源的智能体会话，`session_id` 可以列出某个会话在所有项目中的记录，因此智能体可以核对自己的使用量记到了哪里。`specivo_ai_usage_report` 像 AI 支出报表一样汇总支出；传入 `issue_ref` 时只统计一个工作项，`include_sub_issues=true` 则把它下面的工作项也算进去。智能体看不到自己的 token 计数，所以数字必须来自 hook、上报工具或 AI 工具自己的 `/cost` 输出，绝不能靠估算。不指定工作项或项目时，记录会归到智能体会话正在处理的工作项（见智能体会话），否则保持未分配。
AI 订阅	`specivo_ai_subscriptions` 用于列出、添加、更正、结束和删除智能体所用密钥持有人的 AI 订阅，例如根据账单一次录入多个套餐周期。它会对同一套餐各周期之间的重叠和空缺发出警告，并拒绝项目受限的密钥和服务账户。
环境信息	`specivo_whoami`（密钥对应哪个账户）、`specivo_list_lookups`（追踪器/状态/优先级 ID）和 `specivo_setup_guide`（配置帮助）。

先调用环境信息工具

行为规范的智能体会在创建或更新工作项之前先调用 specivo_list_lookups 了解项目的追踪器、状态和优先级 ID，并调用 specivo_whoami 确认自己以哪个账户在操作。接入新智能体时，先让它运行这两个工具。

读与写¶

工具大约一半是读（列出、查看、搜索、读取维基），一半是写（创建工作项、添加评论、更新状态、记录工时或 AI 使用、编辑维基）。这个区分与权限直接相关：

读操作返回密钥所属账户有权看到的一切。
写操作每次都会根据该账户在项目中的角色校验。账户在界面里做不了的修改，智能体通过 MCP 同样做不了。

正因如此，使用具备合适角色的专用服务账户才是限定智能体权限的安全做法：只需查看的地方给只读角色，需要操作的地方才给写入角色。

每一次写入都有审计记录¶

智能体的每一次 MCP 工具调用，无论读写，都会记录到安全审计日志中，标记为 source=mcp，并记下执行的账户、时间和客户端地址。管理员可以在 管理 → 审计日志 中查看智能体到底做了什么。工作项的修改也会和真人修改一样出现在常规的工作项历史和评论记录中。智能体的任何操作都不会被隐藏。

审计日志只覆盖 MCP。智能体用密钥调用 REST API 时，会被当作普通用户处理：它对工作项和维基的修改记录在各自的历史里，而不在审计日志中。

智能体会话¶

Specivo 还会把每个密钥的调用归入智能体会话：间隔不到 30 分钟的调用（由 AGENT_SESSION_TIMEOUT 控制，单位为秒）属于同一个会话。会话记录以下信息：

发起调用的客户端：使用它连接时宣告的名称和版本（例如 claude-code 和 2.1.0），否则取其 User-Agent 请求头中的第一个产品名；
智能体正在处理的工作项：通过 MCP，指它最近一次创建时就处于进行中状态（活动组中的任意状态）或指派给自己账户的工作项、移入此类状态的工作项、指派给自己账户的工作项、处于进行中且指派给自己账户时被它更新过的工作项（因此智能体恢复处理自己的工作项时会再次标记，即使什么都没改），或者在其上启动了计时器的工作项。以最新的一个为准。只有密钥账户能看到的工作项才会被记录。

会话中的工作项只是把 AI 使用归属到工作项时的一个提示（specivo_log_ai_usage 不带工作项或项目时会用到它，前提是该账户有权在那里记录使用量）；它不授予任何权限。提示词和对话内容一概不会存储。

文件上传走 REST API¶

MCP 工具只处理文本：可以读写工作项、评论和维基文本，但无法上传二进制文件。要添加附件，请用 curl 调用 Specivo 的 REST API，复用同一个 spv_… 密钥：

curl -X POST https://your-specivo-host/api/v1/attachments/ \
  -H "Authorization: Bearer spv_your_api_key_here" \
  -F "file=@./diagram.png" \
  -F "container_type=Issue" \
  -F "container_id=123"

container_type 为 Issue、WikiPage 或 Journal（评论），container_id 是对应的数字 id。添加文件需要拥有修改附件所属对象的权限：

附加到	所需权限
工作项	编辑工作项或添加评论；对于账户自己创建的工作项，创建工作项也可以
维基页面	管理维基页面
评论	编辑任意评论；对于账户自己的评论，编辑自己的评论也可以

工作项上的文件会记录到工作项历史中（“已添加文件 diagram.png”）。要把它和所属的编辑或评论记在同一条目里，加上 -F "journal_id=…"：journal_id 来自 PATCH /api/v1/issues/{ref}/ 的返回值（编辑没有产生任何变化时为 null），或者来自 POST /api/v1/issues/{ref}/journals/ 返回的评论 id。每次上传的响应也带有 journal_id，所以同一批的后续文件可以加入同一条目。

REST API 基础

REST 认证只支持 Authorization: Bearer spv_… 请求头，而且每个 API URL 都要以斜杠结尾。连接 MCP 客户端的那个密钥在这里同样可用。