Site Agent: A Page-Aware Guide for My Portfolio Site Agent： 作品集页面向导

Visitors arrive with questions, not an information architecture

A portfolio usually asks visitors to understand its categories, cards, and project names before they can form a view of the designer. Recruiters, collaborators, and peers often arrive with the opposite starting point. They already have a question: Have you worked in healthcare? Why does this project matter? Which case study best shows systems thinking?

Site Agent is the guide I built across this portfolio. It does not offer unlimited conversation, and it does not replace the Archive. Its job is narrower: understand the page a visitor is reading and the recent conversation, answer from public material, then connect that answer to a useful page.

Split authority before styling intelligence

I did not ask the model to run the whole experience. Contact, resume, all work, open project, and related-page requests have deterministic answers, so local code recognizes and executes them. The model is reserved for the work that needs language: comparing projects, explaining a method, summarizing the current article, or understanding a very short follow-up.

This division lets the model speak without giving it navigation authority. Project links, follow-up suggestions, and related work are rebuilt by the site from the final answer, current path, and public index. An unstable response cannot invent a route and send a visitor somewhere that does not exist.

The current page becomes the default subject

The early version behaved more like site-wide search. It knew what the portfolio contained, but it did not always know what the visitor was looking at. The failure was clearest on a project page. A visitor could ask “Why does it matter?” and receive a site-wide recommendation about another project.

Each request now carries the current path. Site Agent first decides whether the question refers to this page, explicitly names another entry, or asks about the portfolio as a whole. On a project page, short prompts such as “What methods did you use?”, “What should I notice?”, or “Why this approach?” stay anchored to that project. The subject changes only when the visitor names something else or clearly asks a site-wide question.

Treat failure as a normal route

Site Agent reaches OpenRouter through an Astro API route. Free models can be slow, return nothing, break a response format, or include provider reasoning artifacts. I could not design the interaction around the assumption that the model would always cooperate.

Each model attempt has a 4.5-second limit and all candidates share a 9-second budget. If there is no API key, a provider times out, or every candidate fails, the server builds a contextual fallback from the public index. The browser keeps an independent network timeout as a second boundary. The fallback is less flexible than a model answer, but it can still explain the current page, surface related work, and provide direct routes.

It began as a shape-shifting entrance

Site Agent began as a floating orb. Refraction, transparency, and an internal dot field helped it grow out of the page. The orb stretched into a prompt, then expanded again into a glass answer window. Day and night photobooth scenes tested whether the same material could survive very different backgrounds. I also owe an early thank-you to my friend Zihan Huang, whose conversation about agents on personal sites helped me treat this as a native site object instead of an attached support widget.

That exploration established the dot field and the idea of one object unfolding through the interaction. It also exposed the mismatch. The orb, prompt, and answer still read as three different objects. Glass copy depended too much on the page behind it. The material demonstration was louder than the job of helping someone understand their current page.

The current capsule makes continuity useful

The current version returns to a solid ink capsule in the center of the utility bar. One container stretches into the prompt, grows into the answer window, and collapses along the same path. It no longer needs refraction to prove that it exists, and page content no longer sits behind the answer copy.

The dot field remains as a state signal. It drifts at rest, settles toward the bottom through prompt and window states, and gains energy only during thinking. The visual change now explains system state instead of staging a separate material performance.

The article and the agent have to change together

Site Agent depends on the portfolio, so content maintenance is part of the product. A build script turns public projects and articles into an index with separate project, article, bilingual, and evidence fields. The agent definition states what it can answer, what it cannot access, how long an answer should be, and when thin evidence should be acknowledged. Safety, local suggestions, and fallback behavior stay in deterministic code.

The harness matters because it gives every content change a clear synchronization surface. A title or slug change affects the index and routes. A change to current-page semantics requires a context and suggestion check. A change to the public knowledge boundary triggers a generated-material audit. Site Agent is not a feature that was placed on the portfolio and left alone. It grows with the site, and it has to be checked with the site.

What it demonstrates now

This project does not have public conversion or usage data, and I do not want to disguise a working implementation as user impact. What it demonstrates is a set of concrete design decisions: put the language model in the narrow role it can handle, keep navigation and safety inside a system that can be verified, make failure remain useful, and use one visual object to connect those layers into a coherent interaction.