Readme Craft Agent API

通过 HTTP API 直接生成并部署 GitHub Profile README。

Base URLhttps://aidulia.cn/agent/v1

OpenAPI: /openapi.json llms.txt: /llms.txtPOST /generatePOST /deploy

Agent Resolution Flow

当用户说“优化我的 GitHub 主页”时，先解析 GitHub 用户名，再调用 API。

优先从 Agent 上下文查找：用户记忆、已连接 GitHub 账号、gh CLI 登录态、当前仓库 remote 或历史对话。
如果能解析到用户名，就带 username 和 message 调用 /analyze，再把返回的 analysis 交给 /render。
如果不知道用户名，先向用户追问 GitHub 用户名。
不要根据“我的主页”猜身份；后端只校验明确传入的用户名。

Response

{
  "error": {
    "code": "MISSING_USERNAME",
    "type": "needs_input",
    "retryable": true,
    "retry_after_seconds": 0,
    "message": {
      "en": "Please provide the GitHub username.",
      "zh": "请提供 GitHub 用户名。"
    },
    "docs_url": "https://aidulia.cn/agent#agent-resolution"
  },
  "agent": {
    "version": "1.0.0",
    "request_id": "req_...",
    "required_fields": ["username"]
  }
}

Endpoints

POST /analyze

抓取 GitHub 仓库和 Profile README，并返回分析结果

Request

{
  "username": "GitHub 用户名",
  "message": "优化一下我的 GitHub 主页",
  "extra_info": ""
}

Response

{
  "agent": {
    "version": "1.0.0",
    "request_id": "req_...",
    "quota_remaining": 4,
    "quota_reset_at": "2026-06-25T14:30:00Z"
  },
  "analysis": { "summary": "..." },
  "cache": { "analysis": "miss" }
}

Quick start

curl -X POST https://aidulia.cn/agent/v1/analyze \
  -H "Content-Type: application/json" \
  -d '{"username":"GitHub 用户名","message":"优化一下我的 GitHub 主页"}'

POST /render

基于已有 analysis 渲染一版 README

Request

{
  "username": "GitHub 用户名",
  "analysis": { "summary": "..." },
  "message": "换一种更专业的风格",
  "style": null,
  "extra_info": "",
  "exclude_styles": []
}

Response

{
  "agent": {
    "version": "1.0.0",
    "request_id": "req_...",
    "quota_remaining": 4,
    "quota_reset_at": "2026-06-25T14:30:00Z"
  },
  "readme": "# ...",
  "style": { "id": "swiss", "label": "极简瑞士" },
  "analysis": { "summary": "..." }
}

Quick start

curl -X POST https://aidulia.cn/agent/v1/render \
  -H "Content-Type: application/json" \
  -d '{"username":"GitHub 用户名","analysis":{"summary":"..."},"message":"换一种更专业的风格"}'

POST /generate

快捷路径：一次调用完成分析和渲染

Request

{
  "username": "GitHub 用户名",
  "message": "优化一下我的 GitHub 主页",
  "style": null,
  "extra_info": "",
  "exclude_styles": []
}

Response

{
  "agent": {
    "version": "1.0.0",
    "request_id": "req_...",
    "quota_remaining": 4,
    "quota_reset_at": "2026-06-25T14:30:00Z"
  },
  "readme": "# ...",
  "style": { "id": "swiss", "label": "极简瑞士" },
  "analysis": { "summary": "..." }
}

Quick start

curl -X POST https://aidulia.cn/agent/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"username":"GitHub 用户名","message":"优化一下我的 GitHub 主页"}'

POST /deploy

写入 Profile 仓库（需 GitHub PAT）

Request

{
  "username": "GitHub 用户名",
  "readme_content": "# ...",
  "github_token": "github_pat_..."
}

Response

{
  "agent": {
    "version": "1.0.0",
    "request_id": "req_...",
    "quota_remaining": 9,
    "quota_reset_at": "2026-06-26T14:30:00Z"
  },
  "success": true,
  "repo_url": "https://github.com/tammy201805/tammy201805",
  "readme_url": "https://github.com/tammy201805",
  "commit_sha": "..."
}

Quick start

curl -X POST https://aidulia.cn/agent/v1/deploy \
  -H "Content-Type: application/json" \
  -d '{"username":"GitHub 用户名","readme_content":"# ...","github_token":"$GITHUB_TOKEN"}'

GET /styles

查看可选排版模板

Response

{
  "styles": [
    { "id": "swiss", "label": "极简瑞士", "description": "..." }
  ]
}

速率限制

Level	Limit	Window
IP / analyze	5	1 hour
IP / render + generate	5	1 hour
IP / deploy	10	1 day

错误码

{
  "error": {
    "code": "RATE_LIMITED",
    "type": "temporary",
    "retryable": true,
    "retry_after_seconds": 1800,
    "message": {
      "en": "Rate limit exceeded. Try again later.",
      "zh": "请求过于频繁，请稍后重试"
    },
    "docs_url": "https://aidulia.cn/agent#rate-limits"
  },
  "agent": {
    "version": "1.0.0",
    "request_id": "req_...",
    "quota_remaining": 0,
    "quota_reset_at": "2026-06-25T14:30:00Z"
  }
}

RATE_LIMITEDMISSING_USERNAMEINVALID_USERNAMEUSER_NOT_FOUNDGITHUB_API_ERRORLLM_ERRORLLM_TIMEOUTSERVICE_BUSYDEPLOY_FAILEDINTERNAL_ERROR