rednote-tool-studio/AGENT_GUIDE.md

Codex 接入说明

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

建议工作流

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 应用改动。
• 校验通过表示静态门禁通过，不等同于小红书模拟器或真机验收。

示例

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 前增加身份认证、项目授权和请求限流。