# Codex 接入说明

Rednote Tool Studio 是确定性的项目、构建与校验服务，不内嵌任何 LLM。Codex、Claude Code 或其他编码代理通过 HTTP 操作它。

生产环境使用 HTTP Basic Auth。用户名默认为 `studio`，密码由部署方保存在 `STUDIO_PASSWORD` 中。代理调用所有业务 API 时都应发送 `Authorization` 请求头；`GET /api/health` 是唯一无需认证的接口。

## 建议工作流

1. `POST /api/projects` 创建项目，保存响应中的 `id` 和 `revision`。
2. `GET /api/projects/{id}` 获取文件列表。
3. 逐个读取必要文件，避免覆盖用户未要求修改的内容。
4. 使用 `PUT /files/{path}` 或 `POST /patch` 写入，并始终传当前 `revision`。
5. 若修改了 `package.json`，调用 `POST /dependencies/install`。安装过程禁用依赖生命周期脚本。
6. `POST /build` 后读取结构化报告；根据 `code`、`file`、`line` 和 `suggestion` 修复。
7. `POST /validate` 直到 `status` 为 `passed`。
8. `POST /package`，将 `artifactUrl` 返回给用户。

完整接口契约位于 `GET /openapi.json`。

## 约束

- 小工具纯本地运行，不调用网络接口，不加载任何外链资源。
- 不使用内联脚本、行内事件、`type="module"`、`import()`、Web Worker、WASM 或受限设备 API。
- 源码可以用 React JSX；服务会将最终代码打包成面向 Chrome 61 的 ES2017 经典脚本。
- `index.html` 必须位于 ZIP 根目录。
- 修改失败并返回 HTTP 409 时，重新获取项目与文件，再基于最新 revision 应用改动。
- 校验通过表示静态门禁通过，不等同于小红书模拟器或真机验收。

## 示例

```bash
curl -X POST http://localhost:3000/api/projects \
  -H 'Content-Type: application/json' \
  -d '{"name":"周末灵感签","template":"basic"}'

curl -X POST http://localhost:3000/api/projects/PROJECT_ID/package \
  -H 'Content-Type: application/json' \
  -d '{}'
```

不要把服务暴露到不可信网络。后续部署到共享环境时，应在 API 前增加身份认证、项目授权和请求限流。