Now I have a comprehensive understanding of the C route's patterns. Let me check a few more C files to understand tags route, media route, ai route, and check the smoke report. But I have enough. Let me also check the drizzle migration SQL to understand the table structure generated. And check the smoke artifacts. Actually, I have enough info. Let me think about the architecture for Route F. ## Route F design Key differences from C: 1. **Single GraphQL endpoint** `POST /graphql` using graphql-yoga with handwritten SDL schema 2. `GET /graphql?sdl` returns SDL (schema self-description) — this is DoD item 5 (SDL version) 3. Idempotency via `idempotencyKey` parameter in mutations, D1 `idempotency` table 4. Audit logs in every mutation resolver 5. `extensions.agent_hints` on GraphQL errors 6. NO REST API (except: export zip at `/export`, view beacon `POST /view/{slug}`) 7. Static rebuild pipeline reusing C's approach (D1 content render → direct upload Pages, debounce 10s) 8. Astro static frontend pulling from GraphQL at build time 9. React island admin SPA talking to GraphQL (fetch + query/mutation strings) Data model per shared spec: - posts(slug,title,content,summary,status draft|published,created_at,updated_at,published_at) - tags(id,name,slug) - post_tags - media(id,filename,url,content_type,size,created_at) - audit_logs(id,action,resource,actor_id,subject_id,via,created_at) - idempotency(key,response_hash,created_at) Note: The spec says posts doesn't include views but C added views. The shared spec data model doesn't include views but the stats panel needs 访问数 (views). Let me add views to posts — the shared spec says "统计面板（文章/标签/访问数）". I'll include views in the posts table. That's consistent with C. GraphQL SDL: ```graphql type Post { slug: String! title: String! content: String! summary: String status: Status! tags: [Tag!]! createdAt: String! publishedAt: String _links: PostLinks! } type PostLinks { publish: String unpublish: String delete: String edit: String } enum Status { DRAFT PUBLISHED } type Query { posts(status: Status, tag: String, page: Int): PostPage! post(slug: String!): Post tags: [Tag!]! stats: Stats! openapiMeta: JSON! } type Mutation { createPost(input: PostInput!, idempotencyKey: String!): Post! updatePost(slug: String!, input: PostInput!): Post! deletePost(slug: String!): Boolean! publish(slug: String!, idempotencyKey: String!): Post! unpublish(slug: String!): Post! generateSummary(slug: String!): SummaryResult! } ``` Note the SDL in the handoff has `openapiMeta: JSON!` — that's a bit odd. It's the "OpenAPI meta" field in GraphQL. Actually reading again: `stats: Stats! openapiMeta: JSON!`. Hmm, since Route F explicitly says NO OpenAPI, but the SDL in the handoff includes `openapiMeta: JSON!`. Wait — I think the intent is: since GraphQL is self-describing via SDL, the `openapiMeta` field was probably a leftover or a field that returns metadata about the API. Actually it says the schema is "最小集" (minimal set). Let me reconsider. Actually I think including `openapiMeta: JSON!` would be confusing since we don't have an OpenAPI doc. But the handoff's SDL literally has it. Hmm. Let me interpret: the field could return API metadata/self-description — like schema version, available endpoints (the non-GraphQL endpoints like /export, /view), links to SDL, etc. That's a reasonable interpretation: "OpenAPI meta" = a JSON describing the API's meta-information. Since we intentionally drop OpenAPI, I can implement `openapiMeta` as a JSON object containing: name, version, description, sdl endpoint, docs, non-graphql endpoints (export, view beacon), rate limits, authentication method. That gives the Agent a self-description of the full API surface (including the pragmatic non-GraphQL exceptions). I'll implement it with descriptions. This also covers DoD item 5 partially — no, DoD 5 is SDL. But openapiMeta can be the "meta" describing the whole API. Good. Let me design the resolver structure. Since it's a single GraphQL endpoint, everything goes through graphql-yoga. Auth: the `Authorization: Bearer` header — graphql-yoga passes request to context. I'll extract auth from the request header (API_TOKEN or JWT session). For mutations, require auth. For queries, allow anonymous for published posts; authenticated users can see drafts. Wait, the admin SPA needs a login flow. Since we have a single GraphQL endpoint, login should be a mutation too! The handoff SDL shows `Query` and `Mutation` without a login mutation though. Hmm. The admin SPA needs to log in. Options: - Add a `login(username, password): AuthPayload` mutation. This is the GraphQL-idiomatic way. - The handoff's "minimal set" SDL doesn't include login but also doesn't forbid adding. The handoff says "SDL 最小集" and shows a specific set. I think adding `login` mutation and `me` query is reasonable and necessary for the human admin SPA. Actually wait — re-reading: the admin SPA "调 GraphQL（fetch + 简易 query/mutation 字符串）". Login via GraphQL mutation is cleanest. But there's a subtlety: the handoff says the admin UI is "React 岛 SPA 调 GraphQL". Login must go through GraphQL to be a pure GraphQL facade. I'll add: ```graphql type AuthPayload { token: String! username: String! } type Mutation { login(username: String!, password: String!): AuthPayload! ... } ``` That's a pragmatic extension to the minimal SDL. I'll document it. Also the handoff SDL doesn't show PostInput, Tag, PostPage, Stats, SummaryResult, JSON scalar. I need to define those. PostInput: { title, content, summary, slug, status, tags }. Tag: { id, name, slug }. PostPage: { posts, total, page, perPage, totalPages }. Stats: matches stats panel. SummaryResult: { summary, tags, configured, message? }. Hmm, let me keep Stats aligned with what admin needs: postCount, publishedCount, draftCount, tagCount, mediaCount, totalViews, topViewed. Media: the handoff SDL doesn't include media queries/mutations! But the shared spec DoD requires: media CRUD is part of admin (媒体 CRUD is in DoD? Actually DoD item 3 is 登录→发文→发布→前台可见→撤回→不可见→删除. The shared spec section 1 says 后台 /admin: 登录、文章 CRUD + 发布/撤回、标签 CRUD、统计面板、导出 zip. Media upload is part of... "导出 zip（posts/*.md + frontmatter + media/）". Media is seeded (1 media). The admin media library in C is a nice extra. For GraphQL, media would need mutations too: `media`, `uploadMedia`, `deleteMedia`. Since export zip needs media and stats needs mediaCount, media queries are needed at minimum. Let me add: ```graphql type Media { id: Int! filename: String! url: String! contentType: String! size: Int! createdAt: String! } type Query { ... media: [Media!]! ... } type Mutation { uploadMedia(idempotencyKey: String!, file: Upload!): Media! deleteMedia(id: Int!): Boolean! } ``` Upload scalar requires graphql-yoga's `GraphQLUpload`. That works in yoga. But uploading files via fetch + FormData to /graphql with multipart — graphql-yoga supports multipart requests (graphql-multipart-request spec) with Upload scalar. That's doable but adds complexity. Alternatively, since export zip is a non-GraphQL endpoint (binary), media upload could also be... no, keep GraphQL purity where feasible. graphql-yoga supports file uploads natively. The admin SPA can use fetch with FormData containing operations + map + file (multipart). graphql-yoga handles it. Let me implement that. Actually, let me reconsider the scope. The DoD requirements are the acceptance criteria. Let me map them: 1. 干净环境一条命令起本地 dev — README. npm install + npm run dev. I need a `.env` for local dev. 2. seed：管理员+3篇文章+标签+1媒体 — seed script. 3. 浏览器全流程：登录→发文→发布→前台可见→撤回→不可见→删除 4. Agent curl：token 登录→建文→发布→前台可见；带 idempotencyKey 重复请求返回同一结果 — via GraphQL. 5. SDL：SDL 可获取且包含全部 Query/Mutation 与字段描述（SDL 版） 6. 双轨审计：写操作后查 audit_logs 有 actor/subject/via 记录 7. HATEOAS：GET 文章返回 _links — via GraphQL Post._links 8. 错误格式：无 token 访问返回结构化 agent_hints — GraphQL errors extensions.agent_hints 9. 导出 zip：frontmatter 可被 PyYAML 解析 10. 真实部署 + 线上 URL 可打开 11. 部署后线上重跑 3/4/8 关键项冒烟 Plus the route handoff's own DoD: browser admin full flow; Agent pure GraphQL (createPost idempotent replay → publish → auto rebuild → frontend visible); SDL fetch; error extensions.agent_hints. So I need: - Login (GraphQL mutation) + admin UI - Post CRUD + publish/unpublish (GraphQL) - Tags CRUD - Media upload + list + delete - Stats - Export zip (non-GraphQL GET /export) - View beacon (non-GraphQL POST /view/{slug}) - Auto rebuild pipeline (debounce 10s, direct upload) - Audit logs - Idempotency (D1 table, key param) - SDL endpoint - errors with extensions.agent_hints - Post._links (HATEOAS) Choice: idempotency via D1 `idempotency` table vs KV IDEMPOTENCY_F. The handoff says "幂等：mutation 参数内 idempotencyKey，D1 idempotency 表". So D1 table it is. This also gives auditable idempotency records and works in local dev (better-sqlite3). Reason: single store, transactional with the write, auditable, portable. I'll note this in README/report. Idempotency design: - On createPost/publish with idempotencyKey: first check `idempotency` table for key. If found, return the stored result (response_hash stores a JSON of the result post). If not, perform operation and store the key → response. - response_hash: I'll store the JSON of the returned Post (e.g. slug + the serialized result). Return the same result object. - For createPost: idempotent on key. Note: if key differs but same slug → slug conflict error (409 equivalent). The handoff's replay test: "重复 mutation 同 slug" — hmm, "query posts→mutation createPost(带 idempotencyKey)→重复 mutation 同 slug→publish". Let me re-read: "Agent 用纯 GraphQL：query posts→mutation createPost(带 idempotencyKey)→重复 mutation 同 slug→publish→前台（自动重建后）可见". So the replay is "重复 mutation 同 slug" — repeat the same mutation with the same slug (and same idempotencyKey presumably). The shared spec DoD 4 says "带 X-Idempotency-Key 重复请求返回同一结果" — same request with same key returns same result. So I'll implement: if idempotencyKey already exists, return stored result regardless of input. This handles both same-request replay and same-slug replay. Where to store idempotency response? I'll store response JSON in the `response_hash` column... actually the name says hash but C stored hash. Let me just store a hash of the response plus... hmm. To "return the same result", I need to reconstruct the result. Two approaches: a) Store full response JSON in idempotency table (extra column `response_json`). b) Re-derive: for createPost, look up post by slug (stored key→slug mapping). Simplest robust: store `response_json` in the idempotency table. On replay, return stored response_json (which is the serialized Post). That's clean and truly "same result". I'll do that. The spec's field name `response_hash` — I'll keep the column named response_hash but store the JSON there? That's semantically wrong. Let me store hash + a `response_json` column. Actually the spec table is `idempotency(key,response_hash,created_at)`. I'll keep `response_hash` as a column name but store the full response JSON (documenting that we store the serialized response for exact replay; a hash alone couldn't reconstruct the result). Hmm, but I could store both: response_hash = md5 of response_json for integrity, and response_json for reconstruction. Let me add both columns: `key`, `response_hash`, `response_json`, `created_at`. That's a reasonable extension of the minimal spec. Actually simpler: I'll follow the spec: `idempotency(key, response_hash, created_at)` where I store response_json in response_hash column. No — that's confusing for future readers. I'll add `response_json` column. It's minimal-necessary. I'll document the deviation. Actually, let me keep it truly minimal and spec-compliant: `response_hash` stores a hash; add `response_json` for replay. I'll document both. Fine. Now, the D1/KV choice: "KV 如需幂等 IDEMPOTENCY_F（GraphQL 幂等键走 D1 表也可，选一说明理由）". I choose D1 table. Reasons: single transactional store with the data (no distributed consistency issues between KV and D1), works identically in local better-sqlite3 dev, auditable (who/what replayed), avoids extra KV namespace. Document in README. ### Audit logs design `audit_logs(id, action, resource, actor_id, subject_id, via, created_at)`. The handoff: "双轨审计：每个 mutation resolver 调 Service 前/后写 audit_logs（actor=token, subject, via='graphql')". And shared spec: "所有写操作审计日志记录 actor_id / subject_id / via(web|api) / created_at". For GraphQL route, via='graphql'. actor_id = token identity (username "admin" for session JWT, "agent" for API_TOKEN). subject_id = 管理员 id — we only have a single admin. Hmm, shared spec says JWT has sub (actor=Agent/人类会话) and act_sub (subject=意志主体管理员 id). So for API_TOKEN requests, actor_id = "agent:<api-token-identity>", subject_id = "admin" (the will-subject). For web session, actor_id = "session:admin" (or the username), subject_id = "admin". Let me keep it simple: - Session login: actor_id = username (e.g. "admin"), subject_id = username, via = "graphql" (since even the web admin goes through GraphQL now). - Agent API token: actor_id = "agent", subject_id = "admin", via = "graphql". Wait, but the shared spec says via(web|api). For GraphQL route the handoff says via='graphql'. I'll use via='graphql' as the route F interpretation (the whole facade is GraphQL; distinguish via=graphql and note that in the SDL/meta). Actually, to keep DoD 6 testable ("查 audit_logs 有 actor/subject/via 记录"), I'll write an audit record for each mutation with action (create_post/update_post/delete_post/publish/unpublish/...), resource (e.g. "post:<slug>"), actor_id, subject_id, via='graphql', created_at. But wait — how does an agent verify audit_logs? There's no GraphQL query for audit_logs in the SDL. DoD 6 requires "写操作后查 audit_logs 有 actor/subject/via 记录". Since the schema is minimal, I could add a `auditLogs` query to the SDL. That makes it checkable via GraphQL. The handoff's minimal SDL doesn't include it, but adding a read-only `auditLogs(limit)` query to Query type is a pragmatic extension that makes the DoD verifiable through the pure GraphQL facade. I'll add it. It's an admin-only query. Alternatively, DoD 6 could be verified by directly querying D1 with wrangler. But pure GraphQL verification is cleaner and consistent with "Agent 全操作" and "双轨审计". I'll add `auditLogs` query. ### Error handling with extensions.agent_hints graphql-yoga: throw errors with extensions. In resolvers, throw a custom error class: ```ts class GraphQLErrorWithHints extends GraphQLError { constructor(message, hints, code, status) { super(message, { extensions: { code, http: {status}, agent_hints: hints } }) } } ``` So the response is: ```json { "errors": [{ "message": "Unauthorized", "extensions": { "code": "UNAUTHORIZED", "http": {"status": 401}, "agent_hints": {"retry_allowed": false, "suggested_action": "..."} } }] } ``` That's the route F equivalent of the structured error. Good. For unauthenticated mutation access: throw Unauthorized error with agent_hints { retry_allowed: false, suggested_action: "Provide a valid Authorization: Bearer <API_TOKEN> header or session token via login()" }. For validation errors (e.g. slug exists): agent_hints { retry_allowed: true (with different slug), suggested_action: "..." }. For AI not configured: SummaryResult with configured:false and agent_hints... actually generateSummary returns SummaryResult { summary, tags, configured, message }. In C it returned configured:false with message. I'll do the same via a result object (not an error). Also the GraphQL spec has the `extensions` field on errors per spec. graphql-yoga automatically includes extensions if we pass them. Good. ### Rebuild pipeline Reuse C's approach: pages-rebuild.ts (buildSiteFiles + uploadToPages with direct-upload) and rebuild.ts (triggerRebuild with debounce 10s + rebuildState table + waitUntil). But code must be NEW (re-written), not copied verbatim. I'll rewrite them with the same architecture but adapted for GraphQL (rendering from D1, using my own schema/table names). I'll write my own render module (the Astro frontend pages will be F-specific). Note: The rebuild pipeline must mirror the Astro output. My Astro frontend will have index, posts/[slug], tags/[slug], admin. The rebuild renders index/posts/tags with the same CSS/layout as Base.astro. For the admin SPA assets: rebuild fetches live site /admin/ + _astro assets (like C). I'll reuse the same approach (fetchLiveAssets). Important: in C, `render.ts` was used both by the rebuild pipeline and... Actually no, render.ts was used only in pages-rebuild.ts. The Astro frontend is separate. For F, I'll write `apps/api/src/lib/render.ts` that mirrors `apps/web` frontend pages (index/posts/tags) for the rebuild. The view beacon posts to `/view/{slug}` (F uses POST /view/{slug} instead of C's /api/posts/{slug}/view). ### Static frontend build via GraphQL Astro static build fetches from GraphQL API at build time. So `apps/web/src/lib/api.ts` uses a GraphQL query string + POST to /graphql. Astro build needs PUBLIC_API_URL pointing at the deployed worker (for production build). For local dev, the API runs locally via @hono/node-server + graphql-yoga, and Astro pulls from localhost. Local dev: `npm run dev` starts API (tsx watch src/index.ts on port 8790) and web (astro dev on 4321). Astro dev doesn't build static pages though — dev mode renders on the fly. That's fine for local development. The "干净环境一条命令起本地 dev" — I'll provide `npm run dev` and also `npm run build` for the static build. Actually to mirror C: root `npm run dev` runs both in parallel. Good. But wait — for the DoD local tests, I need the API running and the web build to work. Let me set up scripts: - `npm run dev` → parallel api + web dev - `npm run build` → api build (tsc --noEmit) + web build (astro build with PUBLIC_API_URL) ### Auth for GraphQL graphql-yoga: context = ({ request }) => ({ auth: await resolveAuth(request) }). resolveAuth extracts Bearer token, checks API_TOKEN or verifies JWT, returns { type: 'session'|'agent', username }. Login mutation issues JWT (jose) — same as C. But we need to run jose in worker (works fine). ### Env / runtime I'll mirror C's portable env approach but simplified. Since route F's API is GraphQL-only, but I still have the dual entry (worker + node). Actually — do I need the node entry for local dev? Yes, for local testing (better-sqlite3) and DoD tests. The handoff mentions "双入口 worker/node" as a mature pattern to reference. I'll keep it: `src/index.ts` (node) and `src/worker.ts` (worker). Use the runtime context (AsyncLocalStorage) approach. Let me simplify: I'll use the same architecture but write my own code. I'll use drizzle-orm for D1 + better-sqlite3 for local. Actually — could I avoid drizzle and write raw SQL? The handoff doesn't require drizzle. Using raw SQL via better-sqlite3 and D1's `prepare().all()/run()/first()` would be simpler and truly my own. But drizzle gives type safety and migrations. Hmm. Tradeoff: raw SQL is simpler, less dependency weight, and D1's API is very close to better-sqlite3. Actually better-sqlite3 has .prepare().get()/.all()/.run() and D1 has .prepare().first()/.all()/.run(). Very similar. I could write a small db facade with raw SQL that works on both. That avoids drizzle entirely and is arguably more "first-principles". Migrations: I can write a single SQL migration file and apply it both locally (better-sqlite3 exec) and on D1 (wrangler d1 migrations apply, or just d1 execute --file). Actually wrangler d1 migrations require the migrations folder format with journal. Simpler: use `wrangler d1 execute --file=schema.sql` for remote, and local better-sqlite3 exec for local. I'll write `db/schema.sql` with CREATE TABLE IF NOT EXISTS. And a `db/migrate.ts` that runs it on local sqlite. And for remote: `wrangler d1 execute leoblog-f-db --remote --file=./schema.sql`. This is cleaner and less code. Let me go raw SQL. No drizzle. No drizzle-kit. Fewer deps, less to maintain. The idempotency table etc. all via raw SQL. Let me design the DB layer: ```ts // db/types.ts export interface DB { // mirror of better-sqlite3 subset AND D1 prepare(sql: string): any // returns statement } ``` Hmm, the better-sqlite3 API: `db.prepare(sql)` returns Statement with .all(), .get(), .run(), .bind(). D1: `db.prepare(sql)` returns D1PreparedStatement with .bind(...), .all(), .first(), .run(). Both chain. The patterns differ slightly: - better-sqlite3: `stmt.all(...params)` — params to all(). - D1: `stmt.bind(...params).all()`. To unify, I'll write a tiny adapter that takes raw SQL + params and produces rows, using a runtime-provided executor. Approach: each DB adapter (node/worker) exposes a uniform interface: ```ts interface Queryable { all(sql: string, params: unknown[]): Promise<Row[]> get(sql: string, params: unknown[]): Promise<Row | undefined> run(sql: string, params: unknown[]): Promise<{ meta: { changes?: number } }> exec(sql: string): Promise<void> } ``` Node adapter wraps better-sqlite3 (synchronous, but returns promises). Worker adapter wraps D1 (`await env.DB.prepare(sql).bind(...).all()` etc). The rest of the code is fully portable and async. This is clean and avoids drizzle. Then a `db/` facade with helper functions like `insertPost`, `findPostBySlug`, `listPosts`, etc. Or I can keep raw SQL in the services. Let me write a `db.ts` module with typed functions, plus a generic query helper. Actually, to keep it manageable, I'll write a `services/` layer (per smart-door "Service 只写一次"): - services/posts.ts — post CRUD, publish/unpublish, tags attach - services/tags.ts — tag CRUD - services/media.ts — media upload/list/delete (via storage adapter) - services/stats.ts - services/export.ts — zip build - services/audit.ts — audit logging - services/idempotency.ts — idempotency key handling - services/ai.ts — summary generation - services/rebuild.ts — trigger rebuild - services/pages-rebuild.ts — direct upload pipeline - services/render.ts — static HTML renderer for rebuild - services/auth.ts — JWT issue/verify, token identity - services/storage.ts — R2/local adapter Resolvers (graphql layer) call services. That's the "Service 只写一次，两件外套" principle — here there's only one 外套 (GraphQL), plus the non-GraphQL endpoints (/export, /view) also call the same services. Good. Actually — I realize the "两件外套" concept: human Web UI and Agent API are two shells over the same Service. In Route F, both the human admin SPA and Agent go through the SAME GraphQL endpoint. So the two shells are literally the same HTTP endpoint (just different auth: session JWT vs API token). That's an elegant illustration. The Service layer is the single source of business logic. Let me now think about the file layout for route-f: ``` route-f-graphql/ ├── package.json # workspaces ├── .env # local env (dev secrets - but NOT the CF token; only local dev creds) ├── README.md ├── apps/ │ ├── api/ │ │ ├── package.json │ │ ├── tsconfig.json │ │ ├── wrangler.toml │ │ ├── schema.sql # D1/local schema │ │ ├── data/ # local sqlite (gitignored) │ │ └── src/ │ │ ├── index.ts # node entry │ │ ├── worker.ts # workers entry │ │ ├── app.ts # hono app assembly (graphql + non-graphql endpoints) │ │ ├── graphql/ │ │ │ ├── schema.ts # SDL + resolvers │ │ │ └── errors.ts # error classes with agent_hints │ │ ├── db/ │ │ │ ├── types.ts │ │ │ ├── node.ts │ │ │ ├── worker.ts │ │ │ ├── migrate.ts │ │ │ └── seed.ts │ │ ├── services/ │ │ │ ├── auth.ts │ │ │ ├── audit.ts │ │ │ ├── idempotency.ts │ │ │ ├── posts.ts │ │ │ ├── tags.ts │ │ │ ├── media.ts │ │ │ ├── stats.ts │ │ │ ├── export.ts │ │ │ ├── ai.ts │ │ │ ├── rebuild.ts │ │ │ ├── pages-rebuild.ts │ │ │ ├── render.ts │ │ │ └── storage.ts │ │ └── lib/ │ │ ├── runtime.ts # AsyncLocalStorage context │ │ ├── env.ts # env facade │ │ └── slugify.ts # maybe fold into posts │ └── web/ │ ├── package.json │ ├── astro.config.mjs │ ├── tsconfig.json │ └── src/ │ ├── lib/api.ts # GraphQL client │ ├── layouts/Base.astro │ ├── pages/index.astro │ ├── pages/posts/[slug].astro │ ├── pages/tags/[slug].astro │ └── pages/admin/index.astro │ └── islands/admin/ │ ├── AdminApp.tsx │ └── api.ts # GraphQL client for admin ``` Wait — I need to also produce a migration SQL for D1. wrangler d1 migrations apply expects a folder with a journal. But `wrangler d1 execute --remote --file=...` works without journal. I'll use that approach: one `schema.sql` applied both locally and remote. Actually there's a subtlety: `wrangler d1 execute --remote --file=schema.sql` requires the D1 binding? No — `wrangler d1 execute <database_name_or_id> --remote --file=...`. It works with just the DB name/id and account. Good. I'll run it from apps/api dir. ### The GraphQL endpoint details graphql-yoga on Hono: `graphql` from 'graphql-yoga' returns a fetch handler; on Hono use `app.all("/graphql", (c) => yoga.fetch(c.req.raw, createYogaContext(c)))`. Actually the cleanest: `const yoga = createYoga({ schema, context: ({ request }) => ... })` and then `app.all("/graphql", (c) => yoga.fetch(c.req.raw, { ... }))`. yoga.fetch takes (request, responseInit, ctx). To inject context, we can use `context: ({ request, params })` inside createYoga. But we need the Hono context (for executionCtx / waitUntil) in the rebuild trigger. Let me get waitUntil via `c.executionCtx`. graphql-yoga createYoga options: ```ts createYoga({ schema, context: ({ request, params }) => ({ ... }), // params = passed through fetch ... }) ``` So I can pass `ctx` from Hono into `yoga.fetch(c.req.raw, { request: c.req.raw }, { honoCtx: c })`. Hmm, the yoga.fetch signature is `fetch(request: Request, responseInit?, params?)`. The third argument is available in context as `params`. So: ```ts app.all("/graphql", (c) => yoga.fetch(c.req.raw, undefined, { honoCtx: c })) ``` and in context: `({ params }) => ({ honoCtx: params?.honoCtx })`. Then resolvers can access `context.honoCtx.executionCtx?.waitUntil`. Alternatively, I can get waitUntil from the request via `request.headers`... no. Let me check: graphql-yoga also exposes `serverContext`. The third fetch arg is the "context" merged... Let me recall graphql-yoga API: ```ts const yoga = createYoga<ServerContext>({ schema, context: ({ request, params }) => ({ ... }) // request: Request, params: from fetch() }) // then yoga.fetch(request, responseInit, serverContext) ``` Actually graphql-yoga's `fetch` is `(request, responseInit?, serverContext?)`. The `context` option function receives `{ request, params }` where params is the serverContext passed. So yes: pass `c` as third arg to yoga.fetch, and receive it in context as `params`. Wait, I need to double check naming. In graphql-yoga, the context factory receives `{ request, params, ... }` and `params` = the "ctx" arg passed to `.fetch()`. Let me verify with the actual docs when implementing. I'll write a small wrapper and test it. Actually simpler and more robust: build a `createYoga` with `context: async ({ request }) => ({ request, auth: ..., db: runtime.db, storage, env, honoCtx: null })`. But we need honoCtx. Alternatively, since the runtime context (AsyncLocalStorage) already carries db/storage/env, I only need honoCtx for waitUntil. I can get waitUntil from... Actually, there's another way: in worker.ts, the ExecutionContext is available at fetch() top level. I can stash it in the runtime context. Let me add `executionCtx` to the RuntimeContext. Then resolvers call `triggerRebuild` which uses `runtime().executionCtx.waitUntil`. That's clean and avoids the hono/yoga interplay. In Node, executionCtx is undefined; triggerRebuild then just void-settles. So RuntimeContext = { db, storage, env, executionCtx?: { waitUntil } }. For context: I'll pass the hono context through the third arg to get auth... actually auth is extracted from the request header, which the context factory receives as `request`. So context factory: ```ts context: async ({ request }) => ({ auth: await resolveAuth(request), // runtime stuff via runtime() facade }) ``` And since runtime() (ALS) already provides db/storage/env/executionCtx, the resolvers can import `db`, `env` facades directly. Now, the auth identity resolution: ```ts interface AuthIdentity { kind: 'session'|'agent'|'anonymous', actorId: string, subjectId: string } ``` - Bearer token == API_TOKEN → kind='agent', actorId='agent', subjectId='admin' (意志主体). Actually let me make actorId='agent:leoblog-f' or just 'agent'. And subjectId='admin'. - Bearer token valid JWT → kind='session', actorId='session:'+username, subjectId=username. - no/invalid token → anonymous. Queries (read): allow anonymous but restrict to published posts (unless authenticated). Mutations: require authenticated (session or agent). Login mutation: public (obviously). Note: DoD 8 "无 token 访问返回结构化 agent_hints" — the error case. In GraphQL, a mutation without auth → errors[0].extensions.agent_hints. ### IDEMPOTENCY implementation detail idempotencyKey is required (String!) for createPost and publish. Maybe optional for others? The handoff shows createPost(input, idempotencyKey!) and publish(slug, idempotencyKey!). updatePost/unpublish/delete don't have it. Follow the handoff exactly: createPost and publish require idempotencyKey. For uploadMedia too (I'll require it). Actually let me just require it for createPost and publish per handoff, and also uploadMedia since I add it. Keep updatePost/unpublish/delete without (they're naturally idempotent operations on a specific resource). Implementation: ```ts async function withIdempotency(key, action, fn): Promise<Post> { if (!key) throw validation error const existing = await getIdempotency(key) if (existing) return JSON.parse(existing.response_json) // exact replay const result = await fn() await storeIdempotency(key, result) return result } ``` Race conditions: two concurrent requests with same key. D1 is single-writer serialized per write; but two isolates could interleave. For a prototype, checking-then-inserting is fine; add UNIQUE constraint on key, and on conflict, re-fetch and return stored. I'll add a try/catch on insert; if unique violation, read existing and return it. Good enough and documented. ### View beacon `POST /view/{slug}` — public, increments views. DoD browser flow: "前台可见" doesn't need views, but stats panel shows 访问数. The static detail page beacon posts to the API `/view/{slug}`. In C it was `/api/posts/{slug}/view`. For F, the route is `POST /view/{slug}` per handoff ("view beacon POST /view/{slug}"). Good. ### Export zip `GET /export` (non-GraphQL, binary). Requires auth (Bearer). Uses fflate zipSync. Same structure: posts/*.md + media/. frontmatter parseable by PyYAML. ### Stats GraphQL `stats` query returns { postCount, publishedCount, draftCount, tagCount, mediaCount, totalViews, topViewed: [StatsItem] }. DoD: 统计面板（文章/标签/访问数）. Good. ### AI generateSummary `generateSummary(slug): SummaryResult!`. SummaryResult = { summary: String!, tags: [String!]!, configured: Boolean!, message: String }. Calls OpenAI-compatible endpoint if configured; else configured:false with message. It's a mutation (writes summary to post? In C, aiSuggest returned suggestions without persisting; the admin form applies them). Let me have generateSummary persist the summary to the post (that's more "resource-ized" and useful for agents: call generateSummary(slug) → returns new summary and updates the post). Hmm, handoff SDL: `generateSummary(slug: String!): SummaryResult!`. I'll make it update the post's summary field with the generated summary, and return SummaryResult { summary, tags, configured, message }. If not configured → configured:false, message, and post unchanged. Persisting summary is a reasonable interpretation and useful. But then it's a write op → audit + rebuild? It writes summary. I'll audit it (action=generate_summary). Rebuild not strictly needed if content changes summary... but the list page shows summary, so rebuild IS needed. I'll trigger rebuild too. Actually the admin flow in C: AI generates summary suggestion, user clicks to save (which triggers updatePost → rebuild). For the GraphQL generateSummary mutation that auto-persists, I should trigger rebuild since the post's rendered summary changes. OK. ### The admin React SPA via GraphQL I'll write a minimal GraphQL client in the SPA: ```ts async function gql<T>(query: string, variables?: Record<string, unknown>, token?: string): Promise<T> ``` Posts fetch + execute query/mutation strings. Login: `mutation { login(username, password) { token } }`. Token stored in localStorage. Authorization header added when present. AdminApp will have tabs: Posts, Tags, Media, Stats. Post form with title/slug/summary/tags/content/status + AI generate. Upload media via multipart GraphQL (Upload scalar). Export zip via GET /export with Authorization header (download blob). For file upload with graphql-yoga multipart: ``` const form = new FormData() form.append('operations', JSON.stringify({ query: 'mutation($file: Upload!){ uploadMedia(file:$file){ ... } }', variables: { file: null } })) form.append('map', JSON.stringify({ '0': ['variables.file'] })) form.append('0', file) ``` That's the graphql-multipart-request spec. graphql-yoga supports it natively with `Upload` scalar (imported from graphql-yoga? Actually GraphQLUpload from 'graphql-upload' — but graphql-yoga re-exports or is compatible). Let me check: graphql-yoga supports file uploads; the scalar type is `GraphQLUpload` exported from 'graphql-yoga'. Yes, `import { GraphQLUpload } from 'graphql-yoga'`. Actually, I need to double check the multipart handling in yoga: it requires the request to have Content-Type multipart/form-data. yoga's fetch handler processes it. The resolver receives the upload promise / File. In yoga, `file` arg of type Upload is a `File` (they use the fetch File API). So in resolver: `const file: File = args.file; const buf = new Uint8Array(await file.arrayBuffer())`. Good. ### Astro frontend GraphQL queries At build time, fetch POST `${API_URL}/graphql` with query: ```graphql query Home($page: Int) { posts(status: PUBLISHED, page: $page) { posts { slug title summary publishedAt tags { slug name } } total totalPages } tags { slug name } } ``` For getStaticPaths of detail pages, fetch all published posts (iterate pages or fetch posts with large page). Detail page query: `query { post(slug) { ... } }`. Tag page: query posts(tag: slug) and tags. I'll keep it simple: the frontend fetches from GraphQL at build time via a small gql helper (fetch + JSON). ### The SDL self-description endpoint `GET /graphql?sdl` returns the SDL text. graphql-yoga: I can use `printSchema(schema)` from graphql. On the `/graphql` route, if method GET and query param sdl, return text/plain of printSchema(schema). Also `GET /graphql` (no query) — graphql-yoga returns a simple landing/playground (in dev) or a 400 "GET query not allowed"? By default yoga's GET on /graphql runs queries if `?query=` present; otherwise returns a landing page. That's fine. Also add descriptions in the SDL so DoD 5 "SDL 可获取且包含全部 Query/Mutation 与字段描述" — every type, field, arg should have a description. I'll write SDL with `"""..."""` descriptions throughout. ### openapiMeta `Query.openapiMeta: JSON!` — returns a JSON describing the API meta: name, version, endpoint (single /graphql), sdl endpoint, auth, non-graphql endpoints (export, view), idempotency convention, rate limiting, etc. I'll implement with a `JSON` custom scalar (graphql-yoga exports GraphQLJSON? graphql-yoga has built-in `GraphQLJSON`? Let me check — graphql-yoga exports GraphQLScalarType built-ins? Actually 'graphql-yoga' re-exports `GraphQLJSON` from 'graphql-scalars'? Hmm. Let me just define my own JSON scalar: ```ts const JSONScalar = new GraphQLScalarType({ name: 'JSON', description: 'Arbitrary JSON value', serialize: (v) => v, parseValue: (v) => v, parseLiteral: (ast) => ast.kind === Kind.OBJECT ? ... }) ``` For serialize only (output), a minimal scalar works. I'll implement serialize + parseValue + parseLiteral (return raw value). Fine. ### Now — what about the seed with 1 media? Seed: admin (via env ADMIN_USER/ADMIN_PASSWORD — not stored in DB; that matches C where admin is just env creds). 3 posts (2 published, 1 draft), tags, 1 media. For local seed, write file to uploads/ and insert media row. For remote seed (D1+R2), write to R2 bucket and insert media row with public URL. I'll write a seed script that works against the local sqlite, plus a remote seed path. For remote seed, I'll create a temporary worker script that uses the D1 + R2 bindings? That requires deploy first. Alternative: use `wrangler d1 execute --remote` with SQL inserts and `wrangler r2 object put` for the media file. Simpler: write a `seed-remote.ts` that runs via `wrangler d1 execute` — but D1 execute runs SQL, not TS. C's approach: they had seed-remote.ts used "via wrangler d1 execute / a temporary worker". I'll do: 1. Create the media object in R2 via `wrangler r2 object put leoblog-f-media/seed-sample.png --file=...` 2. Insert seed data via `wrangler d1 execute leoblog-f-db --remote --file=./db/seed.sql` (a SQL file with INSERTs using fixed timestamps or SQLite datetime functions). Actually writing seed as SQL is clean and reproducible. But content with markdown + Chinese needs careful escaping in SQL. Alternatively, write a small script `wrangler d1 execute leoblog-f-db --remote --command="..."` — messy. Better approach: deploy the worker FIRST, then run a seed script that calls the GraphQL API (createPost etc.) with the API token + upload media via multipart to /graphql. That exercises the real API and populates D1. This is elegant: seed through the GraphQL facade (also validates the facade works). But the seed must be idempotent-ish (re-running would create duplicate slugs → 409). I'll write a seed script that checks existence first (query posts) or catches slug conflicts gracefully. Actually, for the "干净环境" DoD, local seed uses the local DB directly (seed.ts → sqlite). For remote, I'll seed via the API (a script `scripts/seed-remote.mjs` that hits the deployed worker's /graphql with createPost mutations, plus a media upload). That also doubles as the DoD 4 agent flow test. Hmm, but DoD item 2 (seed) is mainly about local. Let me make: - `db/seed.ts` (node): inserts into local sqlite: 3 posts, tags, 1 media file (writes to uploads/). - Remote: I'll deploy worker + migrate D1 (schema.sql), then run `npm run seed:remote` which is a node script using fetch to the live GraphQL endpoint (createPost with idempotencyKeys, uploadMedia multipart). This tests the real API too. Wait, the media upload multipart via node fetch: FormData + Blob from node 18+. Node 23 has fetch + FormData + File/Blob globals. Good. Actually — hold on. Let me reconsider: remote seed through the API triggers rebuilds (3 createPost publishes + media upload) — that's fine and actually demonstrates the pipeline. But timing: rebuild debounce 10s. It'll coalesce. Fine. But there's a wrinkle: the deployed worker's seed will also need the media URL. uploadMedia returns the media with url (R2 public URL). Good. Let me also double-check: `wrangler r2 object put` — for the seed I'm going through the API so no direct R2 needed. Good, simpler. ### R2 public URL for media For media to be publicly viewable (media grid in admin shows images; export includes bytes), we need the R2 bucket public URL. Options: r2.dev subdomain (PUBLIC_MEDIA_URL) like C, or custom domain (not allowed per YAGNI). r2.dev public access: create bucket, enable public access (via dashboard or API), get the r2.dev URL. C used `https://pub-1ac471f5152841799441e28de7c27e35.r2.dev`. I'll enable public access for leoblog-f-media and get its r2.dev URL. This can be done via API: `PUT /accounts/{account_id}/r2/buckets/{bucket}/custom_headers`? No. Public access for r2.dev: there's an endpoint `POST /accounts/{acct}/r2/buckets/{bucket}/public_access`? Let me recall... Actually Cloudflare R2 public bucket access: you can set via dashboard "Allow public access" or via API? There's `wrangler r2 bucket get`... Hmm. I recall the API: `PUT /accounts/{account_id}/r2/buckets/{bucket_name}/public_access` isn't public API. Actually there IS: r2.dev access control changed — newer API: `POST /accounts/{account_id}/r2/buckets/{bucket}/public_access` with body `{"enabled": true}`? Let me just test with curl during deployment. Alternatively, serve media through the worker itself! The worker can serve media at `/media/{key}` by reading from R2 and returning bytes. That avoids needing public bucket access entirely and keeps everything under the worker domain. That's actually cleaner: `GET /media/{filename}` → bucket.get → return with content-type. And media url stored as `${PUBLIC_API_URL}/media/${filename}`. For local dev, serve from uploads/ (static). Yes! Let me do that: media served via worker route `GET /media/*`. Then PUBLIC_MEDIA_URL = PUBLIC_API_URL. This removes the r2.dev dependency. Nice and self-contained. In worker.ts add route; in index.ts (node) serve uploads statically at /media. Hmm, C used a separate PUBLIC_MEDIA_URL var. I'll use a `MEDIA_BASE` derived from PUBLIC_API_URL + "/media". Actually let me store the full URL in media.url at upload time: `${PUBLIC_API_URL}/media/${filename}`. For local dev PUBLIC_API_URL=http://localhost:8790, and node serves /media/* from uploads. For worker, PUBLIC_API_URL=https://leoblog-f-api....workers.dev and worker serves /media/* from R2. Clean. ### Rate limiting Shared spec: "幂等/限流放中间件". Simple rate limit for agent API. I'll implement a trivial in-memory per-IP or global token-bucket in the worker. Since "简单限流即可" — I'll do a simple per-IP sliding window stored... in-memory (per isolate) is simplest; document that it's best-effort. Add `X-RateLimit-Limit/Remaining` headers maybe. Actually for a prototype, I'll implement a tiny in-memory limiter on mutation endpoints (e.g. 60 req/min per IP) with agent_hints on 429. Keep it minimal. Hmm, in-memory per-isolate rate limiting is flaky but acceptable per "简单限流即可". I'll note it. Actually let me keep it very simple: a global sliding window per (auth identity) with 100 mutations/min. Enough to demonstrate the concept; not load-bearing. ### Let me now check versions of graphql-yoga and compatibility graphql-yoga v5 works with workers (fetch API). Dependencies: graphql, graphql-yoga, hono, jose, marked, fflate, spark-md5, better-sqlite3 (node only), @hono/node-server. And a YAML lib for... no, export writes YAML manually (frontmatter). DoD 9: frontmatter parseable by PyYAML — my yamlString approach in C works. Keep same approach (write my own). For the SDL self-description I need `printSchema` from 'graphql'. Fine. graphql-yoga version: latest v5.x. Let me use ^5. graphql ^16. These run in workers (yoga has no node deps by default; need to ensure no `process` usage — yoga v5 is worker-compatible). marked: v15 works in workers (pure JS). spark-md5 works. jose works. fflate works. Astro: v4 (like C) with @astrojs/react, react 18. Let me also consider: better-sqlite3 needs native build. It's installed in route C's node_modules already, so it should install fine on this machine (Node 23). Let me verify by checking if route-c's node_modules has it built. I'll trust npm install works (route C already did it). ### Deployment steps 1. `wrangler d1 create leoblog-f-db` → get database_id 2. `wrangler r2 bucket create leoblog-f-media` 3. Local: npm install 4. Build + typecheck api 5. Migrate remote: `wrangler d1 execute leoblog-f-db --remote --file=schema.sql` 6. Deploy worker with secrets: ADMIN_PASSWORD, JWT_SECRET, API_TOKEN (wrangler secret put), vars in wrangler.toml: ADMIN_USER, PUBLIC_API_URL (worker URL), PAGES_PROJECT_NAME=leoblog-f-web, PAGES_SITE_URL, PAGES_BRANCH, plus pages rebuild secrets (PAGES_REBUILD_API_TOKEN, PAGES_REBUILD_ACCOUNT_ID) via secret put. Also OPENAI_* optional (not configured → agent_hints path). 7. Build web with PUBLIC_API_URL=https://leoblog-f-api.<sub>.workers.dev 8. `wrangler pages project create leoblog-f-web --production-branch main` then `wrangler pages deploy dist` 9. Seed remote via API script 10. Online smoke tests Worker subdomain: wrangler workers_dev=true → URL https://leoblog-f-api.<account-subdomain>.workers.dev. The account subdomain is visible in `wrangler whoami` — C used `dalicuqiji.workers.dev` for leoblog-api. So my worker will be `leoblog-f-api.dalicuqiji.workers.dev`. But note: PUBLIC_API_URL must be known BEFORE building the web (Astro build pulls from it). So: create D1, migrate, deploy worker (get URL), then build web with that URL, then deploy pages. Also the worker's wrangler.toml var PUBLIC_API_URL should be the same. And PAGES_SITE_URL = https://leoblog-f-web.pages.dev. Also the rebuild pipeline needs PAGES_REBUILD_API_TOKEN (the CF token — I'll use the provided CLOUDFLARE_API_TOKEN) and PAGES_REBUILD_ACCOUNT_ID (c5260698746cd322513744d6e420fb1c). These are secrets → wrangler secret put PAGES_REBUILD_API_TOKEN. Note: the CF token has permissions? It's the user's token for this account; C's pages-rebuild used it. Should work for pages API. ### Now let me think about potential pitfalls 1. **graphql-yoga + Hono on workers**: yoga.fetch(request) returns Response. Hono `app.all('/graphql', (c) => yoga.fetch(c.req.raw))`. Need to also handle OPTIONS/CORS — yoga handles CORS itself via cors option. Set `cors: true` (default allows same origin; I'll set cors option to allow all: `cors: { origin: '*' }`). Admin SPA on pages.dev calls workers.dev/graphql cross-origin → need CORS. Enable yoga cors for all origins with credentials false. Actually yoga's default CORS config: `cors: { origin: request.headers.get('origin') ?? '*' }`? Let me set `cors: { origin: '*', allowHeaders: ['Content-Type','Authorization'], credentials: false, methods: ['POST','GET','OPTIONS'] }`. Hmm credentials:false required if origin '*'. Good. 2. **Upload scalar + multipart**: verify yoga version supports it. graphql-yoga v5 supports `Upload` scalar by importing `GraphQLUpload` from 'graphql-yoga'. I'll test locally. 3. **waitUntil in worker**: runtime.executionCtx holds ExecutionContext from worker fetch. triggerRebuild uses it. 4. **The rebuild must render F-specific HTML** matching the F Astro frontend (different branding: "LeoBlog · GraphQL 契约即文档", different CSS maybe). I'll keep similar layout. 5. **Local dev DB**: better-sqlite3 + schema.sql applied on startup? I'll make migrate.ts apply schema.sql to the local sqlite (exec multiple statements). better-sqlite3 `.exec()` runs multiple statements. Good. 6. **Chinese content in SQL schema.sql**: CREATE TABLE only, no data. Seed.ts handles data. Good. 7. **Timestamps**: unix seconds like C. 8. **Astro build fetching GraphQL**: if API not reachable at build → build fails. For local build, ensure API running. For prod, deployed worker. The build script should set PUBLIC_API_URL. Let me now also handle: the DoD item 1 "干净环境一条命令起本地 dev". README: `npm install && npm run dev` (root). I'll add a root script that runs migrate + seed automatically? "一条命令起本地 dev" — I'll make `npm run dev` just start both; and document `npm run setup` for migrate+seed. Or make a single `npm start`? I'll document: `npm install` then `npm run dev` (both api+web). And `npm run db:setup` (migrate+seed) as a separate step since seed isn't "dev". Actually to be safe: root scripts: ``` "dev": "npm-run-all --parallel dev:api dev:web", "dev:api": "npm run dev -w @leoblog/api", "dev:web": "npm run dev -w @leoblog/web", "db:setup": "npm run db:migrate -w @leoblog/api && npm run seed -w @leoblog/api", "build": "npm run build -w @leoblog/api && npm run build -w @leoblog/web", ``` The dev:api script should auto-apply migrations? tsx watch src/index.ts — at startup, index.ts can auto-run schema.sql (CREATE TABLE IF NOT EXISTS) — idempotent. That way `npm run dev` works from clean env without separate migrate. I'll make index.ts apply schema.sql at boot (exec IF NOT EXISTS). And seed separately. So "一条命令起本地 dev" = `npm install && npm run dev`, then `npm run seed`. Good enough; README documents. 9. **The `.env` file** for local dev: contains ADMIN_USER, ADMIN_PASSWORD, JWT_SECRET, API_TOKEN, PUBLIC_API_URL=http://localhost:8790, PORT, DATABASE_PATH. NOT the CF token (never write CF token to files). Local dev creds are dev-only (admin/admin123? The shared spec DoD just needs to work). I'll use strong-ish dev creds but for local it's fine to use simple ones. Actually for the deployed version, secrets are set via wrangler secret. Let me generate strong random values for ADMIN_PASSWORD/JWT_SECRET/API_TOKEN and use them in BOTH local .env AND as deployed secrets (same creds → consistent). The task says "生成强随机 ADMIN_PASSWORD/JWT_SECRET/API_TOKEN 记录在报告". So generate strong random strings, put in local .env, and use the same for remote secrets. Then README can reference them? The task says record in report. I'll record them in the final report and README (it's a prototype; but the instruction "绝不写入文件/输出" was only about CF 凭证. The ADMIN_PASSWORD etc. should be recorded in the report per instruction). I'll put dev creds in local .env (needed for local dev) and deploy the same as secrets. And record in report. Hmm — but writing secrets to .env file... The instruction only forbids writing CF credentials to files. ADMIN_PASSWORD/JWT_SECRET/API_TOKEN are meant to be recorded. .env is gitignored anyway. OK. Actually, let me generate the secrets and put them in the local .env and report. For remote, use `wrangler secret put` with the same values. 10. **KV IDEMPOTENCY_F**: I decided D1 table. Skip KV namespace creation. Let me also reconsider `openapiMeta`. Since we deliberately don't do OpenAPI, `openapiMeta` returns JSON about the API. I'll make it return: ```json { "name": "leoblog-f-api", "version": "1.0.0", "spec": "GraphQL", "endpoint": "/graphql", "sdlEndpoint": "/graphql?sdl", "auth": "Authorization: Bearer <API_TOKEN> or session JWT from login()", "nonGraphqlEndpoints": { "/export": "GET zip export", "/view/{slug}": "POST view beacon" }, "idempotency": "createPost/publish/uploadMedia take idempotencyKey argument", "hateoas": "Post._links provides resource-action URLs", "errorFormat": "errors[].extensions.agent_hints {retry_allowed, suggested_action}", "audit": "mutation writes audit_logs with actor/subject/via" } ``` This gives agents a machine-readable API meta via GraphQL. Now let me write everything. Let me start scaffolding. I'll create files. Let me be careful about npm versions. I'll pin roughly to C's versions for things that worked: - hono ^4.6 - @hono/node-server ^1.13 - better-sqlite3 ^11 - jose ^5 - marked ^15 - fflate ^0.8 - spark-md5 ^3 - graphql ^16.9 - graphql-yoga ^5.10 - tsx, typescript, @types/node, @cloudflare/workers-types, wrangler ^3 - astro ^4.16, @astrojs/react ^3.6, react ^18, @types/react Let me check latest graphql-yoga version compatibility with graphql 16. graphql-yoga 5 requires graphql >=16. Good. Let me verify npm registry access and start creating the project. First the directory structure. Let me write out all the code now. I'll create files systematically. First, root package.json, .gitignore, .env. Then apps/api: package.json, tsconfig.json, wrangler.toml, schema.sql, src files. Then apps/web: package.json, astro.config.mjs, tsconfig.json, src files. Then README.md at end. Let me start. #### schema.sql ```sql CREATE TABLE IF NOT EXISTS posts ( id INTEGER PRIMARY KEY AUTOINCREMENT, slug TEXT NOT NULL UNIQUE, title TEXT NOT NULL, content TEXT NOT NULL, summary TEXT, status TEXT NOT NULL DEFAULT 'draft', views INTEGER NOT NULL DEFAULT 0, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, published_at INTEGER ); CREATE TABLE IF NOT EXISTS tags ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL UNIQUE, slug TEXT NOT NULL UNIQUE ); CREATE TABLE IF NOT EXISTS post_tags ( post_id INTEGER NOT NULL REFERENCES posts(id) ON DELETE CASCADE, tag_id INTEGER NOT NULL REFERENCES tags(id) ON DELETE CASCADE, PRIMARY KEY (post_id, tag_id) ); CREATE TABLE IF NOT EXISTS media ( id INTEGER PRIMARY KEY AUTOINCREMENT, filename TEXT NOT NULL, url TEXT NOT NULL, content_type TEXT NOT NULL, size INTEGER NOT NULL, created_at INTEGER NOT NULL ); CREATE TABLE IF NOT EXISTS audit_logs ( id INTEGER PRIMARY KEY AUTOINCREMENT, action TEXT NOT NULL, resource TEXT NOT NULL, actor_id TEXT NOT NULL, subject_id TEXT NOT NULL, via TEXT NOT NULL DEFAULT 'graphql', created_at INTEGER NOT NULL ); CREATE TABLE IF NOT EXISTS idempotency ( id INTEGER PRIMARY KEY AUTOINCREMENT, key TEXT NOT NULL UNIQUE, response_hash TEXT NOT NULL, response_json TEXT NOT NULL, created_at INTEGER NOT NULL ); CREATE TABLE IF NOT EXISTS rebuild_state ( id INTEGER PRIMARY KEY AUTOINCREMENT, key TEXT NOT NULL UNIQUE, last_triggered_at INTEGER NOT NULL, last_triggered_by TEXT, triggered_count INTEGER NOT NULL DEFAULT 0, updated_at INTEGER NOT NULL ); CREATE INDEX IF NOT EXISTS idx_posts_status ON posts(status); CREATE INDEX IF NOT EXISTS idx_post_tags_post ON post_tags(post_id); CREATE INDEX IF NOT EXISTS idx_post_tags_tag ON post_tags(tag_id); CREATE INDEX IF NOT EXISTS idx_audit_created ON audit_logs(created_at); ``` #### DB layer db/types.ts — a generic query interface: ```ts export interface Row { [k: string]: unknown } export interface Queryable { all<T = Row>(sql: string, params?: unknown[]): Promise<T[]> get<T = Row>(sql: string, params?: unknown[]): Promise<T | undefined> run(sql: string, params?: unknown[]): Promise<{ changes: number }> exec(sql: string): Promise<void> } ``` Hmm, `get` returning single row. better-sqlite3 `.get()` returns row or undefined. D1 `.first()` returns row or null. Adapt. db/node.ts: ```ts import Database from 'better-sqlite3' ... class NodeQueryable implements Queryable { private db: Database.Database constructor(path) { this.db = new Database(path); this.db.pragma('journal_mode = WAL'); this.db.pragma('foreign_keys = ON') } async all(sql, params=[]) { return this.db.prepare(sql).all(...params) as Row[] } async get(sql, params=[]) { return this.db.prepare(sql).get(...params) as Row|undefined } async run(sql, params=[]) { const r = this.db.prepare(sql).run(...params); return { changes: r.changes } } async exec(sql) { this.db.exec(sql) } close() { this.db.close() } } ``` db/worker.ts: ```ts import type { Queryable } from './types' export function d1Queryable(d1: D1Database): Queryable { return { async all(sql, params=[]) { const { results } = await d1.prepare(sql).bind(...params).all(); return results as Row[] }, async get(sql, params=[]) { const row = await d1.prepare(sql).bind(...params).first(); return (row as Row) ?? undefined }, async run(sql, params=[]) { const { meta } = await d1.prepare(sql).bind(...params).run(); return { changes: meta?.changes ?? 0 } }, async exec(sql) { await d1.exec(sql) }, } } ``` Wait, D1 `.bind()` with no params — `d1.prepare(sql).bind()` works (bind with zero args). Fine. Then a portable `db` facade via AsyncLocalStorage runtime: ```ts // lib/runtime.ts export interface RuntimeContext { db: Queryable; storage: StorageAdapter; env: Env; executionCtx?: { waitUntil?: (p: Promise<unknown>) => void } } const als = new AsyncLocalStorage<RuntimeContext>() export function runWithRuntime<T>(rt, fn): T { return als.run(rt, fn) } export function runtime(): RuntimeContext { ... } ``` And `db` facade: ```ts // db/index.ts import { runtime } from '../lib/runtime' export const db: Queryable = new Proxy({} as Queryable, { get: (t, p) => (runtime().db as any)[p] }) ``` Same pattern as C. But for the local migrate/seed scripts that run outside ALS... I'll wrap them in runWithRuntime. Seed scripts construct their own queryable directly. Actually, to avoid the ALS complexity in scripts, seed.ts will create a local NodeQueryable directly and use service functions? Services use the `db` facade → needs runtime context. So scripts must run within runWithRuntime. That's fine (C did the same). Hmm wait, there's an issue with the Proxy facade + async methods: `db.all(...)` → proxy get returns runtime().db.all (bound method of real object). Since runtime().db is a plain object (not class), the method access `runtime().db.all` preserves `this`? When you call `db.all(...)` where db is the proxy, the get handler returns `runtime().db.all` (a function value), and calling it as `db.all(...)` — the `this` inside will be the proxy (since method call syntax on proxy). Then inside `all`, it does `this.db.prepare(...)` — this is proxy → proxy get 'db' → runtime().db.db → undefined! Problem. In C, they used drizzle objects where methods were arrow-ish or the proxy forwarding worked because they used `db.select()` (returns statement chain, not relying on `this`). For my raw Queryable class methods that use `this.db`, proxy method calls break. Solution: bind methods when wrapping, or use a context object. Options: a) In the Proxy get handler, return the method wrapped with `.bind(realDb)`. ```ts const handler = { get(t, prop) { const real = runtime().db const v = (real as any)[String(prop)] return typeof v === 'function' ? v.bind(real) : v } } ``` That fixes `this`. Good. I'll do that. Actually simpler: make Queryable implementations not rely on `this`. e.g. NodeQueryable.all uses a stored db field. Binding in the proxy is the cleanest. I'll do bind. Alternatively, skip the proxy and have services import a `getDb()` that returns runtime().db each call: ```ts export function getDb(): Queryable { return runtime().db } ``` Then `const db = getDb()` inside each service function and use it. That's explicit and avoids proxy magic. I'll do that — cleaner and less magical. Services: `import { getDb } from '../db'`. Each function: `const db = getDb()`. Same for env: `getEnv()` or env proxy. I'll do `currentEnv()` returning runtime().env. For storage: `getStorage()`. OK. Let me define the services now. #### services/auth.ts ```ts import { SignJWT, jwtVerify } from 'jose' import { currentEnv } from '../lib/env' export type AuthIdentity = { kind: 'anonymous' actorId: string subjectId: string } | { kind: 'session' | 'agent' actorId: string subjectId: string username: string } export async function resolveAuth(authHeader: string | undefined): Promise<AuthIdentity> { const token = authHeader?.startsWith('Bearer ') ? authHeader.slice(7).trim() : null const env = currentEnv() if (token && env.API_TOKEN && token === env.API_TOKEN) { return { kind: 'agent', actorId: 'agent', subjectId: env.ADMIN_USER, username: 'agent' } } if (token) { try { const { payload } = await jwtVerify(token, new TextEncoder().encode(env.JWT_SECRET)) const username = (payload.sub as string) ?? 'unknown' return { kind: 'session', actorId: `session:${username}`, subjectId: username, username } } catch { /* fallthrough */ } } return { kind: 'anonymous', actorId: 'anonymous', subjectId: '' } } export function isAuthenticated(id: AuthIdentity): boolean { return id.kind === 'agent' || id.kind === 'session' } export async function issueSessionToken(username: string): Promise<string> { const env = currentEnv() return await new SignJWT({ sub: username, role: 'admin', type: 'session' }) .setProtectedHeader({ alg: 'HS256' }) .setIssuedAt() .setExpirationTime('12h') .sign(new TextEncoder().encode(env.JWT_SECRET)) } export async function verifyLogin(username, password): Promise<boolean> { const env = currentEnv() return username === env.ADMIN_USER && password === env.ADMIN_PASSWORD } ``` #### services/posts.ts Post operations with SQL. serializePost converts row to GraphQL Post (with tags, _links, ISO dates). Let me write: ```ts export interface PostRow { id, slug, title, content, summary, status, views, created_at, updated_at, published_at } export function slugify(input) {...} export async function findPostBySlug(slug): Promise<PostRow | undefined> export async function findPostById(id): Promise<PostRow | undefined> export async function listPosts(opts: { status?: 'draft'|'published'|'all', tag?: string, page?: number, perPage?: number, authed?: boolean }): Promise<{ posts, total, page, perPage, totalPages }> export async function createPost({ slug, title, content, summary, status, tags }): Promise<PostRow> export async function updatePost(slug, patch): Promise<PostRow> export async function deletePost(slug): Promise<boolean> export async function setStatus(slug, status): Promise<PostRow> export async function tagsForPost(postId): Promise<Tag[]> export async function ensureTags(names): Promise<number[]> // returns tag ids export async function attachTags(postId, tagIds) export async function replacePostTags(postId, tagNames): Promise<Tag[]> export async function addView(slug) ``` Serialization to GraphQL shape: ```ts export function serializePost(row, tags, apiBase?): Post ``` Post fields per SDL: slug, title, content, summary, status (enum: DRAFT|PUBLISHED), tags: [Tag], createdAt, publishedAt, views? (SDL doesn't have views... but stats topViewed shows views. I'll include views in Stats item but not Post? The SDL Post doesn't have views. Keep SDL as handoff — no views in Post. But admin might want to show views... not required. Keep minimal per handoff.) Wait, SDL Post: `{ slug title content summary status tags createdAt publishedAt _links }`. OK no views. _links: PostLinks { publish, unpublish, delete, edit }. These are HATEOAS links. What do they point to? In a pure GraphQL facade, there are no REST URLs for these actions. Hmm. The handoff maps HATEOAS into GraphQL via _links. The links could be the "graphql operation descriptors" — e.g. publish: "mutation publish(slug: \"...\")" or a URL to the endpoint with a hint. Since DoD 7 says "GET 文章返回 _links" — the _links must be present. I'll make them strings describing the GraphQL operation + slug, e.g.: - publish: `graphql://mutation.publish?slug=<slug>` or better: a human/agent-readable string. I think the cleanest: _links.publish = the GraphQL mutation text? That could be long. Alternatively, represent as the mutation operation name + argument: `mutation{publish(slug:"x", idempotencyKey:"<gen>")}`. Hmm. Let me look at the SDL again: `type PostLinks { publish: String unpublish: String delete: String edit: String }`. Just strings. I'll make them actionable GraphQL operation descriptors: - publish: `publish(slug:"<slug>", idempotencyKey:"<generate>")` - unpublish: `unpublish(slug:"<slug>")` - delete: `deletePost(slug:"<slug>")` - edit: `updatePost(slug:"<slug>", input:{...})` These are literally executable GraphQL snippets (agent can copy into a mutation). That's a nice interpretation: HATEOAS in GraphQL = self-describing operation templates. I'll generate e.g. `mutation { publish(slug: "my-post", idempotencyKey: "<new-uuid>") { slug title } }`. That's genuinely actionable. Let me build them as strings. This is defensible and creative. Document in README. Actually, simpler and still meaningful: provide the operation name + the endpoint (since it's single endpoint, all point to /graphql). Let me do templates as above. #### services/audit.ts ```ts export async function logAudit(action, resource, identity, via='graphql') { const db = getDb() await db.run(`INSERT INTO audit_logs (action, resource, actor_id, subject_id, via, created_at) VALUES (?,?,?,?,?,?)`, [action, resource, identity.actorId, identity.subjectId, via, nowSec()]) } export async function listAuditLogs(limit=50): Promise<AuditRow[]> { return getDb().all(`SELECT * FROM audit_logs ORDER BY created_at DESC, id DESC LIMIT ?`, [limit]) } ``` #### services/idempotency.ts ```ts export async function withIdempotency<T>(key, operation: string, fn: () => Promise<T>): Promise<T> { if (!key || typeof key !== 'string' || key.length < 4) throw validation error const db = getDb() const existing = await db.get<IdemRow>(`SELECT * FROM idempotency WHERE key = ?`, [key]) if (existing) { // replay exact result if (existing.operation !== operation) → conflict? For simplicity: if op mismatch, still return stored? Better: return stored regardless (document). return JSON.parse(existing.response_json) as T } const result = await fn() const json = JSON.stringify(result) try { await db.run(`INSERT INTO idempotency (key, operation, response_hash, response_json, created_at) VALUES (?,?,?,?,?)`, [key, operation, md5(json), json, nowSec()]) } catch (e) { // unique conflict — another isolate won; return its stored result const row = await db.get(`SELECT * FROM idempotency WHERE key = ?`, [key]) if (row) return JSON.parse(row.response_json) throw e } return result } ``` md5: I have spark-md5 for the pages rebuild. I can use it here too, or a simple hash. response_hash = spark-md5 of json. Fine. Add `operation` column? The spec table is idempotency(key,response_hash,created_at). I'll keep just those + response_json. operation not needed. Keep spec-minimal: key, response_hash, response_json, created_at. Validation error for missing key: The SDL makes idempotencyKey required (String!), so GraphQL layer catches missing. Good — no need for custom validation in service. But empty string is possible → treat as missing → error with agent_hints. I'll validate in resolver/service: if !key.trim() → throw ValidationError. Actually since it's required non-null in SDL, but could be "" — check in service, throw error with hints. Fine. #### services/tags.ts ```ts export async function listAllTags(): Promise<Tag[]> // ordered by name export async function createTag(name): Promise<Tag> export async function renameTag(id, name): Promise<Tag> export async function deleteTag(id): Promise<boolean> ``` Tag = { id, name, slug }. #### services/media.ts ```ts export async function listMedia() export async function createMedia({filename, url, contentType, size}) export async function deleteMedia(id): Promise<boolean> // also delete from storage export async function uploadMedia(file: File): Promise<Media> // uses storage adapter saveBuffer ``` storage adapter: ```ts interface StorageAdapter { saveBuffer(data: Uint8Array, contentType: string): Promise<{ filename: string; url: string; contentType: string; size: number }> deleteFile(filename: string): Promise<void> readFile(filename: string): Promise<Uint8Array> serve(request: Request): Promise<Response | null> // media serving } ``` Hmm serve is node/worker-specific. Let me keep serve out of the adapter; instead have a `getMediaObject(filename): Promise<{data, contentType} | null>`. storage/local.ts: files under uploads/; url = `${PUBLIC_API_URL}/media/${filename}`. Actually at upload time we need PUBLIC_API_URL to build url. Let me have the media service build the URL: `const base = currentEnv().PUBLIC_API_URL.replace(/\/+$/,'')`; url = `${base}/media/${filename}`. The storage adapter returns filename only; media service constructs URL. Cleaner. storage/r2.ts: same but bucket.put/get/delete. serve media: - node entry: `app.get('/media/*', serveStatic uploads)`. - worker: route `app.get('/media/:filename', ...)` reads R2. #### services/stats.ts ```ts export async function getStats() { // counts via SQL return { postCount, publishedCount, draftCount, tagCount, mediaCount, totalViews, topViewed } } ``` #### services/export.ts fflate zipSync. Build posts/*.md + media/. Same as C (rewrite). #### services/ai.ts OpenAI-compatible, same as C (rewrite). Returns { summary, tags } or null if not configured. #### services/render.ts HTML renderer mirroring Astro pages for rebuild. I'll write basePage + postItem + index/posts/tags render functions, matching the F frontend styling. And a `renderMarkdown` using marked. #### services/rebuild.ts + pages-rebuild.ts Reuse C architecture, rewritten: - DEBOUNCE_MS = 10_000 - rebuildState table (already in schema) - triggerRebuild(source): debounce + performPagesRebuild + optional hook. Use runtime().executionCtx?.waitUntil. - performPagesRebuild: buildSiteFiles() → render from DB (published posts, tags) → fetchLiveAssets from PAGES_SITE_URL → uploadToPages (direct upload API). - view beacon URL inside rendered pages points to `${PUBLIC_API_URL}/view/${slug}`. #### GraphQL schema.ts Handwritten SDL with descriptions. Let me write the full SDL: ```graphql """ 单一 GraphQL 端点契约（Route F）。Schema 即文档： 本博客所有读写能力都通过这一个端点暴露。 """ schema { query: Query mutation: Mutation } """文章状态""" enum Status { DRAFT PUBLISHED } """标签""" type Tag { """数据库主键""" id: Int! """标签显示名""" name: String! """标签 slug（用于 URL）""" slug: String! } """文章""" type Post { """URL 友好的唯一标识""" slug: String! """标题""" title: String! """Markdown 正文""" content: String! """摘要（列表页展示，可为空）""" summary: String """发布状态""" status: Status! """所属标签""" tags: [Tag!]! """创建时间（ISO8601）""" createdAt: String! """发布时间（ISO8601，草稿为 null）""" publishedAt: String """HATEOAS：本资源的可执行 GraphQL 操作模板""" _links: PostLinks! } """文章的 HATEOAS 链接（可执行的 GraphQL mutation 模板）""" type PostLinks { """发布模板""" publish: String! """撤回模板""" unpublish: String! """删除模板""" delete: String! """编辑模板""" edit: String! } """文章分页结果""" type PostPage { posts: [Post!]! total: Int! page: Int! perPage: Int! totalPages: Int! } """文章输入""" input PostInput { title: String! content: String! summary: String slug: String status: Status tags: [String!] } """媒体文件""" type Media { id: Int! filename: String! url: String! contentType: String! size: Int! createdAt: String! } """统计面板数据""" type Stats { postCount: Int! publishedCount: Int! draftCount: Int! tagCount: Int! mediaCount: Int! totalViews: Int! topViewed: [ViewedPost!]! } """访问最多的文章""" type ViewedPost { id: Int! title: String! slug: String! views: Int! } """AI 摘要生成结果""" type SummaryResult { summary: String! tags: [String!]! configured: Boolean! message: String } """登录结果""" type AuthPayload { token: String! username: String! } """审计日志条目（双轨审计，Agent 可查询）""" type AuditLog { id: Int! action: String! resource: String! actorId: String! subjectId: String! via: String! createdAt: String! } """任意 JSON 值""" scalar JSON type Query { """已发布文章列表（分页，可按状态/标签过滤）""" posts(status: Status, tag: String, page: Int): PostPage! """按 slug 取单篇文章（草稿需鉴权）""" post(slug: String!): Post """全部标签""" tags: [Tag!]! """统计面板""" stats: Stats! """媒体列表（需鉴权）""" media: [Media!]! """审计日志（需鉴权，Agent 可验证双轨审计）""" auditLogs(limit: Int): [AuditLog!]! """API 元信息（本端点的自描述 meta）""" openapiMeta: JSON! } type Mutation { """登录（人类会话，返回短期 JWT）""" login(username: String!, password: String!): AuthPayload! """创建文章（幂等：idempotencyKey 重复返回同一结果）""" createPost(input: PostInput!, idempotencyKey: String!): Post! """更新文章""" updatePost(slug: String!, input: PostInput!): Post! """删除文章""" deletePost(slug: String!): Boolean! """发布文章（幂等）""" publish(slug: String!, idempotencyKey: String!): Post! """撤回文章""" unpublish(slug: String!): Post! """生成 AI 摘要（未配置时 configured=false + agent_hints）""" generateSummary(slug: String!): SummaryResult! """上传媒体（幂等，multipart GraphQL Upload）""" uploadMedia(idempotencyKey: String!, file: Upload!): Media! """删除媒体""" deleteMedia(id: Int!): Boolean! """创建标签""" createTag(name: String!): Tag! """重命名标签""" renameTag(id: Int!, name: String!): Tag! """删除标签""" deleteTag(id: Int!): Boolean! } """文件上传（graphql-multipart-request 规范）""" scalar Upload ``` That's the full SDL. Now DoD 5: SDL contains all Query/Mutation with descriptions. I'll also add descriptions to args? "全部 Query/Mutation 与字段描述" — fields have descriptions. Args with descriptions would be nicer. GraphQL SDL supports arg descriptions: `createPost(input: PostInput! ... )`. Hmm, args in SDL get descriptions via the arg's own description above it in the arg list. For printed SDL from printSchema, arg descriptions are included if provided. I'll add descriptions to args in some places (at least mutation args). Actually that's a lot of verbosity. "包含全部 Query/Mutation 与字段描述" — I interpret as every type field has a description. Args optional. But to be thorough for Agent-friendliness, I'll add arg descriptions too where meaningful. Let me include arg descriptions for the mutation args (idempotencyKey, slug, input). I'll write them. Wait — there's a subtlety with `scalar JSON` and `scalar Upload` — I must implement both scalar types. JSON: custom scalar. Upload: GraphQLUpload from graphql-yoga. Also note: I should NOT use the `schema { }` block necessarily; printSchema handles it. I'll just define types; printSchema emits schema block automatically. For resolvers, I'll write a resolver map keyed by type/field. Since SDL is written as string, I build schema via `buildSchema` + `addResolvers`? That loses descriptions? No — buildSchema parses SDL including descriptions. But then attaching resolvers via map requires `addResolversToSchema`. Alternatively, write the schema using the schema-builder from SDL string and resolvers map: `makeExecutableSchema` from @graphql-tools/schema — that's a standard approach but adds a dep. graphql-yoga itself doesn't include makeExecutableSchema. I can use `buildSchema(sdl)` then `addResolversToSchema({ schema, resolvers })` from '@graphql-tools/schema'. That adds @graphql-tools/schema dep (with graphql-tools codegen deps... it's fine, it's what most projects use). Alternatively, define schema in code using GraphQLSchema/GraphQLObjectType etc. — verbose but no extra deps, and printSchema(schema) still emits the SDL with descriptions. That's actually quite clean and avoids @graphql-tools entirely: hand-written type definitions in code with descriptions. But the handoff says "手写 SDL + yoga" — meaning SDL as string. Hmm. "schema 用 SDL 或 graphql-codegen 之类不要——手写 SDL + yoga，最小心智". So hand-written SDL string + yoga. To use a string SDL with yoga, I need to attach resolvers. Options: 1. `makeExecutableSchema` (@graphql-tools/schema) — string SDL + resolver map. Most standard. 2. `buildSchema` + custom `addResolversToSchema` — same library. 3. Use graphql-yoga's `useSchema`? No. I'll use @graphql-tools/schema `makeExecutableSchema`. It's one extra dependency, well-established. The SDL stays hand-written as a string (single source of truth for the contract) and the resolver map is typed. For the SDL endpoint, `printSchema(makeExecutableSchema(...))` returns the normalized SDL including descriptions. Now, note `makeExecutableSchema` with `resolvers` where resolvers access context. GraphQL context passed to resolvers: (parent, args, context, info). context will contain { identity } (auth). Services access db/storage/env via runtime() ALSand runtime.executionCtx. But wait — the ALS runtime context is set in the hono route wrapper for EVERY request, including GraphQL. Let me make sure the ALS covers the full resolver execution. In Hono: `app.all('/graphql', (c) => runWithRuntime(rt, () => yoga.fetch(c.req.raw)))`. Since yoga.fetch is async and resolvers run inside, and ALS persists through await chains, it works (AsyncLocalStorage propagates across awaits). Good. Now — the login mutation needs to issue a JWT and verify creds — no db needed. Fine. #### Error handling + agent_hints I'll define a helper to throw GraphQL errors with extensions: ```ts import { GraphQLError } from 'graphql' export function apiError(message: string, code: string, status: number, hints: { retry_allowed: boolean; suggested_action: string }): GraphQLError { return new GraphQLError(message, { extensions: { code, http: { status }, agent_hints: hints } }) } ``` Resolvers throw these. graphql-yoga serializes extensions.http.status into the HTTP response status too (yoga reads extensions.http). Actually graphql-yoga uses `extensions.http.status` if present to set the response status code. Yes — yoga supports `extensions: { http: { status } }` to control HTTP status (via `use` or in thrown errors). Let me confirm: graphql-yoga reads `extensions.http` from errors to set response status. I recall this is supported (GraphQLYogaError with extensions.http). Yes, yoga has built-in support: "Set the status code of the response with extensions.http.status". Good. So an unauthorized mutation → HTTP 401 with JSON `{ errors: [{ message, extensions: { code: 'UNAUTHORIZED', http: { status: 401 }, agent_hints: {...} } }] }`. For validation: e.g. slug exists → 409 CONFLICT, agent_hints { retry_allowed: true, suggested_action: "Use a different slug or an idempotencyKey to replay the same create" }. For not found: 404. Let me define error codes: UNAUTHORIZED, NOT_FOUND, CONFLICT, VALIDATION, RATE_LIMITED, INTERNAL, AI_NOT_CONFIGURED. #### app.ts (Hono assembly) ```ts import { Hono } from 'hono' import { createYoga, GraphQLUpload } from 'graphql-yoga' import { schema, resolvers } from './graphql/schema' ... export function buildApp(): Hono { const app = new Hono() const yoga = createYoga({ schema: buildGraphQLSchema(), context: async ({ request }) => ({ identity: await resolveAuth(request.headers.get('authorization') ?? undefined) }), cors: { origin: '*', allowHeaders: ['Content-Type', 'Authorization'], credentials: false }, graphiql: true, // dev playground helpful }) app.get('/health', c => c.json({ ok: true })) app.all('/graphql', c => yoga.fetch(c.req.raw)) app.get('/export', handleExport) // auth via Bearer app.post('/view/:slug', handleView) app.get('/media/:filename', handleMedia) return app } ``` Wait — media serving differs node vs worker. Node serves from uploads statically; worker from R2. If I put /media route in app.ts using storage adapter's readFile, both work! Let me add `getMedia(filename)` to storage adapter and a /media/:filename route in app.ts that returns bytes. That unifies. In node, readFile reads from uploads dir. In worker, reads R2. But uploads on node: files written to uploads/. readFile reads from there. OK, so storage adapter needs readFile (already have) + getMedia returning {data, contentType}. Let me add `readMeta(filename): Promise<{contentType} | null>`. Or just read bytes and serve with content-type from the DB media row. Simpler: /media/:filename route looks up media row by filename in DB for contentType, then reads bytes. If no row, still try storage? Just require the row. Fine. Also `GET /graphql?sdl` → return SDL text. I'll handle in app.ts before yoga: ```ts app.get('/graphql', c => { if (c.req.query('sdl') !== undefined) { return c.text(printSchema(schema), 200, { 'Content-Type': 'text/plain; charset=utf-8' }) } return yoga.fetch(c.req.raw) }) ``` And `app.all('/graphql')` handles POST. Let me define `app.route('/graphql', ...)` or just two handlers: GET (with sdl special) and POST/OPTIONS. CORS: OPTIONS preflight → yoga handles? If I intercept GET myself, OPTIONS for GET still goes to yoga. Let me structure: ```ts app.get('/graphql', (c) => { if sdl → text; else yoga.fetch }) app.all('/graphql', (c) => yoga.fetch(c.req.raw)) // POST, OPTIONS, etc. ``` Order: Hono matches more specific first? Both are '/graphql'. `app.get` then `app.all` — Hono routes in registration order; GET matches the first (get handler), other methods fall to all. Should work. Hmm, actually `app.all('/graphql', ...)` would also catch GET if the get handler... no, Hono matches per-method; GET registered separately wins for GET. OK. #### Rate limiting Simple in-memory limiter: ```ts const buckets = new Map<string, { count: number; reset: number }>() const LIMIT = 120, WINDOW = 60_000 export function checkRateLimit(key: string): { ok: boolean; remaining: number; retryAfter: number } { const now = Date.now() let b = buckets.get(key) if (!b || now > b.reset) { b = { count: 0, reset: now + WINDOW }; buckets.set(key, b) } b.count++ return { ok: b.count <= LIMIT, remaining: Math.max(0, LIMIT - b.count), retryAfter: Math.max(0, Math.ceil((b.reset - now) / 1000)) } } ``` Apply to mutations (key = identity.actorId + IP). If exceeded → throw RATE_LIMITED error with agent_hints. Note in-memory is per-isolate best-effort. I'll wrap in a middleware: in app.ts, `app.use('/graphql', async (c, next) => {...})`? Simpler to enforce inside resolvers via a helper `enforceRateLimit(identity)`. I'll do it in the GraphQL context setup or a wrapper around mutation execution. Cleanest: a wrapper `withAuth(identity, mutationName, fn)` that checks auth + rate limit, then runs + audits. Actually audit is per-action. Let me create a helper in resolvers: ```ts function requireAuth(ctx, action: string, resource: string) { if (!isAuthenticated(ctx.identity)) throw apiError('Unauthorized', ...) checkRateLimit(ctx.identity.actorId) // throws RATE_LIMITED // audit after success handled by caller } ``` Let me centralize: `runMutation(ctx, { action, resource }, fn)`: ```ts async function runMutation(ctx, action, resource, fn) { if (!isAuthenticated(ctx.identity)) throw unauthorized enforceRateLimit(ctx.identity.actorId) const result = await fn() await logAudit(action, resource, ctx.identity, 'graphql') return result } ``` But some mutations are non-audited-public: login. And uploadMedia/createTag etc. audit each. This central helper keeps resolvers thin and ensures every mutation writes audit — satisfying DoD 6 and "每个 mutation resolver 调 Service 前/后写 audit_logs". For login: no auth needed, no audit? "所有写操作审计日志" — login is a write op (creates session). I'll audit login too (action=login). actor=anonymous→actually actor is the one logging in. I'll set identity manually: after successful login, audit with actorId=username, subjectId=username. Keep simple: audit login with the username. #### Now the rebuild pipeline render.ts (services) — I'll write basePage with CSS matching the F web frontend. Let me design F's frontend to have slightly different branding (to be genuinely F): "LeoBlog F · GraphQL 契约即文档". Keep same layout style (it works). I'll write render functions: renderIndexHtml, renderPostHtml (with view beacon to /view/{slug}), renderTagHtml. And an export `renderMarkdown` (marked) used by... the rebuild only. The Astro frontend also uses marked for rendering markdown in pages. pages-rebuild.ts — copy the architecture from C but write fresh: fetchLiveAssets, buildSiteFiles, uploadToPages, performPagesRebuild. Uses env vars via currentEnv(). Note: pages-rebuild runs under ALS runtime (triggered from a request). In the worker, that's fine (runtime context set by runWithRuntime). In Node (local), also fine. For buildSiteFiles, it queries db facade → needs runtime. OK since always called within a request lifecycle. One concern: rebuild in local dev — triggerRebuild fires performPagesRebuild which calls the live Pages site... but locally we don't want to rebuild remote Pages from a local edit. In local dev, PAGES_REBUILD_* secrets aren't set → uploadToPages returns null (skip). Good. But fetchLiveAssets would still fetch the production site — that's harmless (only copies admin assets). Actually in local dev we don't want any rebuild. Let me guard: in triggerRebuild, if no PAGES_REBUILD_API_TOKEN/ACCOUNT_ID configured → skip entirely (return false, warn). C did that (skips when not configured). I'll do the same: if not configured, no-op. #### seed.ts (local) Inserts media file to uploads/, 3 posts (2 published, 1 draft), tags. Uses local db directly (better-sqlite3) wrapped in runWithRuntime. Reuse C's seed content but write fresh (and adapt: no /api/posts REST in the content — use GraphQL example!). Let me craft F-specific seed content that showcases GraphQL: Post 1: "你好，世界：GraphQL 契约即文档" — talks about single endpoint, SDL self-description, HATEOAS via _links. Post 2: "用 curl 与纯 GraphQL 管理博客（Agent 实操）" — shows the GraphQL mutation examples (createPost with idempotencyKey, publish). Post 3 (draft): "一条命令启动本地开发" — dev env. Tags: ["GraphQL", "Markdown"], ["Agent", "API"], ["开发体验"]. #### seed-remote I'll write `apps/api/scripts/seed-remote.mjs` — a node script that calls the deployed worker's GraphQL endpoint: - uploadMedia via multipart - createPost x3 with idempotencyKeys (status draft/published accordingly) - publish the draft? No — keep 1 draft like local. Then it's idempotent-ish (same idempotencyKey → replay returns same, no dup). The remote seed needs the live API URL + API token. I'll pass via env vars (script reads process.env). Run: `API_URL=... API_TOKEN=... npm run seed:remote`. Actually simpler: I can reuse the local seed logic but point at remote via fetch. Let me write it as a plain .mjs using global fetch/FormData/Blob. Node 23 has these. For multipart: `new FormData()` + `new Blob([pngBytes])` + append. Good. #### Web frontend src/lib/api.ts — GraphQL client helper: ```ts export const API_URL = import.meta.env.PUBLIC_API_URL || 'http://localhost:8790' export async function gql<T>(query, variables?, token?) { ... POST /graphql, Authorization header, returns data or throws errors } ``` Functions: fetchPublishedPosts(page), fetchAllPublishedPosts(), fetchPostBySlug(slug), fetchTags(). Pages: index.astro (list + pagination), posts/[slug].astro (getStaticPaths + detail + view beacon script), tags/[slug].astro, admin/index.astro (AdminApp island). Admin island: AdminApp.tsx + api.ts (graphql client with login, listPosts, createPost, updatePost, deletePost, publish, unpublish, listTags, createTag, renameTag, deleteTag, listMedia, uploadMedia (multipart), deleteMedia, stats, aiGenerateSummary, exportZip, auditLogs maybe). Token in localStorage. Views: same admin UI as C but calling GraphQL. I'll adapt C's AdminApp to use GraphQL api. Since it's a React island client:only, I'll write fresh but similar. Given the C AdminApp is 545 lines, I'll write a comparable but somewhat trimmed version for F. Actually, the admin is a big chunk. Let me write a solid but compact AdminApp covering: login, posts (list/filter/create/edit/delete/publish/unpublish + AI), tags (CRUD), media (upload/delete), stats (counts + export). ~450 lines. Fine. For uploadMedia multipart in the SPA: use the graphql-multipart-request spec with operations/map/file. Export zip: `GET ${API_URL}/export` with Authorization header → blob download. #### Astro build pulling from GraphQL `astro build` runs getStaticPaths which calls fetchPublishedPosts → hits /graphql. Must set PUBLIC_API_URL at build. For local, PUBLIC_API_URL=http://localhost:8790 (API running). For prod deploy, PUBLIC_API_URL=https://leoblog-f-api.dalicuqiji.workers.dev. .env in apps/web for local dev. For prod, build with env var override: `PUBLIC_API_URL=https://... npm run build -w @leoblog/web`. Actually Astro reads import.meta.env.PUBLIC_* from process env at build. Set via shell or .env. I'll document both; for deploy I'll run with env override. Wait — but there's a subtlety: if I commit .env with PUBLIC_API_URL=http://localhost:8790, then the prod build must override. I'll pass PUBLIC_API_URL explicitly in the deploy build command (env vars override .env in Astro? Astro loads .env files but process.env takes precedence? Actually Astro's env: `import.meta.env.PUBLIC_X` reads from process.env AND .env; process.env should win. Let me confirm: Astro uses Vite's env loading; Vite loads .env files, and existing process.env vars take precedence (they're not overwritten). Yes, process env wins. So passing PUBLIC_API_URL explicitly works.) For the F web, I should NOT commit a prod URL in .env. Local .env has localhost. Good. #### wrangler.toml ```toml name = "leoblog-f-api" main = "src/worker.ts" compatibility_date = "2024-11-01" compatibility_flags = ["nodejs_compat"] workers_dev = true [vars] ADMIN_USER = "admin" PUBLIC_API_URL = "https://leoblog-f-api.dalicuqiji.workers.dev" PAGES_PROJECT_NAME = "leoblog-f-web" PAGES_BRANCH = "main" PAGES_SITE_URL = "https://leoblog-f-web.pages.dev" [[d1_databases]] binding = "DB" database_name = "leoblog-f-db" database_id = "<created>" migrations_dir = "drizzle" # not used; we use schema.sql. Remove this. [[r2_buckets]] binding = "BUCKET" bucket_name = "leoblog-f-media" ``` Secrets: ADMIN_PASSWORD, JWT_SECRET, API_TOKEN, PAGES_REBUILD_API_TOKEN, PAGES_REBUILD_ACCOUNT_ID via `wrangler secret put`. Wait — PAGES_REBUILD_ACCOUNT_ID is not secret (it's the account id). Could be a var. But the token is secret. I'll put account id as var in wrangler.toml and token as secret. Actually C kept account id as secret. Either fine. I'll add PAGES_REBUILD_ACCOUNT_ID as a plain var in wrangler.toml and PAGES_REBUILD_API_TOKEN as secret. Hmm, but the account id is the same CF account. Fine as var. compatibility_flags nodejs_compat needed for AsyncLocalStorage (node:async_hooks) and crypto. crypto.randomUUID exists without flag (Web Crypto). AsyncLocalStorage needs nodejs_compat. Yes. #### Let me now check: does graphql-yoga v5 work with hono and workers? graphql-yoga is runtime-agnostic (works on any fetch). Honv integration is trivial. Yes. One thing: yoga needs `process.env.NODE_ENV`? No, it uses `graphql-yoga`'s internal. Should be fine. marked v15 in worker: pure JS, works. But marked.parse with async:false returns string. In worker fine. spark-md5: pure JS, works. fflate: pure JS. But fflate in worker — zipSync is synchronous pure JS, works. jose: works in workers (uses WebCrypto). Better than jsonwebtoken. Now let me also handle `Upload` scalar in yoga. `import { GraphQLUpload } from 'graphql-yoga'`. And resolver for uploadMedia: `file: args.file` is a File (yoga resolves the upload). In yoga v5, with multipart, the resolver receives the actual `File` object. So `const buf = new Uint8Array(await args.file.arrayBuffer())`. Also need to ensure multipart parsing enabled: yoga does it automatically when the scalar named `Upload` is in schema. Good. Let me also think about the `/export` and `/view` and `/media` routes being non-GraphQL: they're "务实取舍" documented in README (binary data and fire-and-forget beacons don't fit GraphQL). Good. #### Now — the web view beacon Static detail page posts to `${API_URL}/view/${slug}`. The rendered page (by rebuild) embeds same. And the app.ts handles POST /view/:slug → increment views. Response 204. #### Now, the "全 DoD 自测" plan (local): 1. Start API locally (node entry, better-sqlite3, auto-migrate). Seed. 2. Run curl GraphQL queries: - GET /graphql?sdl → SDL text (DoD 5) - query posts → published posts - login mutation → token - createPost with idempotencyKey → replay same key → same result (DoD 4) - publish → - updatePost, deletePost - tags CRUD - stats - auditLogs query → actor/subject/via (DoD 6) - _links in post (DoD 7) - no-token mutation → errors[].extensions.agent_hints (DoD 8) - export zip → check frontmatter parseable by PyYAML (DoD 9) - view beacon → views increment → stats 3. Browser: use a headless check via curl for the admin SPA? For local "浏览器全流程" I can use a simple automated browser (chrome-devtools-mcp is mentioned in CLAUDE.md!). But is it available here? The system prompt lists crawl4ai tools and playwright-cli skill. There's a `playwright-cli` skill and `browser-api-exploration` skill. For local verification I can build the web and check pages render. For the browser flow test, I could use curl against the GraphQL API (login etc.) + verify static pages. The handoff says DoD 3 is browser flow. I can do it locally with a headless browser if available. Let me check for playwright/chrome availability later. Alternatively, I'll use crawl4ai_scrape to scrape the local/admin? It might not reach localhost. Hmm. crawl4ai tools are for web scraping. Local pages served on localhost might work with crawl4ai_scrape("http://localhost:4321"). But the admin is a React SPA requiring JS — crawl4ai can run a browser (stealth tier). Let me try when needed. Actually for the "browser 全流程" I can rely on the GraphQL API being fully exercised (which is exactly what the SPA calls), plus the static frontend pages being built and served. I'll verify via curl that the SPA assets load and API works. For online smoke, I'll use crawl4ai to actually click through if possible. Let me first focus on implementation. Let me also check the smoke-report.json and smoke-artifacts of C for ideas on how DoD was evidenced. Let me quickly peek. Actually, let me just get building. I have a solid plan. Let me check the C smoke report quickly for the format, then start writing code. Let me look at the smoke report and the remaining C routes (tags, media, ai) to be thorough. Actually I've seen enough of C's patterns. Let me check smoke-report.json briefly for evidence format.展开全部

Now the GraphQL schema (SDL) + resolvers. This is the core. Let me write the SDL string with descriptions, then the resolver map. Let me carefully design the resolvers. Context type: ```ts interface GraphQLContext { identity: AuthIdentity request: Request } ``` Serialization helpers: serializePost(row, tags) → { slug, title, content, summary, status (DRAFT/PUBLISHED), tags: [Tag], createdAt, publishedAt, _links }. _links templates: - publish: `mutation { publish(slug: "${slug}", idempotencyKey: "<new-uuid>") { slug title } }` - unpublish: `mutation { unpublish(slug: "${slug}") { slug title } }` - delete: `mutation { deletePost(slug: "${slug}") }` - edit: `mutation { updatePost(slug: "${slug}", input: { title: "...", content: "..." }) { slug title } }` Let me generate with random uuid for idempotencyKey placeholder. Actually better a template with a placeholder token like `$IDEMPOTENCY_KEY` so agents replace it. I'll use `"<replace-with-unique-key>"`. Now resolvers. Let me write the full schema.ts. For auth: mutations require auth except login. Queries: posts/post/tags/stats are public (posts restricted to published when anonymous). media/auditLogs require auth. Rate limiting: enforce on mutations (authenticated ones) and login. Let me define runMutation helper: ```ts async function runMutation(ctx, action, resource, fn) { if (!isAuthenticated(ctx.identity)) throw unauthorized() const rl = checkRateLimit(ctx.identity.actorId) if (!rl.ok) throw rateLimited(rl.retryAfterSec) const result = await fn() await logAudit(action, resource, ctx.identity) return result } ``` For login: no auth check, but rate limit on anonymous? Rate limit login by IP. I'll pass a key = `login:${ip}`. Get IP from request headers (CF-Connecting-IP). Let me include request in context. For generateSummary: it's a mutation; uses AI; if not configured return configured=false with message. Note: generateSummary persisting summary to the post. Let me re-think: Should generateSummary write to the post? The handoff SDL: `generateSummary(slug: String!): SummaryResult!`. In C, aiSuggest was separate from save. For the admin SPA flow: user clicks "AI 生成" → gets summary+tags suggestions → user clicks save → updatePost. If generateSummary auto-persists, then the SPA's flow would call generateSummary and then still need updatePost to save other fields. Auto-persisting summary is fine and useful for agents. But then it's a write op → audit + rebuild. Hmm, but if AI is not configured, it shouldn't write anything. And if configured, it writes summary. Let me make generateSummary: 1. find post (not_found if missing) 2. if not configured → return { summary: '', tags: [], configured: false, message: 'AI 未配置...' } (no write) 3. call AI → update post summary → audit (generate_summary) → trigger rebuild → return { summary, tags, configured: true, message: null } Wait — but the admin SPA flow: it would call generateSummary, get tags suggestions, and then save via updatePost with the tags. But generateSummary already persisted summary. That's fine — the SPA then saves title/content/tags via updatePost. Actually if summary is already persisted, updatePost save with the summary field still writes it again. No harm. OK. Actually, hold on — persisting on generateSummary means an agent calling generateSummary(slug) modifies content, which some might find surprising. But it's "资源化动作" (resource-ized action) consistent with the spec's `/posts/{slug}/summary-generations`. I'll persist. Document it. Actually, let me reconsider once more. The shared spec: "AI Native 最小演示：POST /api/v1/posts/{slug}/summary-generations 调 OpenAI 兼容 API 生成摘要". It's a "summary generation" resource. The result is the summary. Whether it persists isn't specified. For a cleaner, less surprising contract, I could NOT persist — just generate and return. But then agents can't get the summary persisted without a second call. Hmm. For the admin UI, non-persisting means user copies it. Persisting is more "do the thing" friendly. I'll persist the summary (and update post), audit it, and trigger rebuild (since the list page shows summaries). This is the "resource-ized action" interpretation and more agent-friendly. I'll clearly document it. Hmm, wait, but there's an edge: if AI is unconfigured, the resolver must return a non-error SummaryResult (configured:false). Good. Let me also think about the `Upload` scalar resolver. graphql-yoga exports `GraphQLUpload`. In the resolver map, `Upload: GraphQLUpload`. For JSON scalar, define custom scalar. Now — one important thing about resolvers for `tags` field on Post: I'll resolve tags at the Post level. To avoid N+1, the posts resolver can pre-fetch tags map. But simpler: Post resolver fetches tags per post. For list of 10, that's 10 queries — acceptable for prototype. But better: use a context cache keyed by post id. Let me add a per-request tag cache in context: ```ts context.tagsCache = new Map<number, TagRow[]>() async function resolvePostTags(postId) { ... cache ... } ``` I'll implement a simple per-request cache via context. Actually to keep it simple and correct, I'll do a batch in the posts resolver: fetch all tags for page posts, then return Post objects with tags pre-attached (non-enumerable or hidden field). The GraphQL Post type only exposes the SDL fields; extra JS properties on the resolved object are fine (they're just ignored unless referenced). So in posts resolver, I attach `_tags` array and resolve `tags` from `parent._tags ?? await tagsForPost(parent.id)`. For single post resolver, fetch tags directly. Let me structure: ```ts const Post = { status: (p) => p.status === 'published' ? 'PUBLISHED' : 'DRAFT', tags: async (p, _, ctx) => p._tags ?? ctx.postTags(p.id), createdAt: (p) => iso(p.created_at), publishedAt: (p) => p.published_at ? iso(p.published_at) : null, _links: (p) => buildLinks(p.slug), } ``` ctx.postTags(postId) with cache: ```ts context: { identity, request, postTagsCache: new Map(), async postTags(id) { if cache has return; else fetch and cache } } ``` Now Query resolvers: - posts({status, tag, page}): status arg is enum DRAFT|PUBLISHED|null. Map to 'draft'|'published'|'all'. If anonymous (not authenticated), force status='published' (even if they pass DRAFT? If anonymous asks status:DRAFT — should we return drafts? No — drafts need auth. C behavior: anon → only published. I'll force: if not authed → status='published' regardless; if they pass status and are authed → respect). Return PostPage { posts, total, page, perPage, totalPages }. - post({slug}): find; if not found → null (return null, not error? GraphQL Post nullable. Return null). If draft and not authed → throw unauthorized? Or return null. Hmm. C returned 401 for drafts. For GraphQL, returning null is ambiguous (agent can't tell if it's a draft or missing). Better to throw NOT_FOUND for drafts when anonymous? That's also ambiguous. Let me return null for not-found, and for draft+anonymous throw unauthorized (explicit). Actually, let me throw notFound when draft+anonymous to avoid leaking existence... but C leaked by 401. The spec's DoD 8 wants structured errors for auth issues. I'll throw unauthorized() for draft+anonymous. Document. - tags: listAllTags. - stats: needs auth (stats has views counts). DoD stats panel is admin-only. But the shared spec says stats panel in admin. I'll require auth for stats query. Actually, is there harm in public stats? It's admin functionality; keep auth. requireAuth → else unauthorized. - media: require auth. - auditLogs: require auth. - openapiMeta: public, returns meta JSON. Mutation resolvers: - login: verify creds → issue token → audit (login) → return { token, username }. actorId = username. But rate limit login by IP. - createPost(input, idempotencyKey): runMutation → withIdempotency(key, 'createPost', async () => { try createPost; catch slug_conflict → throw slugConflict }). Note: createPost service throws Error('slug_conflict') or Error('not_found'). I need to map service errors to GraphQL errors. Let me make services throw typed errors. I'll create a small helper: throw a plain Error with `.code` property. In resolvers, catch and map. Let me define error mapping in resolvers: wrap fn with try/catch mapping `err.code`: - 'not_found' → notFound(...) - 'slug_conflict' → slugConflict(...) - 'VALIDATION' → invalidInput(...) - else → GraphQLError(message, { extensions: { code:'INTERNAL', http:{status:500}, agent_hints:{retry_allowed:true, suggested_action:'Report the error; retry after a short delay.'} } }) The runMutation can wrap. But careful: withIdempotency wraps fn; if fn throws slug_conflict, we don't store idempotency, error propagates. Good. Also createPost with status published → returns published post + trigger rebuild. triggerRebuild should be called for content mutations. Let me call triggerRebuild in the resolver after successful mutation (before audit or after). Order: do the write, trigger rebuild (fire and forget), audit, return. Actually audit should be "调用 Service 前/后写 audit_logs" — handoff says before/after. I'll audit after success. For failures, could audit failure too, but keep it: audit success only. Actually "所有写操作审计" — I'll audit all attempted writes (even failures?) Keep simple: audit on success. Document. Hmm, the spec says "所有写操作审计日志记录 actor_id/subject_id/via/created_at". For the prototype, success audit is fine and DoD 6 checks after a write → audit exists. I'll audit on success. For delete: deletePost returns boolean. - publish(slug, idempotencyKey): withIdempotency → setPostStatus('published') + triggerRebuild → return post. Note: idempotency replay returns stored result — same post. Good. - unpublish(slug): setPostStatus('draft') + rebuild. - updatePost(slug, input): updatePost service + rebuild. Input fields all optional (PostInput in SDL — wait, handoff SDL has updatePost(slug, input: PostInput!) — PostInput with all-required fields? In SDL, PostInput fields: title: String!, content: String!, summary: String, slug: String, status: Status, tags: [String!]. If updatePost requires full input with non-null title/content, that's awkward for partial updates. But the handoff literally defines one PostInput used by both create and update. To allow partial updates, I could make updatePost's input nullable fields... but the same PostInput type is used for both. Since SDL type PostInput has title/content non-null, createPost requires them (good), updatePost would also require them (meh). Option: define updatePost input with the same PostInput type — update requires title and content present. The admin SPA always sends full fields on save anyway. And agents doing updatePost would send the full input. That matches the handoff SDL literally. But partial updates like publish-then-update... Actually updatePost can still change status etc. I'll keep PostInput as-is (title/content non-null) and treat updatePost as "full update" — the SPA and agents send complete inputs. This keeps the SDL exactly per handoff. Good, simpler. But what if an agent wants to update only summary? They'd have to fetch the post first and resubmit full input. Acceptable; document as a design decision (or add a separate optional update). I'll keep the handoff SDL verbatim. Wait — actually, let me reconsider. updatePost(input: PostInput!) where PostInput.title is non-null. The admin "publish/unpublish" toggle in C calls updatePost with only {status}. In my F design, publish/unpublish are separate mutations (publish/unpublish), so the SPA uses those, not updatePost with partial. And the edit form sends full input. OK. But the service updatePost accepts Partial — that's fine, the resolver passes full input. Good. - generateSummary(slug): as described. - uploadMedia(idempotencyKey, file): runMutation + withIdempotency → uploadMedia(file) → rebuild trigger? Media upload doesn't change static pages (media isn't on public pages, only export). No rebuild needed. Skip rebuild. Actually media isn't rendered on the static site. No rebuild. - deleteMedia(id): delete + no rebuild. - createTag(name): create + rebuild? Tags affect tag pages in static site (empty tag pages). If a new tag has no posts, the tag page would be created only on rebuild. So yes, createTag/renameTag/deleteTag should trigger rebuild (tags pages depend on tags). C's tags route didn't trigger rebuild (only posts did) — but the rebuild generates tag pages for all tags. If a tag is added but no post uses it, its page won't appear until next rebuild. For consistency I'll trigger rebuild on tag mutations too. It's cheap (debounced). Actually C only rebuilt on posts. Hmm. Tag changes do affect the tag pages and post items' tag links... tag rename changes slug → post tag links. So yes, rebuild on tag CRUD. I'll do it. - renameTag(id, name), deleteTag(id). Now the openapiMeta JSON. Now the SDL. Let me also add arg descriptions where useful. Let me write the SDL string carefully. One more consideration: `scalar JSON` — the handoff SDL has `openapiMeta: JSON!`. I'll define JSON scalar. And `scalar Upload`. Let me also double check: GraphQL yoga's GraphiQL — enable `graphiql: true` so GET /graphql without sdl shows a playground. That's nice for agents/humans. The sdl param takes precedence. Now, there's the question of whether to require idempotencyKey for createPost when called with status published. That's fine. Let me also handle the audit for createPost resource string: `post:<slug>`. Now let me write graphql/schema.ts. It's large. Let me write it. Also, I need `makeExecutableSchema` from @graphql-tools/schema. Let me add that dependency. Actually — wait, do I really want the extra dep? Let me think about the alternative: `buildSchema` from graphql then `addResolversToSchema`. @graphql-tools/schema provides both makeExecutableSchema and addResolversToSchema. It's the standard. I'll add `@graphql-tools/schema`. Let me check its compatibility with graphql 16 and workers. @graphql-tools/schema is pure JS, no node deps, works in workers. Yes. Actually, I realize graphql-yoga may work with resolvers attached differently — graphql-yoga accepts `schema` only. So I need to produce a full GraphQLSchema. makeExecutableSchema does exactly that. Alternatively, I could write the schema entirely in code (GraphQLObjectType etc.) and use printSchema for the SDL endpoint. That avoids @graphql-tools. But handoff explicitly says "手写 SDL + yoga" → SDL string. makeExecutableSchema it is. Let me write schema.ts now. For the resolver `posts` — the page arg: page: Int. Return PostPage. For `openapiMeta` I'll build a static object. Let me write the SDL with comprehensive descriptions. This is the DoD-5 artifact. Every field gets a description.展开全部