常见工作流¶

客户端连接之后，你只需向 AI 智能体（AI agent）描述想要的结果，由它自行选择合适的工具。下面是一些常见模式，以“你可以让智能体做什么”的形式呈现。这些示例假定智能体的账户在项目中拥有合适的角色，详见 API 密钥与作用域。

先收集上下文，再动手¶

最有用的习惯是让智能体在行动前先了解情况。一个好的请求会把以下几步串起来：

1. 搜索 相关主题，范围覆盖工作项（Issue）和维基（Wiki）。Specivo 的混合搜索按语义匹配，而不只是匹配关键词。
2. 读取工作项：打开看起来相关的那一个，获取完整的描述、字段和评论。
3. 读取维基页面：查看它引用的页面，了解背景或约定。

“找出与登录流程相关的未关闭工作项，读取最相关的那个，并在提出任何建议之前查看维基里我们的认证约定。”

这样智能体依据的是项目的真实状态，而不是猜测。

创建工作项¶

让智能体把它（或你）发现的工作记录下来。它会先查询项目的追踪器（Tracker）和优先级，然后用清晰的主题和 Markdown 描述创建工作项。

“在 ACME 中创建一个 Bug：报表页的导出按钮点击后没有反应。优先级设为 High，并指派给我。”

新建的工作项会得到类似 ACME-42 的编号，后续请求中可以直接引用。

创建工作项的工具还接受一个 元数据（metadata）映射，智能体可以在同一次调用中设置自定义的元数据字段，而不必先创建再更新。例如故事点估算或初始分支，都可以在创建时一并写入。

把工作项移到其他项目¶

如果工作项建在了错误的项目里，智能体可以把它移走，而且不会丢失任何内容。

“把 ACME-42 移到 HOME 项目，并备注它属于 home 团队。”

工作项会保留历史记录、评论、关联、附件、关注者、工时记录和元数据，并在目标项目中获得新编号；旧编号仍然有效。只有独立的工作项才能移动，请先解除与父工作项或子工作项的关系。完整规则见把工作项移到其他项目。

标记已解决并记录工时¶

一项工作完成后，智能体可以一次性更新状态并记录投入的工时。

“把 ACME-42 标记为 Resolved，完成百分比设为 100%，并记录 2 小时的 Development 工时，附上关于修复的说明。”

把状态设为 Resolved（已解决）会使工作项进入已完成类别；记录工时则把工时记在该工作项上，并带有活动类型（默认为 Development，即开发）。

完成后追加提交元数据¶

把代码和工作项关联起来，最干净的方式是用元数据，而不是在描述里写自由文本。提交代码后，让智能体把提交哈希和分支追加到工作项的数组型元数据字段中（Software Development（软件开发）架构提供了 commits、branches 和 pull_requests 字段）。

“在 ACME-42 上，把提交哈希 a1b2c3d 追加到 commits 元数据，把 fix/export-button 追加到 branches。”

由于这些是数组字段，追加只会往列表里添加，不会覆盖已有条目，元数据因此始终是“哪些内容已发布”的唯一可信来源。参见设置元数据值。

逐步编写维基页面¶

智能体可以在一次对话中起草并不断扩充一个维基页面。先创建页面，再随着内容的完善逐段添加。

“创建一个标题为‘Deployment Runbook’的维基页面，先写概览；等我确认回滚步骤后，再追加一节回滚步骤。”

标题中用 空格 分隔单词（slug 会自动生成），并让智能体追加或编辑特定章节，而不是重写整页。每次编辑都有版本记录，你随时可以查看历史记录或回退。