# 项目 API

让 project-scoped context 和 handoff records 与创建它们的 agent workflow 保持连接。

- Canonical: https://docs.xmemo.dev/zh/docs/api/projects
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: f87dd0befa0c74658bc8585d0e0cb06c2f4e66349349fea57dfb0ad50d4d972a
- Edition-Digest: 4d1059a14223392cd13ae815944505289b0448c29dd17eb413d988ff31354e60
- Source-Revision: sha256:4feaf3bfdc42a8d043acdcde2b2c2e4c2dd59e9077168e06d562745030d51c62

## Project boundaries and base contract

OpenAPI contract 在 /v1/projects/{project_id} 下暴露 project operations；已提交的 public data-plane contract 中没有顶层 POST /v1/projects operation。project_id 选择 project workspace，而 scope、bucket、team_id 和 path 仍是 authorization 与 filtering fields。使用 X-API-Key header 进行认证，并使用被授权访问所选 project/team 的 token。

- Context：POST /v1/projects/{project_id}/context。
- Todos：POST /v1/projects/{project_id}/todos；GET /v1/projects/{project_id}/todos。
- Todo transitions：POST /v1/projects/{project_id}/todos/{todo_id}/accept；POST /v1/projects/{project_id}/todos/{todo_id}/assign；POST /v1/projects/{project_id}/todos/{todo_id}/block；POST /v1/projects/{project_id}/todos/{todo_id}/unblock；POST /v1/projects/{project_id}/todos/{todo_id}/complete；POST /v1/projects/{project_id}/todos/{todo_id}/cancel。
- Decisions：POST /v1/projects/{project_id}/decisions；GET /v1/projects/{project_id}/decisions。
- Decision transitions：POST /v1/projects/{project_id}/decisions/{decision_id}/resolve；POST /v1/projects/{project_id}/decisions/{decision_id}/supersede；POST /v1/projects/{project_id}/decisions/{decision_id}/reopen。
- Maintenance：GET /v1/projects/{project_id}/maintenance/settings；PATCH /v1/projects/{project_id}/maintenance/settings；GET /v1/projects/{project_id}/maintenance；POST /v1/projects/{project_id}/maintenance/execute。

## Project context request and response schemas

POST /v1/projects/{project_id}/context 接受 ProjectContextRequest：bucket 默认 %，team_id 和 durable_query 可为 null，max_items 默认 100（1..1000），max_tokens 默认 8000（1..50000），include_durable_context 默认 true，recent_hours 默认 168（1..8760）。它返回 ProjectContextPackResponse，必需字段为 project_scope、assembled_at 和 budget，此外还有 project_state、agent_states、action_items、decisions、timeline、recent_memories、durable_context、governance_caveats、missing_domains、incomplete_domains 和 suggested_next_actions。

```http
POST /v1/projects/memory-os/context
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "bucket": "work",
  "max_items": 100,
  "max_tokens": 8000,
  "include_durable_context": true,
  "recent_hours": 168
}
```

## Project todos and decisions

Todo creation 接受 ProjectTodoCreateRequest，其中 content required，priority、assignee_agent_id、depends_on、due_at、source_memory_id、metadata、bucket（default work）、scope、path 和 team_id 可选；它返回 ProjectTodo。GET todos 接受可选的 status 和 team_id，并返回 ProjectTodo array。Decision creation 接受 ProjectDecisionCreateRequest，其中 context required，options、impact_level、proposed_by_agent_id、supersedes、source_memory_id、due_at、metadata、bucket（default work）、scope、path 和 team_id 可选；它返回 ProjectDecision。Decision listing 接受 status 和 team_id，并返回 array。

```http
POST /v1/projects/memory-os/todos
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "content": "Review the current API contract",
  "priority": "high",
  "bucket": "work"
}

POST /v1/projects/memory-os/decisions
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "context": "Choose the public REST reference scope",
  "options": ["memory-only", "full-openapi"]
}
```

## Todo and decision lifecycle operations

OpenAPI lifecycle operations 返回 ProjectTodo 或 ProjectDecision，supersede 除外，它返回 ProjectDecision array。ProjectTodo 要求 todo_id、project_id 和 content；其他声明的 fields 包括 status、priority、assignee_agent_id、accepted_by_agent_id、blocked_reason、depends_on、due_at、completed_at、completion_note、source_memory_id、created_at、updated_at、audit_trail 和 extra_metadata。ProjectDecision 要求 decision_id、project_id 和 content；其他声明的 fields 包括 title、decision、rationale、status、proposed_by_agent_id、resolved_by_agent_id、impact_level、supersedes、superseded_by、options、resolution、decision_context、source_memory_id、resolved_at、created_at、updated_at、audit_trail 和 extra_metadata。POST /v1/projects/{project_id}/decisions/{decision_id}/resolve 要求 {resolution: string}；POST /v1/projects/{project_id}/decisions/{decision_id}/supersede 要求 context，并接受 options、impact_level、proposed_by_agent_id 和 resolution_note；reopen 不需要 request body。Todo accept、unblock 和大多数 transitions 在 OpenAPI 中不需要 request body；assign 要求 {assignee_agent_id: string}，block 要求 {reason: string}，complete 接受 {note: string|null}，cancel 接受 {reason: string|null}。

```json
{
  "resolution": "Use the memory-only public reference."
}
```

## Project maintenance, pagination, errors, and limits

Maintenance 是 OpenAPI 中 public /v1/projects surface 的一部分：settings GET/PATCH 使用 ProjectMaintenanceSettingsResponse 和 ProjectMaintenanceSettingsPatchRequest；report GET 接受 team_id 和 scan_limit（default 1000，range 1..5000），并返回 ProjectMaintenanceReportResponse；execute POST 接受带有 actions（1..4 strings）、target_ids（最多 500 ids）和 confirm_all_matching（default false）的 ProjectMaintenanceExecuteRequest，并返回 ProjectMaintenanceExecuteResponse。Project todo/decision lists 暴露 status/team_id filters，但在 OpenAPI 中没有 page 或 cursor parameters。所有列出的 operations 都为 422 声明 HTTPValidationError。Runtime authorization errors 和可配置的 60 秒 rate limits 与 Authentication、Memory API pages 共用；OpenAPI 不发布 project-specific quota。