Imported from Zexuan-Xie/Zephyr-s-Blog (
AGENTS.md). Install upstream withnpx skills add Zexuan-Xie/Zephyr-s-Blog. Copyright stays with the author.
xLab Blog Agent Guide
Read order
Before changing code, read:
PROGRESS.md— current breakpoint, environment, next actions, and required verification.docs/plans/SECOND_DEVELOPMENT.md— active staged plan. Section 4 is the current Stage 2 plan; Section 5 covers Stage 3 and MCP.docs/specs/CONTEXT.md— canonical product language.- The relevant active specs under
docs/specs/. docs/api/openapi.yamlbefore changing shared API behavior.
Historical implementation detail is compacted in docs/archive/INITIAL_BUILD_SUMMARY.md, docs/verification/, and Git history. Do not revive old OMX runtime state, stale task ledgers, or detached worker changes.
Product language
Use Author, Reader, Anonymous Visitor, Author Workspace, Content Tree, Directory, File, URL Path, Content Version, and Published Content consistently. Admin describes privileges/routes, not the person or product UI. Do not expose the implementation term slug in product UI.
Current scope
The staged implementation is now at Stage 3 engineering closeout:
- Reliability, navigation, and identity — engineering complete.
- Simple-English Author Workspace and protected Content Tree — engineering complete and preserved as the Author baseline.
- Autosave, Content Versions, Published Content snapshots, Draft Preview, Draft/Published Assets, and a server-local stdio Blog MCP Server — engineering complete; user acceptance is the next checkpoint.
Maintain presentation/defense quality: code should stay readable, extensible, and architecturally clear. Do not redesign public homepage, Recent cards, public Directory/File reading, comments/Likes, or the Glass Ricepaper system except to repair regressions.
Engineering rules
- Keep each stage runnable, reversible, and independently testable.
- Update OpenAPI first for shared API contract changes.
- Keep SQL in repositories, not HTTP handlers or MCP handlers.
- Preserve iframe
sandbox="allow-scripts"withoutallow-same-origin. - Preserve full-text search fallback when semantic indexing is unavailable.
- Back up the local database before cleanup, fixture reset, or schema migration.
- Do not commit credentials, local database files, uploads, caches, build output, or agent runtime state.
- Update
PROGRESS.mdat every key milestone and before stopping. - Record verification evidence under
docs/verification/. - Prefer clear service/API-client reuse over duplicated business logic, especially for the final MCP Server.
Exact local environment
Use Conda environment blogenv:
- Node.js
22.22.3 - npm
10.9.8 - Go
1.26.4 - PostgreSQL
17.10 - pgvector
0.8.1locally
Run tools through conda run -n blogenv ... when the shell environment is uncertain.
Required verification
Backend:
cd api
CGO_ENABLED=0 GOCACHE=/tmp/xlab-blog-go-cache go test -count=1 ./...
CGO_ENABLED=0 GOCACHE=/tmp/xlab-blog-go-cache go vet ./...
test -z "$(gofmt -l .)"
Frontend:
cd web
node --test tests/*.test.mjs
npm run lint
npm run build
MCP:
cd mcp
npm test
npm run build
For runtime/auth/tree/publication changes, also run native PostgreSQL API smoke and browser acceptance. Stage 3 additionally requires autosave/publication/Draft Preview/Asset/MCP evidence.
