harness_coding_docs/docs/api.md

API / 模块合约

本文定义后端 API、本地模块、CLI 参数或事件合约的目标形状。 实现前可细化，但不要在代码里另起一套不兼容接口。

如果项目没有后端 API，删除不适用的小节，改成本地模块接口、CLI 参数或事件合约。不要默认所有项目都有 REST 后端。

通用约定

• 传输：【JSON over HTTPS / GraphQL / gRPC / 本地函数调用】。
• 鉴权：【Session Cookie / Bearer Token / 无】。
• 请求体和响应体编码：【UTF-8 JSON】。
• 时间格式：【ISO 8601 / Unix timestamp】。
• 未登录访问需要权限的接口时返回：【401 / 403】。

通用错误响应：

{
  "error": {
    "code": "bad_request",
    "message": "请求参数不正确"
  }
}

账号

POST /api/auth/login

请求：

{
  "email": "user@example.com",
  "password": "password"
}

成功响应：

{
  "user": {
    "id": 1,
    "email": "user@example.com"
  }
}

核心资源

把项目的核心资源按 REST 或其他风格写清楚。

GET /api/items

成功响应：

{
  "items": [
    {
      "id": 1,
      "name": "示例"
    }
  ]
}

POST /api/items

请求：

{
  "name": "示例"
}

成功响应返回新增资源。

无后端项目替代写法

用于桌面工具、CLI、本地自动化脚本、纯前端本地应用等没有后端服务的项目。

本地模块合约

type Input = {
  sourcePath: string;
  options: {
    dryRun: boolean;
  };
};

type Result = {
  ok: boolean;
  outputPath?: string;
  errors: Array<{
    code: string;
    message: string;
  }>;
};

需要写清楚：

• 模块入口函数：【函数名 / 文件路径】。
• 输入字段：【字段、类型、必填、默认值】。
• 输出字段：【成功结果、失败结果、错误码】。
• 副作用：【读写哪些文件、调用哪些系统能力、是否联网】。

CLI 参数合约

【命令】 --input 【路径】 --output 【路径】 --dry-run

需要写清楚：

• 必填参数和可选参数。
• 默认值。
• 退出码含义。
• 标准输出和错误输出格式。

事件合约

适用于桌面 UI、浏览器本地状态、插件或自动化流程。

事件	触发时机	负载	结果
【event.name】	【用户动作 / 系统动作】	【字段】	【状态变化】

需要写清楚事件来源、负载字段、状态变化和失败处理。

待实现时确认

• 参数校验规则。
• 分页、排序、筛选方式。
• 重复提交是否幂等。
• 错误码枚举。
• 鉴权过期时间和刷新策略。
• 无后端项目的模块入口、CLI 参数、事件负载和副作用边界。