DEV Community: Evan Lin

[Claude Code in Practice] Rethinking Terminal Workflows: From zsh Autocomplete to Search and Diff Toolchains

Evan Lin — Fri, 14 Aug 2026 16:56:08 +0000

Pain Point: Starting Over with Every Command

When using Claude Code for tasks, there have always been two minor frictions that I hadn't seriously addressed until now.

The first is that the shell itself is too bare-bones: there's nothing in ~/.zshrc except for two lines of PATH. No auto-completion, no command history. Navigating history requires pressing the up arrow repeatedly, and even then, similar commands must be manually edited. The second is when collaborating with Claude Code, some commands that are clearly read-only and have no side effects (listing files, checking versions, curling a README) require a manual "allow" click every time. This back-and-forth breaks the flow.

This post records the process of tackling both issues at once: how tools were chosen, what pitfalls were encountered, and how it was eventually integrated with Claude Code's permission system.

Solution 1: Let Zsh Remember What You've Typed

I haven't installed oh-my-zsh and didn't want to carry a whole framework for just two features, so I picked the two smallest, sufficient packages:

zsh-autosuggestions: Suggests similar commands in gray text while typing; press Ctrl+Space or → to accept.
zsh-completions: Enhances the coverage of tab auto-completion.

brew install zsh-autosuggestions zsh-completions

Combined with history settings, the up/down keys can filter history based on current input instead of just scrolling through everything:

# --- Command History Settings ---
HISTFILE=~/.zsh_history
HISTSIZE=10000
SAVEHIST=10000
setopt SHARE_HISTORY # Share history across multiple terminal windows
setopt HIST_IGNORE_DUPS
setopt HIST_IGNORE_ALL_DUPS
setopt HIST_FIND_NO_DUPS
setopt INC_APPEND_HISTORY # Write to history file immediately upon command entry

autoload -Uz up-line-or-beginning-search down-line-or-beginning-search
zle -N up-line-or-beginning-search
zle -N down-line-or-beginning-search
bindkey "^[[A" up-line-or-beginning-search
bindkey "^[[B" down-line-or-beginning-search

After installing the packages and adding the settings, theoretically, restarting the terminal should work—but it wasn't that smooth.

Solution 2: Add Color to Read the Terminal Faster

Once auto-completion was set up, I added colors as well:

zsh-syntax-highlighting: Real-time coloring while typing; green for valid commands, red for invalid ones.
ls -G: Different colors for folders, executables, and links.
grep --color=auto: Highlights matched keywords in red.

export CLICOLOR=1
export LSCOLORS=GxFxCxDxBxegedabagaced
alias grep='grep --color=auto'

source /opt/homebrew/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

Handled fonts too: Ghostty's config file (~/Library/Application Support/com.mitchellh.ghostty/config.ghostty) didn't specify a font size and defaulted to the system's 13. Adding font-size = 16 solved it.

Solution 3: Replace `ls`, `cat`, and `cd` with Smarter Versions

Color and auto-completion are infrastructure; next, I added modern alternatives for three common commands. The selection criterion was simple: single executable, no background daemon, and no impact on startup speed.

Command	Alternative	Benefit
`ls`	`eza --icons`	Color, icons, tree structure (`lt`)
`cat`	`bat --paging=never`	Syntax highlighting, line numbers
`cd` (helper)	`zoxide`	Remembers frequent folders; `z proj` jumps directly

I evaluated fzf but didn't install it this time—my current habits don't require fuzzy searching history/files yet. I'll add it if I feel a bottleneck later.

Solution 4: Make File Searching and Comparison Faster for Claude Code

The previous items were for "user experience"; this one is for "Claude Code speed." Claude Code's built-in search tool already uses ripgrep (rg), and jq is already installed, so these three were missing:

fd: Replaces find; simple syntax, fast, especially noticeable when listing files.
ast-grep: Structural code search. Not just text matching, but looking at the Abstract Syntax Tree (AST). It can search for "all calls to a function where the first argument is a string," which is much more accurate than regex for large-scale refactoring or precise searches.
difftastic (difft): Syntax-aware diff. It recognizes when a function has been moved rather than deleted and rewritten.

brew install fd ast-grep difftastic git-delta

git-delta is mainly for human-readable git diff. It's unrelated to Claude Code, but I installed it anyway.

Solution 5: Add Common Read-Only Commands to Claude Code's Permission Whitelist

A new problem emerged after installing the tools: the first time Claude Code calls these new commands, it still asks for permission. Using the fewer-permission-prompts skill to scan recent session transcripts, I identified frequently run, truly read-only commands and compiled a whitelist:

{
  "permissions": {
    "allow": [
      "Bash(curl -s https://raw.githubusercontent.com/*)",
      "Bash(curl -s \"https://api.github.com/*)",
      "Bash(brew list*)",
      "Bash(xcodes list*)",
      "Bash(xcodebuild -version)",
      "Bash(curl -sI *)",
      "Bash(difft *)",
      "Bash(delta *)"
    ]
  }
}

fd, rg, and jq are not on the list, not because they were missed, but because Claude Code already includes them as built-in, auto-allowed read-only commands.

Three Easily Overlooked Pitfalls

Pitfall 1: `compinit` complaining about "insecure directories"

After installing packages and restarting the terminal, the first launch showed:

zsh compinit: insecure directories, run compaudit for list.

compaudit revealed the issue was that the /opt/homebrew/share directory permissions were too open (group write access). compinit checks permissions before loading completion scripts; if any directory is "writable by others," it refuses to load to prevent malicious scripts from being injected into the completion path. The fix is the official Homebrew recommendation:

chmod go-w /opt/homebrew/share
chmod -R go-w /opt/homebrew/share/zsh
rm -f ~/.zcompdump*

Clearing the cache to let it rebuild solved the problem.

Pitfall 2: `zsh-syntax-highlighting` must be the last line

The official documentation is clear: this line must be the last thing executed in .zshrc. If placed before zsh-autosuggestions or other bindkey settings, syntax highlighting and auto-suggestions may interfere, and key bindings might fail. I specifically moved it to the very end of the file.

Pitfall 3: `ast-grep` was intentionally left out of the whitelist

ast-grep is missing from the whitelist on purpose. By default, it's a read-only search, but adding the -U / --update-all flag allows it to rewrite files. Permission rules use prefix matching, so I can't allow only the "no -U" usage. Opening a broad rule like Bash(ast-grep *) theoretically allows file-modifying usage as well.

This aligns with the original logic for sed: only "read-only expressions" are auto-allowed; any usage with in-place editing still prompts for permission. Rather than re-evaluating the risk, I followed the same standard.

Summary and Benefits

This terminal environment overhaul was essentially about optimizing "human typing" and "Claude Code execution" separately:

Less typing: zsh-autosuggestions + history filtering means almost no re-typing repetitive commands.
Faster reading: Syntax highlighting, eza, and bat make outputs instantly readable.
Faster navigation: zoxide replaces memorizing paths, and fd replaces the slow find.
More accurate Claude Code searches: ast-grep adds structural search that plain text matching can't do, and difftastic makes diff results closer to actual changes.
Fewer "allow" clicks: Whitelisting truly read-only, risk-controlled commands while still prompting for things that should be asked (like ast-grep -U).

The core principle for tool selection remained the same: single executable, no background daemons, and avoiding frameworks where possible. The real time-consumer was deciding "whether to whitelist this"—speed is secondary; the priority is ensuring a command that can modify files isn't accidentally wrapped in a seemingly safe, generic rule.

[Dev Log][Python] Create short videos from photos and clips with Gemini 3.7 Flash: ReelCraft

Evan Lin — Fri, 14 Aug 2026 16:55:48 +0000

Preface:

It all started with a misunderstanding.

I noticed a new page in the Gemini API documentation called Omni, introducing a model named Gemini Omni Flash, described as "natively multimodal, processing text, images, audio, and video simultaneously." My first thought was straightforward: if I throw a whole folder of videos and photos from my phone into it, let it understand what each asset is about, and then tell it in one sentence to edit them into a short video—isn't that a video editing app?

After reading the documentation, I realized I had misunderstood, and the misunderstanding happened to be at the most critical point. However, after bypassing that limitation, the rest was actually feasible. The result is ReelCraft: a Python CLI where you feed in a bunch of videos and photos, Gemini 3.7 Flash understands the assets one by one and provides editing suggestions. Once I confirm the edit list, ffmpeg cuts it into a 9:16 vertical short video, background music is generated using Lyria 3, and subtitles are automatically burned in.

Along the way, there were three issues where both ffmpeg and Gemini reported success, but the output was wrong—the kind of errors you only discover by actually playing the video.

TL;DR

This article will cover:

Omni Flash is not what I thought it was
Bypassing limitations: Per-file understanding, then text aggregation
Using edl.yaml as a human confirmation point
The difference after switching to Gemini 3.7 Flash
Background music: Lyria 3 uses a different API
ffmpeg will silently fail your edits
Subtitles: Two issues only visible after burning them in
Other pitfalls
Conclusion
Reference links

Omni Flash is not what I thought it was

Gemini Omni Flash (gemini-omni-flash-preview) is a video generation and editing model that uses the Interactions API. It allows you to use natural language to apply effects to a single video, such as "when the person touches the mirror, make the mirror ripple beautifully like liquid." It is not a tool for "understanding a bunch of videos."

The limitation section states clearly:

Referencing or reasoning across multiple videos is not supported. Attempting multi-video prompting may result in degraded model performance or unexpected outputs.

Additionally:

Video references up to 3 seconds in duration are accepted by the API schema but are not correctly processed by the model at this time.

So the path of "throwing a bunch of videos in and letting it understand and edit them" was blocked for Omni Flash. The models that can actually perform multi-video understanding are the standard Gemini models: starting from version 2.5, a single request can include up to 10 videos. With a 1M context window, it can handle about an hour of footage at default resolution, tokenize it second-by-second, and output scene descriptions with timestamps.

The time spent on this misunderstanding wasn't wasted. The verification process helped clarify "which task should be handled by which model," and the architecture followed naturally.

Bypassing limitations: Per-file understanding, then text aggregation

The entire pipeline is split into five stages, with states stored in files:

[Asset Folder]
     │ poc ingest: Scan videos/photos → catalog.json
     ▼
     │ poc analyze: Call Gemini for each file individually → analysis/*.json
     ▼
     │ poc plan: Aggregate all analysis results, call once for editing suggestions
     ▼ → summary.md (for humans) + edl.yaml (for machine execution)
     ⏸ Human inspection and editing of edl.yaml
     ▼
     │ poc render: ffmpeg editing, 9:16 cropping, xfade transitions
     ▼
output/final.mp4

The key design decision is in the second and third steps: call Gemini once for each video to get precise internal timestamps and descriptions; then feed these text results (not the raw videos) into a second call for cross-asset aggregation, sequencing, and editing suggestions.

This approach has two benefits. First, it completely avoids the "multi-video reasoning not supported" issue because the second call only sees text, not ten videos. Second, it isn't limited by the 10 videos/request cap; no matter how many assets there are, it just means more independent calls in the analyze phase. Those calls can be retried or fail individually without affecting each other.

Testing also proved that timestamps are more reliable when processed separately. When asking about ten videos in a single prompt ("which seconds are the highlights?"), the model easily confuses the timelines of different videos.

Failure handling in the analyze phase is recorded separately: if a file fails after three retries, it's logged in analysis/_errors.json, while other files continue. This later revealed a loophole during review, which I'll discuss later.

Using edl.yaml as a human confirmation point

I decided from the start not to make it "one-click fully automatic." Between inputting assets and outputting the final product, there must be a place where I can manually intervene, because LLM-provided edit points will inevitably have some irrationalities, and re-running the entire pipeline incurs API costs again.

That interface is a YAML file:

target_duration_sec: 23
aspect_ratio: '9:16'
clips:
- source: /abs/path/808327978.mp4
  note: Opening shot: Showing the COSCUP x UbuCon Asia main visual backdrop.
  in: '00:00.000'
  out: '00:02.500'
- source: /abs/path/S__1908753.jpg
  note: Fun venue easter egg: Creative semiconductor chip snacks distributed on-site.
  duration_sec: 4.0
transitions: crossfade 0.3s
mood_tags: [Professional, Joyful, Community Cohesion]

Videos use in/out to mark the range, photos use duration_sec for duration, and note is the reason for selection written by Gemini (this field was later used for subtitles, see below). To change an edit point, just change the numbers; to change the order, move the clip; after saving, run poc render.

The outputs of each stage remain in the project directory, so any step can be re-run individually. analyze also skips files that already have analysis results, so re-running doesn't incur double charges—this is very helpful when iterating on prompts.

poc plan --theme was added later: you can provide a sentence as the editing theme, e.g., --theme "Participating in the COSCUP open source community". This affects the narrative angle of the summary, the priority of clip selection, and the wording of each clip's note. Since it only affects the plan stage, changing the theme doesn't require re-analyzing assets, making it very cheap to try different narratives on the same set of materials.

The difference after switching to Gemini 3.7 Flash

The understanding and aggregation stages initially used gemini-2.5-flash, then switched to gemini-3.7-flash. This is the GA stable version, not a preview:

Item	Specification
Model ID	`gemini-3.7-flash`
Input	1,048,576 tokens
Output	65,536 tokens
Input Types	Text, Image, Video, Audio, PDF
Capabilities	structured outputs, function calling, caching, thinking (low/medium/high)
Not Supported	Video/Image/Audio generation, Live API

For this project, the most important features are structured outputs and video input, as the analyze stage involves feeding in a video and requesting a JSON with a fixed schema.

After switching, I didn't just change the string and call it a day; I verified it with actual API calls, running analyze_file on real assets. For the same lecture video, the difference in descriptions between the two models was quite noticeable.

gemini-2.5-flash version:

At the start of the video, a woman on stage uses a microphone to introduce herself to the audience. The large screen behind her shows her name "Zona Wang" and her job description.

gemini-3.7-flash version:

In the video, a female speaker (Zona Wang, LINE Technology Evangelist) is giving a self-introduction and presentation on a stage in a lecture hall, followed by a camera pan across the audience listening intently.

The difference lies in "job description" vs. "LINE Technology Evangelist." The latter actually read the small text on the slide, while the former only knew there was some job information there.

The gap in the aggregation stage was even larger. For the same set of COSCUP assets and the same --theme, 2.5's summary was: "This short video aims to showcase the vitality and diversity of the COSCUP open source community. From professional knowledge sharing and deep technical exchange to warm interaction and inclusion among community members"—the whole thing stayed at an abstract level. 3.7 recognized the full event name "COSCUP x UbuCon Asia," booth names like "FOSS for All" and "Kubernetes," and even described a photo as "Creative semiconductor chip snacks distributed on-site." These details weren't in my prompt; they all came from the text and objects in the photos.

For an application where "asset understanding quality directly determines editing quality," the benefit of switching models was greater than I expected. The editing suggestions improved because it actually understood more, not because the prompt was written better.

By the way, 3.7's note style also changed to a "Short Label: Detailed Description" format. This change later broke all my subtitles, as discussed below.

Background music: Lyria 3 uses a different API

Background music is generated using Lyria 3. There are two models: lyria-3-clip-preview for 30-second clips, and lyria-3-pro-preview for full songs. My output is about 20 seconds, so the clip version is perfect.

It doesn't require a separate Vertex AI application or allowlisting; the same Gemini API key works. However, the calling method is completely different from generate_content, using client.interactions.create():

interaction = client.interactions.create(
    model="lyria-3-clip-preview",
    input="An instrumental background music track for a short social-media video, "
          "about 20 seconds long. Mood: Professional, Joyful, Community Cohesion, Happy. "
          "No vocals, no lyrics, loopable.",
)
audio_bytes = base64.b64decode(interaction.output_audio.data)

Several things were different from what I imagined.

It has no structured parameters. Length, BPM, genre, and mood must all be written in the natural language prompt, rather than passing a field like bpm=120. So the generate_score(mood_tags, duration_sec) function's job is actually to concatenate mood tags and seconds into an English sentence. Mood tags are aggregated from asset analysis results during the plan stage, and poc render --mood "Happy, Joyful, Celebration" can further overlay desired directions.

It is single-turn generation and cannot be iteratively modified. Unlike Omni Flash's video editing, once the music is generated, it's set; if you're not satisfied, you have to submit a new prompt. All generated audio includes a SynthID watermark.

When the music is shorter than the video, you have to handle it yourself. The clip version is max 30 seconds, but the video might be longer. So during mixing, I use -stream_loop -1 to loop the audio infinitely and -shortest to trim it to the video length:

cmd.extend(["-stream_loop", "-1", "-i", str(audio_path)])
# ... filter_complex, map video ...
cmd.extend(["-map", f"{audio_index}:a", "-c:a", "aac", "-b:a", "128k", "-shortest"])

Music generation failure (quota, network, safety filters) won't crash the entire render; it prints a warning and falls back to silent output. This principle was later added to the project's CLAUDE.md: any value-added feature calling an external generative API must degrade gracefully and not let the main process die because of a secondary feature.

ffmpeg will silently fail your edits

The render stage uses ffmpeg's xfade filter to connect clips. Each xfade requires an offset parameter, which is "at which second in the output timeline to start this transition." The logic for accumulation is: the sum of all previous clip lengths minus the seconds overlapped by each transition.

After writing the first version, unit tests were all green, and real assets produced normal videos. Then review identified two scenarios where ffmpeg returns exit code 0, but the output file is wrong.

Scenario one: The transition is longer than the clip, causing the clip to be silently swallowed. For two 1-second clips with transitions: "crossfade 2s", the calculated offset is -1.000. ffmpeg accepts this negative number, doesn't report an error, and finishes normally. The output is a 1-second video containing only the first clip; the second one disappears entirely. Since EDL.transitions is a free-text field, it's entirely possible for me to type 3s instead of 0.3s when manually editing the YAML, and it won't tell me in any way.

Scenario two: out exceeds the actual asset length, causing everything following it to be truncated. For a 10-second video, if the EDL says in: 8.0 / out: 15.0, only 2 seconds can actually be taken. If a 1.5-second photo follows, the offset is calculated as 6.700, which falls after the end of the first stream. The result is a 2-second output where the photo is completely missing, and the exit code is still 0. This scenario is even more important to prevent because the EDL is generated by an LLM, and hallucinating an out-of-bounds end time is quite natural.

I added explicit checks for both: if a negative offset is calculated, a ValueError is thrown specifying which clip and transition length; before rendering, ffprobe is used to read the actual length of each video asset, and if out exceeds it, an error is reported clearly stating the requested vs. actual duration.

I care so much because a "successful" but incorrect output is much worse than a crash. If it crashes, I know to fix it immediately. With exit code 0 and a seemingly normal mp4, I might not notice until I watch the whole video and think "wait, a segment is missing," and then have no idea where to start investigating.

Subtitles: Two issues only visible after burning them in

The source for subtitles is the note for each clip in the EDL—the editing reason written by Gemini. Since it already wrote a description for each segment, using it as an on-screen title is perfect.

The implementation doesn't use drawtext; instead, it generates an SRT file and burns it in using libass's subtitles filter. The reason is that drawtext requires manual handling of Chinese font paths and escaping characters; colons, commas, and single quotes all clash with filtergraph syntax. SRT with force_style is much cleaner, and specifying FontName=Noto Sans TC lets fontconfig find the Chinese font.

The first issue was two subtitles appearing on screen simultaneously. In the first version, each subtitle's display interval was just the clip's own start and end times. But with a 0.3s crossfade overlap between adjacent clips, those 0.3 seconds would have two lines of white text on a black background stacked together, which looked ugly. The fix was to change each subtitle's end time to "when the next clip starts" rather than its own end time, ensuring at most one subtitle is visible at any moment. Unit tests couldn't catch this because the SRT was perfectly valid and ffmpeg burned it successfully; I only found it by looking at the frames.

The second issue was subtitles all trailing with an ellipsis. The note is a full sentence description, which would fill the screen if burned directly, so it's truncated into a short title: cut at the first comma or period, or use a character limit if no punctuation is found, adding "..." if truncated.

After switching to Gemini 3.7 Flash, this rule fell apart. 3.7 tends to write notes in a "Opening shot: Showing the 2024 COSCUP x UbuCon Asia main visual backdrop" format—a "Short Label: Detailed Description" style. Since colons weren't in my sentence-breaking character list, the whole sentence fell into the character-limit truncation path, and all eight subtitles ended with "...".

Hard truncation had a second flaw: it ignored word boundaries. "Presenting the female speaker sharing presentation content about ChatGPT and Antigravity" cut at the 20th character resulted in "...and An...", a halved English word.

I fixed both: colons are now treated as label separators, and the label itself is used as the full title without an ellipsis; when hard truncation is necessary, if the cut point falls in the middle of a continuous string of English letters/numbers, it backtracks to before that string started, discarding the whole segment rather than cutting it in half. I also relaxed the character limit from 20 to 24.

After re-burning, the eight subtitles became clean short titles like "Opening Shot," "Session Hall Live," "Technical Sharing Close-up," "Venue Easter Egg," and "Community Booth Interaction," without a single ellipsis.

Other pitfalls

files.upload() returning doesn't mean the file is ready. This was caught by digging into the SDK source code during review, and it would crash on the real API while never showing up in tests. client.files.upload() returns as soon as the bytes are transferred, without waiting for server-side processing. After a video is uploaded, it stays in a PROCESSING state for several seconds; trying to use it for generate_content during this time results in a 400 FAILED_PRECONDITION.

Worse, my original retry loop made things worse: analyze_file was wrapped in a retry, so each retry re-uploaded the entire video and immediately failed again, with only about 3 seconds of backoff across three tries. After three tries, the asset went into _errors.json, and the plan stage didn't read that file at the time, so the asset silently disappeared from the final product. The fix was adding a wait_for_active(), polling client.files.get() after upload until the state is ACTIVE before proceeding, and moving the upload out of the retry loop.

_errors.json was written but not read. As mentioned, analyze diligently recorded failed assets, but plan didn't read them, and summary.md wouldn't mention them. The only way a user could notice was by counting the segments in the final product. Now plan attaches the failure list to the end of the summary, explicitly stating which assets were not included.

Re-running ingest can bite you with old analysis results. This was encountered during actual use, not review. I changed the contents of the asset folder, adding new photos and deleting old ones, then re-ran poc ingest. catalog.json was updated, but analysis results for deleted files were still sitting in analysis/. When plan read the analysis results, it didn't cross-reference them with the current catalog, so it fed outdated assets to Gemini. The model reasonably picked a segment from them, but since the file no longer existed, the whole plan failed. Now load_analyses() filters by the catalog and prints which outdated records are ignored.

Timestamp precision. format_timestamp initially used :04.1f, keeping only one decimal place. Every time an EDL went in and out of YAML, it lost up to 0.05 seconds, which is about 1.5 frames at 30fps, causing edit points to drift. I changed it to :06.3f to keep millisecond precision.

Looking back, these problems fall into two categories. files.upload and ffmpeg silent errors were caught by reading the code line-by-line during review. Subtitle overlapping, ellipsis issues, and stale analysis results only surfaced by actually running the code, playing the videos, and trying different sets of assets. When the tests were all green, those three issues were still lurking in the code.

Conclusion

What ReelCraft does now is simple: a folder of videos and photos goes in, and a 9:16 short video with music and subtitles comes out, with a YAML file in the middle that I can manually edit.

Architecturally, what really makes this work is the "per-file understanding, text aggregation" split. It was conceived to bypass Omni Flash's lack of multi-video reasoning, but it ended up solving timestamp precision and asset count limits as well. After switching to Gemini 3.7 Flash, the granularity of asset understanding significantly increased, and the editing suggestions improved accordingly—the gains here were greater than what I got from tuning prompts.

Two areas remain untouched: Omni Flash's single-clip generative touch-up has an empty touch_up_clip interface, and subtitles are currently derived automatically from note, with the text_overlays field still empty. Neither music nor subtitles are cached; they are re-generated every time render is run.

Reference Links:

[Learning Notes][Golang] Authorization Challenges in the AI Agent Era: What is ID-JAG and Why I Re-implemented It in Go

Evan Lin — Tue, 28 Jul 2026 05:12:52 +0000

Preface:

In the past six months or so, connecting AI Agents directly to internal systems to help get things done is no longer news. However, if you think one step further: in "whose identity" should the Agent call those APIs? If the permissions it receives are as broad as a human's, once it is tricked into performing an operation it shouldn't, the consequences could be more severe than a human's accidental slip.

This is exactly the problem that ID-JAG (Identity Assertion JWT Authorization Grant) aims to solve. I recently organized the principles of this mechanism and re-implemented the MCP Server from the tutorial repo athenz-community/id-jag-the-hard-way using Go: kkdai/id-jag-mcp. This article aims to clarify the technical principles of ID-JAG: which RFC standards it is built upon, how it differs from OAuth2 / PKCE that I've written about before, what the actual token exchange flow looks like, and finally, a demonstration of how to run and test this Go project.

TL;DR

This article will introduce the following in order:

What is ID-JAG? Why is it needed?
From OAuth2 and PKCE to new problems in the Agent era
Two RFC cornerstones: Token Exchange and JWT Bearer
The complete ID-JAG token exchange flow
Downscoping permissions at every hop: How the Principle of Least Privilege is implemented
Why re-implement this MCP Server in Go?
Hands-on: Installation, Execution, and Testing
Conclusion
References

What is ID-JAG? Why is it needed?

ID-JAG is an authorization mechanism that allows AI Agents to access protected resources on behalf of users, with the keyword being "on behalf of." Currently, it is still an IETF Internet-Draft and has not yet become an official RFC, but organizations like LY Corporation (on the Athenz authorization system) and Okta have already begun implementation, and the MCP (Model Context Protocol) specification has already cited this draft.

Traditional service-to-service authorization usually falls into two extremes: either the entire service shares a universal master key (API Key, Service Account), or the user's session or long-lived token is directly lent to the program. The former has too much power, while the latter lacks an audit trail; if leaked, an attacker can almost completely impersonate the user, and it is very difficult to detect. When AI Agents start deciding which tools to call and which internal APIs to connect to on their own, the risks of both approaches are amplified: an Agent might perform operations the user never intended due to prompt injection or hallucinations. If the Agent holds a master key, the consequence is that all company data is at its mercy. In real-world scenarios, there is often a multi-layered architecture where an "Orchestrator Agent calls a Sub-Agent," and the risk is passed all the way down.

What ID-JAG wants to achieve is: for every action an Agent takes, it must be able to prove that "this is a specific user, at a specific moment, authorizing me to do this specific thing," and this authorization scope should be as narrow as possible, with a validity period as short as possible. It is built on top of OAuth2 token exchange (RFC 8693), adding a layer of proof that "this token is derived from a human's identity assertion." This is also why it is listed on OAuth.net's Cross-App Access (XAA) page—this is precisely a new problem emerging in the Agent era.

Incidentally, ID-JAG also solves a very practical user experience problem: if an Agent had to pop up a browser window for the user to manually click "Agree" every time it needed to access a new service, the experience would quickly become exhausting, leading users to just agree to everything. ID-JAG consolidates the authorization action to the moment the user logs in via SSO. After that, when the Agent needs new access permissions, it uses the already issued identity assertion to exchange for a token with the authorization server, without requiring the user to pop up and click again.

From OAuth2 and PKCE to new problems in the Agent era

I previously wrote about How to develop OAuth2 PKCE via Golang, which covered the implementation experience of LINE Login adopting PKCE. The problem solved in that article and the one ID-JAG solves are actually on two different levels. Comparing them makes it clearer what is new about ID-JAG.

PKCE solves the problem of "whether the client identity is trustworthy": for public clients like mobile apps that cannot safely store a client secret, the authorization code might be intercepted by a malicious app on the same phone during transmission. PKCE uses a code_verifier / code_challenge one-time pair to ensure that even if the code is stolen, it cannot be exchanged for a token without the correct verifier. The entire problem occurs in a "single hop" between the user and the app in their hand.

ID-JAG solves the problem of "whether this non-human service identity is qualified to act on behalf of this person for this task," and it often spans several hops: User logs into IdP → AI Client Gateway → MCP Server → Final Resource Server. The caller at each hop is not the user themselves, yet each must prove they are "acting under authority." The original design of OAuth 2.0 was for "human user ↔ application" scenarios and does not directly support this multi-layer Agent chain delegation scenario. PKCE protects the integrity of a single authorization exchange; ID-JAG protects the minimum necessary permissions for every link in an entire authorization chain. The two do not conflict; they are mechanisms solving problems at different stages under the same broad architecture.

Two RFC cornerstones: Token Exchange and JWT Bearer

ID-JAG did not invent a new protocol out of thin air; instead, it combines two existing IETF standards. Understanding these two cornerstones is necessary to understand what the subsequent complete exchange flow is doing.

The first is RFC 8693 — OAuth 2.0 Token Exchange, which defines a general protocol for "exchanging one type of token for another." Conceptually, it's like going to a currency exchange to swap Yen for Taiwan Dollars, except here you are swapping security tokens. A token exchange request looks roughly like this:

POST /token
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token=<Identity Assertion JWT>
subject_token_type=urn:ietf:params:oauth:token-type:jwt
requested_token_type=urn:ietf:params:oauth:token-type:access_token
scope=read:orders

The subject_token contains the token representing the delegated identity, requested_token_type specifies what type of token you want to exchange it for, and scope can narrow down the permission range at the moment of exchange.

The second is RFC 7523 — JWT Bearer Grant, which allows a JWT itself to be used directly as an OAuth 2.0 authorization credential without having to go through an authorization code exchange first:

POST /token
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
assertion=<Signed Identity Assertion JWT>

After receiving it, the authorization server verifies the signature of this JWT using the issuer's (IdP) public key. If fields like audience, scope, and exp are reasonable, it can directly issue an Access Token without secondary user consent—because the IdP has already endorsed this identity assertion.

The "Identity Assertion JWT" to be exchanged usually contains the following fields:

{
  "iss": "https://enterprise.idp.example.com/v1",
  "sub": "alice@company.com",
  "aud": "https://api.service.example.com",
  "exp": 1773839486,
  "iat": 1773825086,
  "jti": "abc123-7dc6-42ab-b326-uniqueid",
  "scope": "read:orders write:tickets"
}

sub is the user being proxied, aud is which service this assertion is intended for, scope is the allowed permission range, and jti is a unique ID used to prevent the same assertion from being replayed. ID-JAG uses this short-lived identity assertion and, through the exchange mechanisms defined in the two RFCs above, gradually exchanges it for the Access Token that the Agent can actually use to call the API.

The complete ID-JAG token exchange flow

Using the architecture of the id-jag-the-hard-way tutorial repo as an example (using Athenz as the authorization server), the complete chain connects the previous two RFCs:

User logs into IdP (Keycloak)
   │ Obtains OIDC ID Token
   ▼
AI Client Gateway
   │ Uses RFC 8693 Token Exchange to swap ID Token for ID-JAG
   │ (grant_type=token-exchange, subject_token_type=id_token,
   │ requested_token_type=id-jag)
   ▼
Then uses RFC 7523 JWT Bearer to swap ID-JAG for a usable Athenz Access Token
   │ (grant_type=jwt-bearer, assertion=<ID-JAG>)
   ▼
AI Client calls MCP Server with this Access Token
   │
   ▼
After receiving the request, the MCP Server performs an RFC 8693 Token Exchange "itself"
   │ Swaps the received Access Token for a new Access Token with the "minimum scope needed for this tool"
   │ (This step uses the MCP Server's own mTLS service identity, not the user's credentials)
   ▼
Calls the final Resource Server with the downscoped Access Token

Throughout the chain, the token is exchanged more than once; it is exchanged every time it crosses a trust boundary, and the scope becomes narrower with each exchange. This design intentionally ensures that the "credential" for each segment of the path is different—the token held by the AI Client Gateway cannot be used directly to trick the final Resource Server because the MCP Server stage forces re-verification and re-issuance. The issued Access Token usually records both sub (the proxied user) and act (the identity of the Agent actually performing the operation), so downstream services can clearly see that "Alice performed this operation through a certain Agent," and the audit trail is not broken midway.

Downscoping permissions at every hop: How the Principle of Least Privilege is implemented

This is what I find to be the most beautiful part of the entire architectural design: least privilege is not just a principle written in a document; it is physically enforced by the token exchange mechanism.

Taking my re-implemented id-jag-mcp as an example, it provides three tools:

Tool	Corresponding Athenz Scope
`get_k8s_docs`	`api:role.docs-getter`
`delete_k8s_doc`	`api:role.docs-deleter`
`post_k8s_doc`	`api:role.docs-poster`

When the MCP Server receives a request, it does not directly forward the Access Token sent by the AI Client to the upstream API—it will always use its own mTLS certificate to perform a token exchange with Athenz ZTS for the "scope actually needed by this tool." Only the newly exchanged token will be used to call the upstream. Even if the token scope at the AI Client Gateway is broader (e.g., possessing both read and delete permissions), the MCP Server will only request the specific small piece of permission actually needed for each tool before forwarding.

In other words, no part of the entire system "happens" to have more power than its current task requires—this is not checked via code review or internal regulations, but is architecturally impossible to bypass.

Why re-implement this MCP Server in Go?

The original MCP Server in id-jag-the-hard-way (api_server/mcp/) was written in TypeScript + Express and used a hand-coded JSON-RPC 2.0 protocol (without the official SDK). I wanted to confirm two things: first, if this token exchange architecture is implemented in a different language with a different MCP SDK, can the logic truly be replicated; second, how the official modelcontextprotocol/go-sdk actually performs.

The final implementation maintains the original core logic (same scope mapping, same mTLS token exchange flow) but replaces the protocol layer entirely with the official Go SDK. The mTLS client was custom-built (without depending on Athenz's official Go client library).

Hands-on: Installation, Execution, and Testing

The code is at kkdai/id-jag-mcp (Apache 2.0 license). The project structure and separation of responsibilities are roughly:

cmd/id-jag-mcp/ Entry point: reads settings, assembles all components, starts HTTP server
internal/config/ Environment variable configuration reading
internal/athenz/ mTLS client + Athenz ZTS RFC 8693 token exchange
internal/tools/ Tool input types + shared upstream forwarding logic
internal/server/ MCP tool registration (official SDK) + REST shortcut routes + logging

First, clone the project and build the binary:

git clone https://github.com/kkdai/id-jag-mcp.git
cd id-jag-mcp
go build -o id-jag-mcp ./cmd/id-jag-mcp

To actually run it, you need to prepare mTLS certificates, a reachable Athenz ZTS, and an upstream API server. Configuration is done entirely through environment variables:

mkdir -p certs
cp /path/to/api-mcp.crt /path/to/api-mcp.key /path/to/ca.crt certs/

export UPSTREAM_BASE_URL=http://localhost:14443
export AUTHORIZATION_SERVER_URL=https://athenz-zts-server.athenz:4443/zts/v1

go run ./cmd/id-jag-mcp

After startup, in addition to the /mcp endpoint for MCP client connections, it also provides REST shortcut routes corresponding to the three tools, making it easy to test directly with curl without an MCP client:

curl -H "Authorization: Bearer $AT" http://localhost:8101/api/docs

curl -X DELETE -H "Authorization: Bearer $AT" http://localhost:8101/api/docs/5

curl -X POST -H "Authorization: Bearer $AT" -H "Content-Type: application/json" \
  -d '{"name":"doc1","content":"hello"}' \
  http://localhost:8101/api/docs

If you just want to confirm if the logic itself is written correctly, you don't need to actually set up an Athenz/Keycloak environment—testing uses httptest to simulate ZTS and the upstream API throughout:

go build ./...
go vet ./...
go test ./...

For example, the tests for internal/athenz will start a fake ZTS server to verify if the outgoing grant_type, subject_token, scope, and audience parameters are correct; the tests for internal/tools verify that when each tool forwards to the upstream, it carries the "downscoped token after exchange" rather than the original one received. This way, you can confirm the entire token exchange logic is correct without actually connecting to Athenz.

The README (available in both Chinese and English) contains a complete list of environment variables and more details.

Conclusion

ID-JAG does not solve "whether this client is who it says it is" (that is a PKCE problem), but rather "whether this non-human service identity is qualified to represent a specific person to do this specific thing right now." What supports this architecture is not documentation constraints, but the chaining of RFC 8693 and RFC 7523 standards, ensuring every hop is forced to re-verify and re-downscope permissions.

If your AI Agents have started interacting with internal systems, this is an architecture worth taking the time to understand—and you don't necessarily have to copy Athenz's implementation. The key is to understand the core principle that "every hop must re-issue, and the scope must get narrower," and apply it to your own authorization server.

[Dev Log][Node.js] Feedly Classic is gone, so I built my own FeedFlow (Part 1)

Evan Lin — Tue, 28 Jul 2026 05:12:29 +0000

Introduction:

Since Feedly's redesign, I haven't been able to get used to the interface. I especially miss the high-density, single-column, no-nonsense reading rhythm of the old Feedly Classic. My subscription sources include many English, Japanese, and Korean technical blogs. Every time I encountered them, I either had to open a new tab for translation or simply skip them. Over time, these sources became "read but ignored."

Instead of continuing to settle, I spent a weekend building my own RSS reader: FeedFlow. It features a mobile-first design, dark theme, and multi-column view modes—a tribute to Feedly Classic. Data is stored in Google Firestore, and accounts are tied to LINE Login. For non-Chinese articles, the background automatically uses Gemini 2.5 Flash to translate them into Traditional Chinese. It is currently deployed on Cloud Run, and I use it every day.

This repo will continue to be developed. This post is the first in a series, documenting the skeleton of the entire project and the context behind several key decisions.

TL;DR

This article will introduce:

Why build an RSS reader from scratch
The significance of LINE Login in this project
The RSS reader development process: From standalone MVP to multi-user cloud sync
Why Gemini was chosen as the translation engine and the pitfalls encountered
Frontend interface: Four view modes and mobile-first design
An unexpected interlude: Cleaning leaked keys from git history
Current progress and the direction of the next post
Conclusion
Reference links

Why build an RSS reader from scratch

There is no shortage of RSS readers on the market, but what I wanted was very specific: it needs to be fast on mobile, have high information density (no big images taking up the whole screen for every article), and allow for in-place translation of foreign sources without switching tabs. These three conditions combined are not fully met by any existing service, especially "automatic translation of non-Chinese articles," which is almost never treated as a first-class citizen in other readers.

The project is named FeedFlow, and its core consists of three parts: an Express backend (server.js) responsible for fetching RSS, parsing content, calling Gemini, and reading/writing to Firestore; a frontend using pure Vanilla JS ES Modules (app.js, store.js, api.js, i18n.js) without any frameworks; and Firestore for the database with LINE Login for accounts. The first MVP version produced subscription management, folder categorization, four view modes, and a dark theme. Every subsequent version has been built upon this skeleton.

The significance of LINE Login in this project

I previously wrote about How to develop OAuth2 PKCE via Golang, which discussed the implementation details of introducing PKCE to LINE Login. At that time, LINE Login was the subject of research for deconstructing the protocol. In FeedFlow, LINE Login takes on a different role—it is the key to making the multi-user architecture viable.

FeedFlow initially didn't have an account system; data was stored in the browser's localStorage. If you switched devices, your subscriptions would disappear. To achieve cloud sync, the first step was to have a stable user identity that could serve as a key for document paths in Firestore (users/{userId}/...). Instead of building a custom username/password system, using the LINE User ID (sub claim) obtained via LINE Login as this key saved me from building the entire password, verification email, and "forgot password" flow. For a personal project, this was much more cost-effective.

This decision wasn't made all at once. The earliest version was a "lazy" version: letting users paste a LINE UID string, which the backend just used as a Firestore key without any authentication. This kind of "login" meant anyone could impersonate any UID. The next version switched to formal LINE OpenID Connect: a standard OAuth 2.1 authorization code flow. After obtaining the id_token, the signature is verified using LINE's /oauth2/v2.1/verify, and the session is stored in an HTTP-only cookie rather than being passed around in URL parameters. Later, state and nonce checks were added to block CSRF. This "get it working first, then get it right" sequence reflects the typical rhythm of personal projects: get the features working to confirm the direction, and fix security holes once the need is visible.

Since the primary use case is sharing links within LINE and opening them in the LINE in-app browser, I also integrated the LIFF SDK. This allows users opening the app within LINE to log in directly using LIFF's SSO without being redirected to an external browser.

The RSS reader development process: From standalone MVP to multi-user cloud sync

The features during the MVP stage weren't much different from a standard RSS reader: paste a URL, the backend parses the feed using rss-parser, and if no feed is found, it uses cheerio to scan the webpage's <link> tags for auto-discovery. Subscribed sources can be categorized into folders; articles can be marked as read or "mark all as read"; and a refresh function pulls the latest articles. In this version, all data was still stored in localStorage.

What truly made the project "feel like a product" were the versions after connecting to Firestore. Each user's subscription list, folders, reading progress, and preferences are written to independent paths under users/{LINE_UID}/..., ensuring multi-tenant data isolation. Reading progress is tracked in detail: not just a list of "read article" IDs (readArticleIds), but also which article was last read for each feed (lastReadArticleId), allowing users to pick up where they left off across devices.

An interesting small mechanism is "auto-hydration": when Cloud Run redeploys or a user logs in on a new device, there is no article data in memory, only the subscription list in Firestore. At this point, the backend re-fetches and parses each feed in the subscription list in the background to populate the screen. Users don't see an empty "please subscribe first" screen; the transition is quite natural.

Later, a "rich preview" version was added: when an RSS URL is pasted, in addition to fetching the feed title and description, it also grabs the latest three articles as samples. Non-Chinese content is sent to Gemini for translation, so users can understand what the source is about before actually subscribing.

Why Gemini was chosen as the translation engine and the pitfalls encountered

Translation was necessary because the subscription list contains many non-Chinese sources. The logic is simple: the backend detects the article language; if it's not Traditional Chinese, it's sent to Gemini 2.5 Flash, which returns a JSON structure with translatedTitle / translatedContent. The frontend adds a "✨ Trad-Ch" translation badge to article cards and the reader, and the reader includes a button to toggle between the original text and the translation. Choosing Gemini was straightforward: the latency and cost of 2.5 Flash are suitable for this "translate several articles upon entering the screen" usage. Other APIs could do it, but I was already using this GCP project, so it was easy to integrate.

The first version was the most direct: using GEMINI_API_KEY to call the Generative Language API. It worked, but after deploying to Cloud Run, it meant managing an extra set of API Key environment variables, increasing the risk of key leakage. Later, I changed the translation part to use Vertex AI, authenticating with the Cloud Run service's own identity (ADC, Application Default Credentials). This eliminated the need for a separate API Key—the Cloud Run service account itself has permission to call Vertex AI; you just need to set the IAM permissions. When the ADC environment is unavailable during local development, it falls back to GEMINI_API_KEY.

After this version went live, a whole batch of translation requests failed in the Cloud Run logs with the message: "Neither Vertex AI ADC self-identity nor GEMINI_API_KEY is available," even though both paths were configured. Upon investigation, I found I had misused the @google/genai SDK: it requires a boolean vertexai: true along with project and location as parallel parameters. I had initially written it as a nested vertexai: { project, location }. The SDK's logic for "is Vertex mode on" and "did it read project/location" were separate; consequently, the SDK thought Vertex mode was on but couldn't find the project or region, causing every call to fail at the start.

Instead of wrestling with the SDK's parameter rules, I eventually removed the @google/genai package entirely. I used google-auth-library's GoogleAuth to directly request an ADC token and constructed the HTTP request to the Vertex AI generateContent REST endpoint myself. With one less layer of SDK abstraction, the behavior became much more predictable. In cases like this, bypassing the SDK and hitting the REST API directly is often easier than digging through documentation to find which parameters should be nested or parallel.

Frontend interface: Four view modes and mobile-first design

The reference point for the interface design was Feedly Classic: a view mode toggle button in the top right, with four modes applying different layouts to the same article data without re-fetching.

Mode	Features
Magazine	Default mode, summary cards with images and text, suitable for quickly scanning titles and snippets.
List	High-density text-only list, showing the maximum number of articles at once.
Title Only	Only titles are kept, allowing for the fastest scrolling speed.
Cards	Visual cards focused on large images, suitable for sources with rich visual content.

The sidebar uses a folder structure, listing each folder and uncategorized subscriptions with unread count badges. The article list and the reader are two separate panels; clicking an article slides it from the list into the reader, and a swipe-up gesture slides it back to the list. The operation logic follows mobile native app habits rather than the typical web behavior of full-page jumps. The overall theme is dark. The top bar contains icons for the menu, view modes, mark all as read, refresh, and settings. After logging in, the LINE display name appears where the "LINE Login" button used to be.

In the settings page, "Interface Language" and "Translation Target Language" are split into two independent options. The interface currently supports zh-TW / en / ja. The translation target language determines which language Gemini translates foreign text into. There's no reason to tie these together; a user might want an English interface but still want to translate Japanese articles into Traditional Chinese.

Current progress and the direction of the next post

As of writing this, two new documents have been added to the repo (docs/superpowers/specs/ and docs/superpowers/plans/) to plan for paginated browsing of the article list—five articles per page, supporting swipe gestures, mouse wheels, and buttons for navigation. This part is still under development and will be the subject of the next post in this series.

Conclusion

FeedFlow currently solves a simple problem: quickly scanning a bunch of foreign technical articles on mobile without switching tabs for translation or enduring a bloated interface. Three decisions support this architecture: LINE Login provides user identity without a custom account system, Firestore enables multi-user cloud sync, and Gemini 2.5 Flash (via Vertex AI ADC, without storing API Keys locally) handles translation. None of these were perfect on the first try—LINE Login evolved from string pasting to formal OAuth, and translation moved from raw API Keys to service identity authentication. It was all about getting it running first and then strengthening it.

Reference Links:

[Book Sharing] Tsaisang’s Tales of the Strange: Japanese Mythology, Ghost Stories, and Sometimes Taiwan

Evan Lin — Thu, 23 Jul 2026 13:25:47 +0000

Tsai-sang Talks About the Strange
Japanese Myths and Spiritual Ghost Stories, and Sometimes Taiwan
Rated by 73 people
Author: Tsai Yi-chu  Publisher: Eurasian Publishing Group

Foreword:

This is the first book I finished reading in 2026. I didn't write any book reviews in the first half of this year because I only read a little bit of many books. I spent quite a long time reading this one as well; I happened to see it while looking for books, and it turned out the second half of the book was quite captivating, so I finished it all in one go.

Synopsis

Not just crazy, but crazier! Tsai Yi-chu a.k.a. the Chuunibyou Professor of Folklore unleashes a flood of ghost stories!

◆ How do Japan's first generation of gods play out soap opera dramas every day?
◆ How does Japanese mythology hide various "sexual metaphors" in its stories?
◆ Yokai aren't all troublemakers; which ones can make you rich or send you to heaven?
◆ Is there bullying in the world of Yokai? Can just getting old and ugly make you a Yokai?
◆ Is the Jade Emperor actually not a CEO? Is Guanyin Bodhisattva actually a foreigner?
◆ Can Taiwan also have "Shigong (Priest) Watches" and "Yokai Pokémon"?

Taiwanese people fear ghosts, Japanese people fear ghosts, people all over the world fear ghosts...
It doesn't matter if you haven't seen "Ghost Stories," come here to listen to Tsai-sang talk nonsense and discuss gods and ghosts, so you won't feel "creepy" anymore!

Most people's impression of Japan is—endless temples to visit, super cute and otaku cosplayers, AV actresses... Hey! There must also be supernatural stories, Sadako, Yokai, and various urban legends!

Listen to how Tsai-sang combines hair-raising ghost encounters with historical stories passed down through the ages, and see how he uses super "grounded" slang to reveal the cultural meanings behind Japanese mythology!

Japanese Folklore PhD Tsai Yi-chu has gathered years of research on folklore, using myths and ghost stories as a medium and easy-to-understand "netizen" language to lead readers into Japan's "Gods and Monsters." This includes the genealogy of Japanese gods, the connection between Yokai and culture, and the hidden meanings within. At the same time, he allows Taiwan's various gods to actively participate in the text through a Taiwan-Japan friendly crossover, making you understand ghost talk and become obsessed with gods and ghosts! After reading, I guarantee your mom will ask why you are reading this book on your knees!

Because "Tsai-sang Talks About the Strange" will make you shout on your knees: "What on earth was Japanese mythology on? I want some of that too!"

This book isn't one of those stiff academic papers; it's a cultural analysis book where Tsai Yi-chu (Tsai-sang), a PhD in Folklore from the University of Tsukuba, uses super "grounded" netizen slang and a hilarious style to strip down Japanese mythology and spiritual ghost stories for you! The most brilliant part is that he doesn't just talk about Japan; he occasionally pulls back to Taiwan's folk perspective for comparison.

Here are the three core sections and key points of this book refined for you:

Summary of the Three Core Sections

Section Category	Core Research Focus	Tsai-sang's "Taiwanese-style Plain Language Interpretation" and Highlights
1. Japanese Mythological Prototypes	The birth of Japan's first generation of gods (Izanagi, Izanami, Amaterasu, Susanoo) and the belief in vengeful spirits in history.	Uses "Sex and violence, gore and SOD collections" to roast the absurd plots of Japanese mythology. Introduces the "Vengeful Spirit Fan Club" of ancient Japanese history and endemic species like Tengu.
2. Yokai and Urban Legends	How rural ghosts and monsters evolved into modern urban legends over time (e.g., Slit-Mouthed Woman, Super High-Speed Granny).	Yokai are "new pets of urbanization," reflecting the collective anxiety and loneliness of modern people, and the media's role in fueling the supernatural trend.
3. And Sometimes Taiwan	Cross-sea interactions and cultural comparisons of beliefs between Taiwan and Japan (e.g., Nagasaki Mazu and Tainan's General Flying Tiger).	Demonstrates a "Taiwan-Japan Friendly Crossover." Reflects on Taiwanese people's own cultural roots and subjectivity through the lens of Japanese ghost stories.

I. Japanese Mythology: A First Family More Dramatic Than a Soap Opera

Love and Hate of the First Family: The fallout process of Japan's creator gods (Izanagi and Izanami) is absurd and horrifying (the wife turns into a rotting corpse in Yomi, the husband is so scared he flees and divorces). Their descendants, the Sun Goddess Amaterasu and her brother Susanoo, also have a love-hate relationship. Tsai-sang jokingly says that from a modern perspective, these plots are simply a collection of various horror and gore scenarios.
Vengeful Spirit Fan Club: Many high-ranking gods worshipped in Japanese history (such as Sugawara no Michizane, the God of Learning, and Emperor Sutoku) were actually "victims of political struggles who died miserable deaths." Because later generations feared they would become vengeful spirits and seek revenge, they quickly built shrines to worship them as gods, forming Japan's unique culture of vengeful spirit worship.

II. Yokai and Urban Legends: Collective Anxiety of Modern People

Yokai are the City's New Pets: Former Yokai (like Kappa and Yama-uba) lived deep in the mountains and forests, representing human awe of nature. After urbanization, Yokai also "moved into the city," evolving into urban legends like the Slit-Mouthed Woman and the Super High-Speed Granny.
Reflecting the Loneliness of Real Society: The birth of these modern legends appears to be horror stories on the surface, but at their core, they reflect the alienation and collective anxiety of urbanites. At the same time, the book reviews the "rise and fall of the supernatural craze" fueled by Japanese mass media (TV supernatural programs) for ratings in the 80s and 90s.

III. And Sometimes Taiwan: The Mysterious Connection Between Taiwanese and Japanese Gods and Ghosts

Japanese-speaking Mazu and Japanese Gods: The book specifically mentions the intertwining of Taiwanese and Japanese beliefs. For example, there are several Mazu temples in Nagasaki, Japan, where Mazu "speaks Japanese" due to localization. Meanwhile, in Tainan, Taiwan, there is the "General Flying Tiger Temple," which enshrines Shigeo Sugiura, a Japanese pilot who sacrificed himself to protect Taiwanese villagers during WWII.
Folklore is the "Study of People": Tsai-sang emphasizes that whether studying Japanese mythology or Taiwanese supernatural phenomena, what is ultimately terrifying or absurd is not the ghosts and monsters, but the human society behind them. Belief can soothe the soul because it reflects the logic of contemporary thinking.

Core Quote of the Book:

"To understand people is to understand ghosts; Yokai and spirits are all imaginations based on reality."

We must discover the main reasons why each phenomenon forms. When we use Japanese ghost stories as a mirror to deeply understand the workings of folklore and legends, we can then look back with clearer eyes to discover and identify the cultural identity that belongs to "Taiwan itself."

Reflections

This book is full of many rural legends, and the final section, which includes one of his research reports and actual events, will leave you astonished. First, the book begins by sharing stories of Japanese ghosts and monsters, reflecting on the origins of many ghost stories behind Japanese mythology. It also discusses the connection between Japanese sex and violence and their many ghost stories.

The second part shares some Taiwan-related stories and also discusses the origin of the "Turbo Granny" in Dandadan and the stories related to the Slit-Mouthed Woman. These will make you want to read it all in one breath. As the Ghost Month seems to be approaching again recently, it seems this series of books will become popular again. Everyone should check it out.

[Book Sharing] Taiwan's AI Future: Analyzing Trends, Local Landscape, Corporate Strategy, and Personal Development

Evan Lin — Thu, 23 Jul 2026 13:25:21 +0000

Taiwan's AI Future
Analyzing the latest AI trends, Taiwan's situation, corporate strategies, and personal development
Author: Chien Lee-feng, Hsiao Yu-pin  
Publisher: Business Weekly

Preface:

This is the second book I finished reading in 2026. It is a fairly new book, released at the end of 2025. I bought it because my company invited Chien Lee-feng to give a speech in 2024. Later, I happened to see his book on my e-book shelf and decided to take a look.

Outline

When AI rewrites the world, what is Taiwan's next step?
Former Managing Director of Google Taiwan, computer scientist, and AI scholar—Chien Lee-feng
Writes the first instruction manual for the AI era for Taiwan,
Helping Taiwanese people understand the opportunities and challenges of the AI age!

The world undergoes a digital revolution every ten years:
● 1990: Personal computers start the computer generation;
● 2000: The Internet creates the web generation;
● 2010: Mobile devices and social media lead the mobile generation;
● 2020: Generative AI like ChatGPT makes a shocking debut...
Now is the AI generation, where the rules of the game are completely rewritten, and the gap is rapidly widening between 1:99.
Will you fall behind and be eliminated, or seize the opportunity and become a 1% winner?
This book takes you deep into the AI landscape to master the key to transformation!

【AI Development under Geopolitics】
As the world undergoes an AI-driven paradigm shift, the US sees AI as the key to its return to hegemony. This not only predicts that AI productization will completely subvert the world's rules of operation but also opens up infinite possibilities for the future evolution of AI. From the "Manhattan Project" to the "Stargate" layout, this book will deeply analyze the global situation under the US-China tariff war and provide insights into how AI reshapes the international order.
● The 1:99 challenge: Countries, companies, and individuals who seize the opportunity may become the unique "1" that far surpasses others, while others become the "99" lagging far behind.
● The emergence of DeepSeek has subverted the US monopoly, bringing a "rebalancing" to the AI world, equivalent to inventing the "poor man's atomic bomb."
● If the pace of domestic chip production is not accelerated, an unproductive America will have no tomorrow and will directly lose competitiveness in the AI battle. TSMC has thus become the X-factor in the US-China confrontation.

【Taiwan Looking at the World】
The AI wave is sweeping the globe; this is not just a technological innovation, but a key turning point for national development. In this giant wave, Taiwan not only has the uniquely endowed "Silicon Shield" TSMC but also sees a golden decade to become "the world's Taiwan" as AI challenges and opportunities coexist. This book gives you a glimpse into the future potential of Taiwan's manufacturing industry and how old and new enterprises are redefining "Made in Taiwan."
● Facing geopolitical changes, Taiwan's manufacturing-oriented enterprises should go with the flow. Through overseas production and R&D in Taiwan, they can create a "Taiwan + N (foreign)" model, helping Taiwan remove the red supply chain and join the US-led supply chain.
● An island's market is always outside. Flying to Japan or the US for travel or business for a few days does not equal internationalization. Internationalization is daily life being impacted by different cultures.

【AI Practice in All Walks of Life】
The AI era is a key moment for corporate transformation and talent reinvention. Only companies that dare to pivot will have competitive opportunities. This book lists cases of how companies in different industries respond to AI and provides practical strategic directions to guide Taiwan's corporate transformation to seize the AI market and move towards growth and innovation.
● The impact of AI can be compared to "musical chairs." From tech giants to SMEs, whether it's "emptying the cage for new birds" (industrial restructuring) or empowering employees, wherever the wind blows, new opportunities lie there.
● "Old-ventures + New-ventures": Shifting from software integration to hardware-software integration, combining the advantages of both, makes AI applications possible.
● Developing Sovereign AI doesn't end with outsourcing. Whether building your own model or asking tech giants for help, the strategy must be planned clearly, otherwise, it might just be a waste of money.

【Mastering the Golden Key to Personal Learning and Career】
As a member of the AI generation, how to use AI to improve learning efficiency while clearly identifying AI's limits is an important task. This book suggests how to use AI tools while pointing out that human differentiated experience will become an irreplaceable treasure. Therefore, cleverly accumulating personal unique value is the only way to remain invincible in the AI era.
● AI likes to use certain specific sentence patterns because AI is a probabilistic concept, so naturally, there are some patterns. But conversely, precisely because its data volume is large enough, it can try various combinations that humans have never seen.
● AI has raised the "passing line" of many jobs from 60 to 80 points in one fell swoop, forcing all industries to redefine the core competencies and value of human labor.
● In the AI era, senior talents with professional foundations learn AI the fastest because their long-term accumulated knowledge can judge the correctness of AI-generated content. This AI paradigm shift has, in turn, amplified the advantages of the older generation.

This is an AI survival guide tailored for Taiwan, helping you fully grasp the context of the AI revolution and find the path to growth for the nation, enterprises, and individuals amidst the changes.

This book can be described as an "AI Era Survival Manual" tailored for Taiwanese people and businesses by Dr. Chien Lee-feng, former Managing Director of Google Taiwan, and senior media professional Hsiao Yu-pin. Dr. Chien uses a very pragmatic and precise local perspective to analyze how Taiwan should reposition itself, how companies should play the international game of hardware-software integration, and how individuals can avoid falling into the crisis of "brain outsourcing" under this crazy AI wave.

I have organized the four core frameworks of the book for you to help you grasp the overall context through this overview:

Overview of the Book's Four Core Frameworks

Category	Core Pain Points & Trends	Breakthrough Strategies for Taiwan & Individuals
1. Latest AI Trends	AI brings high centralization and unification, potentially evolving into a 1:99 disparity in capabilities and resources; however, the rise of emerging forces like DeepSeek is bringing "rebalancing" opportunities to the world.	Understand the essence of AI's "probability and language architecture," find breakthroughs outside of US monopolies, and raise the lower limit of basic capabilities.
2. Taiwan's Positioning	Although Taiwan is a key X-factor in geopolitics and AI chips, it also faces structural constraints like island involution, a declining birthrate, and the "five shortages."	Completely shift from a "farmer's mindset" to a "navigator's mindset," taking "going global" as the only way to survive, and stepping beyond Taiwan's borders to expand digital territory.
3. Corporate Transformation	Taiwan is "extremely strong in hardware, extremely weak in software." Software startups lacking computing power and business scenarios find it hard to survive independently on the international stage.	Promote "Old-ventures (hardware giants) + New-ventures (software applications)" collaboration, using Edge AI to add "brains" to powerful hardware devices.
4. Personal Development Keys	Facing the invisible crisis of "brain outsourcing," mediocre professional newcomers who only teach by the book and lack practical experience will be the first to be hit.	Shift from a "problem-solving" habit to a "problem-posing" mindset, creating unique value through high-frequency "repeated interaction and correction" with AI.

I. Latest AI Trends: The 1:99 "Superhuman" Challenge

Extreme Concentration of Power: The AI era has brought high centralization, with global tech giants holding a massive advantage. Among thousands of languages worldwide, only about a hundred can be used in mainstream AI, and English and Simplified Chinese are deeply optimized. This means language and cultural frameworks are the primary keys to mastering AI.
The 1:99 Watershed: The cruelest part of this tsunami is not the elimination of ordinary people at the bottom (AI actually raises the floor for ordinary people), but the elimination of "mediocre professionals." The 1% who seize the opportunity will become superhumans through AI, taking the capabilities and opportunities of the 99%, while others become the lagging 99%.
Rebalancing the AI World: The recent emergence of non-US low-cost, high-efficiency models has broken the absolute monopoly of US tech giants. This has been described as inventing the "poor man's atomic bomb," bringing an opportunity for a reshuffle to countries and enterprises with fewer resources.

II. Taiwan's Situation: From "Island Involution" to the "Age of Discovery"

The Geopolitical X-Factor: TSMC and Taiwan's hardware supply chain hold a key position in the US-China tech confrontation because Taiwan possesses the characteristic of "knowing the demand earliest" (e.g., being able to grasp system requirements like server voltage changes first), giving it an important identity in the adjustment of global infrastructure.
Breaking the Farmer's Mindset: Most Taiwanese companies are used to an "island mindset," where the "sea is invisible" in daily life, making it easy to fall into involution within a comfortable echo chamber. Facing the structural crisis of a declining birthrate and plunging newborn numbers over the next 20 years, Dr. Chien urgently calls for a shift to a "navigator's mindset," because "going global" is the only way for all industries in Taiwan to survive.
Extension of Digital Territory: Taking TSMC as an example, AI allows Taiwan to replicate factories overseas and have them operated remotely by Taiwanese engineers. Taiwan should also turn the crises of aging and labor shortages into opportunities by actively developing robotics and its own Sovereign AI to avoid a national-level digital divide.

III. Corporate Layout: Hardware-Software Integration, Letting "Old-ventures + New-ventures" Dance Together

Using Edge AI to Add Brains to Hardware: Edge AI (referring to terminal devices having local computing power without relying entirely on the cloud) is Taiwan's domain. It is hard for pure software startups in Taiwan to compete with international giants, but we can embed and bundle AI services directly into powerful hardware devices used worldwide (such as Giant bicycles or various terminal equipment), significantly increasing added value.
Old-ventures plus New-ventures Playing the International Game: Today's AI startups can hardly succeed without the data, computing power, and real "business scenarios" provided by a "rich father." Therefore, hardware giants (Old-ventures) should join hands with software startups, combining the international channels of the former with the flexible applications of the latter to go global as a team.
Pragmatic Planning for Sovereign AI: Developing Sovereign AI cannot just be about blindly outsourcing business to tech giants. Whether building their own models or cooperating with major manufacturers, enterprises must clearly plan their own strategies and field applications; otherwise, it is just a waste of money.

IV. Personal Development: Refuse "Brain Outsourcing," Be a High-Level "Questioner"

Shift Thinking from "Solving" to "Posing": AI's capabilities are "asked" out. The more professional the question, the more accurate the response. The future workplace will no longer value rote memorization; core competencies will shift to problem definition, critical thinking, and direction control. Only "questioners" who can demonstrate proactive influence will win.
Using "Iterative Refinement" to Deepen Learning: If you just throw a question to AI, get an answer once, and copy it directly, this behavior is equivalent to plagiarism. However, if you can go back and forth with AI to modify it 10 times, that is a "learning" process; if you continue to repeatedly correct and adjust up to 100 times, that is truly approaching the level of "creation."
Accumulating Irreplaceable "Differentiated Experience": Functions like memory and calculation can be outsourced to AI, but your unique personal experience, cross-disciplinary collaboration ability (π-shaped talent), and human critical thinking are the irreplaceable treasures of the AI era. Cleverly using AI tools to amplify your output is the only way to avoid becoming the "lost generation" eliminated by the times.

The Core Soul Quote of the Book:

"Change is humanity's eternal unease, but from a macro perspective, what AI brings is an opportunity to make humans more capable." When calculation and memory are outsourced from the brain, be sure to retain your power of thinking and creation.

This video Interview with Dr. Chien Lee-feng: Who is the Lost Generation of the AI Era deeply explores the "1:99 Superhuman Challenge" and workplace mindset transformation mentioned in the book, helping you more intuitively understand how to retain personal competitiveness in this era of brain outsourcing.

Personal Thoughts

From my own perspective, this book organizes many recent AI development processes both domestically and internationally. It provides many future insights based on Chien Lee-feng's own experience as the former Managing Director of Google Taiwan. It often shares advice on how various industries should face the AI era. This part is frequently mentioned in his speeches and is shared and explained quite clearly.

Personally, I feel that one can just skim through this book. In comparison, I still prefer Dr. Chien Lee-feng's speeches, which provide more impact and inspiration.

[GCP in Action] LINE Business Card Bot Evolution: Dual-Side Recognition and Merging with Gemini

Evan Lin — Thu, 23 Jul 2026 13:24:50 +0000

Pain Point: One Chinese Business Card is Actually Two Business Cards

Business cards in Taiwan often have a common design: Chinese printed on the front and English on the back (or vice versa). Our LINE business card bot's original logic was very simple: receive an image, perform OCR once, and save one record.

This is where the problem lies. When a user sends the front side, the bot saves a record with only the Chinese name. If the user then sends the back side, the bot treats it as "another new business card," resulting in two records for the same person in the database, each missing half the information. Users have to manually compare and delete duplicate data, which is a terrible experience.

This article records how we taught the bot to recognize that "these are two sides of the same business card" and merge the information from both sides into a single complete record.

Solution: First Ask, "Is there a back side?"

Instead of writing rules to guess if two images are the same business card, we chose a more direct approach: Ask the user.

The workflow is designed as follows:

The user sends the front of the business card, and the bot performs OCR as usual.
After OCR is complete, the bot does not save immediately. Instead, it replies with "📇 Front side data recognized. Is there a back side to this card?" and provides two Quick Reply buttons.
User clicks "No, save directly" → Save according to the original process and finish.
User clicks "Yes, there's a back side" → The bot remembers the front image and waits for the next image.
Once the back side image arrives, both images are sent to Gemini together to be merged into a single record before saving.

We manage this waiting state using the user_states memory dictionary already present in the project, and add a 5-minute timeout. If a user clicks "Yes, there's a back side" but then ignores it or does something else, the process is treated as abandoned after 5 minutes, preventing the entire workflow from getting stuck.

user_states[user_id] = {
    'action': 'pending_backside_confirm',
    'card_obj': card_obj,
    'front_image_bytes': image_content,
    'expires_at': time.time() + PENDING_BACKSIDE_TIMEOUT_SECONDS
}

Core: Let Gemini See Two Images at Once and Merge Them

The most critical technical decision was: should we recognize the front and back sides separately and then write code to merge them? We chose another path: wrapping both the front and back images in a single generate_content request and letting Gemini handle the judgment directly.

The reason is simple: merging Chinese and English names into a format like "Wang Daming David Wang" using string rules is prone to being messy and inaccurate. Semantic-level integration is more likely to fail with hardcoded rules, so letting Gemini handle it directly is much easier.

In app/gemini_utils.py, we added generate_json_from_two_images, which reuses the existing NAMECARD_SCHEMA structured output, but this time the contents includes two image Parts:

def generate_json_from_two_images(
        front_img: PIL.Image.Image,
        back_img: PIL.Image.Image,
        prompt: str) -> object:
    model = GenerativeModel(
        "gemini-3-flash-preview",
        generation_config={
            "response_mime_type": "application/json",
            "response_schema": NAMECARD_SCHEMA
        },
    )
    front_part = Part.from_data(
        data=pil_to_bytes(front_img), mime_type="image/jpeg")
    back_part = Part.from_data(
        data=pil_to_bytes(back_img), mime_type="image/jpeg")
    response = model.generate_content(
        [prompt, front_part, back_part],
        stream=False,
        labels={"client_id": "namecard"}
    )
    return response

The prompt also just adds a merge instruction after the original IMGAGE_PROMPT:

DOUBLE_SIDED_IMAGE_PROMPT = IMGAGE_PROMPT + """
These two images are the front and back of the same business card; please integrate them into a single complete record.
If both Chinese and English appear in the same field (such as name or company), please present them merged
(e.g., "Wang Daming David Wang");
if a field appears on only one side, use the value from that side; ignore obviously redundant information.
"""

One API call means we don't have to write or maintain any merging rules ourselves.

Two Easily Overlooked Pitfalls

During the overall code review before the feature went live, we caught two details that are easily overlooked but can really cause issues.

Pitfall 1: Timing of Duplicate Checks

Originally, the duplicate check (comparing if the email already exists) was done immediately after OCR. However, after the double-sided recognition went live, if the front side happened to have a duplicate email from an old record, the process would prematurely determine it "already exists" and end. This would mean any new email on the back side would never be seen.

The fix was to move the duplicate check later, performing it only after "single-side chosen not to merge" or "double-sided merge complete." This ensures we are always comparing the final version of the data:

async def _finalize_and_save_card(card_obj, event, user_id) -> None:
    existing_card_id = firebase_utils.check_if_card_exists(card_obj, user_id)
    if existing_card_id:
        # ... Reply already exists
        return
    card_id = firebase_utils.add_namecard(card_obj, user_id)
    # ... Reply save successful

Both the single-sided and double-sided merge workflows eventually converge to call this shared function, ensuring the duplicate check is executed only once when the data is finalized.

Pitfall 2: Don't Clear All States Indiscriminately

The user_states dictionary is actually shared by several features: editing memos, modifying fields, and this back-side recognition. The initial implementation, for convenience, would delete the entire state whenever a residual state was detected before processing a new event.

The problem is: if a user is "editing the phone field" and waiting to input a new number, but accidentally sends an image, this logic would clear the editing_field state as well, silently canceling the user's original editing operation.

The fix was to only clear the two states related to the back-side recognition process and leave other states untouched:

if state.get('action') in (
    'pending_backside_confirm', 'awaiting_backside_image'
):
    del user_states[user_id]

We later found a missing branch in the same logic; the part handling "operation expired" replies also cleared everything initially. It was only truly fixed after unifying it with the same selective judgment.

Incidental Resource Cleanup: Don't Let Back-Side Images Linger in Memory

The awaiting_backside_image state stores not just text, but also the raw byte data of the front image. If a user disappears after being asked "Is there a back side?", this data would theoretically stay in the process memory because the original design only checked and cleared timeout states during the "user's next interaction."

We added a sweep_expired_states() function, which runs immediately when a Webhook comes in. It clears all expired temporary states for all users, so we don't have to wait for the specific user to return for passive cleanup:

def sweep_expired_states() -> None:
    now = time.time()
    expired_user_ids = [
        user_id for user_id, state in user_states.items()
        if 'expires_at' in state and state['expires_at'] <= now
    ]
    for user_id in expired_user_ids:
        del user_states[user_id]

Whenever any user sends a message, it performs garbage collection for all users, ensuring that those who abandoned the process don't leave behind memory-consuming remnants.

Summary and Benefits

This double-sided recognition and merging feature makes the LINE business card bot much more aligned with the actual usage habits of Taiwanese users:

Single Recognition, Complete Data: Both sides are sent to Gemini at once, automatically merging Chinese and English fields, eliminating the need for manual duplicate comparison.
Non-Intrusive: Ignoring prompts, timeouts, or temporarily doing something else will naturally revert to single-sided storage without getting the workflow stuck.
Duplicate Checks Target Final Data: Ensures that comparisons are always made against the merged, complete version, so new information appearing only on the back side isn't missed.
Independent State Machines: The temporary state for back-side recognition only affects itself and doesn't interfere with other ongoing user operations.
Clean Memory Usage: Proactively cleaning up timeout states ensures that users who abandon the process don't leave an invisible memory burden.

The complete code has been pushed to GitHub, feel free to check it out!

[Digital Certificate Wallet] Advanced: Building "Visitor-Endorsed Issuance" – A Full-Chain DID Application as Both Verifier and

Evan Lin — Mon, 13 Jul 2026 08:01:01 +0000

(Source: Digital Certificate Wallet Official Website)

Premise:

The previous introductory version created an HR employee card system: colleagues apply for an employee card themselves and then use it to apply for "sports subsidies" and "childcare subsidies." The focus of that article was on separating the two roles: "Issuer" and "Verifier."

In this article, I want to take it a step further: what does it look like if a scenario needs to play both the verifier and issuer roles simultaneously to form a complete DID ecosystem chain? The scenario I chose is "Visitor Endorsement and Issuance"—this is also the one I felt best demonstrates the "full chain" when brainstorming five verifier applications.

By the way, this article will honestly document three pitfalls encountered during the development process, as those are the truly valuable parts of TIL (Today I Learned).

Code is here: https://github.com/kkdai/did-usecase-visitor
Online experience: https://did-usecase-visitor-660825558664.asia-east1.run.app

Scenario: Employee Access Control + Visitor Endorsement and Issuance

This lobby reception desk has two modes:

Employee Access Control / Event Registration: Employees present their employee cards using a digital wallet. The system only verifies "whether they are a valid employee." Once verified, the door opens or registration is successful. Fields like name, birthday, and number of children are not disclosed and remain in the wallet—this is selective disclosure.
Visitor Endorsement and Issuance (the protagonist of this article): An active employee presents their employee card to "endorse" the visitor. After verification, the system immediately issues a temporary visitor pass with an expiration time to the visitor's wallet.

The value of the second mode lies in connecting the two roles:

First act as a Verifier (verify employee card) → then act as an Issuer (issue visitor card) only after verification.

Compared to traditional paper visitor logs (copying IDs, holding physical IDs, piles of personal data at the counter requiring manual disposal), digital endorsement only leaves one piece of accountable information: "which employee endorsed it." Visitor data stays in the visitor's own wallet, and the pass can have an expiration time.

Architecture Decisions: Why not just modify the previous project?

This time, I started a brand new project and deployed it to a separate Cloud Run service instead of adding pages to the original HR project. Several considerations:

Static Frontend + JSON API: The original project used jade templates for server-side rendering. This time, it was changed to public/ static pages + a few JSON APIs (/api/access/qrcode, /api/access/status), separating the frontend and backend more cleanly.
Abstracting Wallet API calls into lib/wallet.js: In the original project, issuer/verifier calls were embedded in routes and duplicated. This time, they were extracted into three functions: requestPresentationQRCode(), getPresentationResult(), and issueCredential(), making it easier to maintain and test.
State changed to Memory: The original project wrote data to a single record.js file. Writing files in a stateless environment like Cloud Run causes issues. This time, a simple memory object was used (resets on restart, sufficient for demonstration purposes).
Reusing the same Sandbox Account tokens: The access tokens for the issuer/verifier are the same set as in the previous article, reused directly.

For the "holding an employee card" verification part, I first used the existing sports subsidy verifier ref as a fallback (if VERIFIER_ACCESS_REF is not set, use VERIFIER_SPORT_REF), so it could run without waiting for backend configuration.

Pitfall Record 1: Presentation successful, but the screen is stuck

This is a classic one. The phone scans the code, and the wallet completes the presentation, but the desktop page just won't move forward; it keeps polling.

First, checking the Cloud Run logs, I found that /api/access/status returns every 3 seconds, each time returning "unverified." I added a log line on the backend to print the original response from the verifier. After redeploying and testing again, I caught the truth:

{
  "data": [
    {
      "credentialType": "0028680530_line_school",
      "claims": [
        { "ename": "ename", "cname": "English Name", "value": "Lub" },
        { "ename": "join_company", "cname": "Join Date", "value": "2018-10-05" }
      ]
    }
  ],
  "verifyResult": true,
  "resultDescription": "success",
  "transactionId": "8cd7f37b-..."
}

See the problem? The field in the response is verifyResult (camelCase), and there is no code field at all. But I used the old logic from the previous article:

// Old (doesn't match current response)
const verified = data.code === 0 && data.verify_result === true;

data.code is undefined, and data.verify_result is also undefined (it's called verifyResult), so it's always false, always pending. Actually, the verification had already succeeded (verifyResult: true, resultDescription: "success"), but the field names I was checking didn't match—it seems the sandbox API response format has changed from snake_case to camelCase.

The fix was to change the logic to be compatible with both formats:

const verified =
  data.verifyResult === true || // New format camelCase
  data.verify_result === true || // Old format compatibility
  (data.code === 0 && data.verify_result === true);

TIL: When integrating third-party APIs, don't trust that "the logic that worked in the last version will work in this one." Sandboxes change. Adding a log line to print the raw response and comparing it is much faster than staring at the code and guessing.

Pitfall Record 2: Visitor card stuck at "Pending Issuance"

After the access control part worked, the visitor endorsement part got stuck—the screen showed "Visitor card pending issuance (issuer template not set)," and no card was actually issued.

I used curl to hit the issuance API /api/vc-item-data directly to see what it returned. I tested two scenarios:

Scenario A: Using employee template + correct employee fields → HTTP 200, and the full response contained these keys:

KEYS: ['id', 'content', 'pureContent', ..., 'qrCode', 'deepLink', 'expired', ...]
qrCode = data:image/png;base64,iVBOR... ← QR code that can actually be scanned into the wallet
deepLink = https://frontend-uat.wallet.gov.tw/api/moda/vcqrcode?...
expired = 2027-01-09T...

Scenario B: Using employee template + visitor fields (visitor_type, endorsed_by…) → HTTP 500 / 400 BAD_REQUEST.

The reason was clear: the employee template fields were isRequired: true (Name, English Name…), but I sent a bunch of visitor fields it didn't have, so it was rejected. And the successful issuance response actually includes qrCode and deepLink, which can be used directly for the visitor to scan and collect the card—my original parsing was correct; the bottleneck was purely "fields not matching the template."

So I designed two issuance modes, automatically switched by environment variables (HAS_VISITOR_TEMPLATE in the code):

Mode	Condition	Behavior	Card Face
Option 1 (fallback)	`VISITOR_VC_*` not set	Borrow the employee template, stuffing visitor info into its required fields (Name="Temporary Visitor", etc.) to issue the card	Displays as an employee card face
Option 2 (Formal)	`VISITOR_VC_*` set	Send `visitor_type / endorsed_by / valid_until` to the dedicated visitor template	Formal visitor pass card face

The advantage of Option 1 is that a real, collectable card can be issued without waiting for backend configuration (even if the card face is borrowed), allowing the entire chain to be tested first; for a formal card face, just go with Option 2 and build a dedicated template, with no code changes required.

Pitfall Record 3: Collection QR too small + Mobile layout

In the first version, I made the visitor pass look like a pretty little ID badge, and the collection QR was only 48px—the result was that it couldn't be scanned at all. This QR is meant to be scanned by "another phone" to collect the card; if it's too small, it loses its purpose.

Later, I changed the visitor card to a vertical layout, enlarging the collection QR to be the main body of the card (max 240px, white background with padding), with "Endorsed by / Valid until" information placed below. Both QRs (for presentation and collection) were also changed to clamp() responsive sizes, so they don't break the layout on mobile and are clear enough on desktop.

TIL: As long as a QR is "for others to scan," it must be treated as the protagonist of the layout, not as a decoration.

The Truth About "Automatic Expiration"

I originally thought I could specify "this visitor pass expires in 4 hours" for each card, but testing revealed that when issuing cards via /api/vc-item-data, the actual validity of the card follows the template settings (e.g., the employee template is issuance date + about half a year); it's not possible to specify a short expiration for individual cards.

So the "Valid until HH:MM" on the card face now is a display value calculated by the application layer, not a mandatory expiration enforced by the wallet. If a truly short-term visitor pass is needed, there are two ways:

When creating the visitor template, set the template's validity period to be short.
Or use the platform's scheduled revocation (revoke)—the issuance response includes fields like clearScheduleId and scheduleRevokeMessage, implying the platform supports scheduled revocation, but this requires integrating the corresponding API separately.

Deployment: Directly to Cloud Run from Source Code

This time, I used buildpacks to deploy directly from source code without writing a Dockerfile:

gcloud run deploy did-usecase-visitor \
  --source=. --region=asia-east1 --platform=managed --allow-unauthenticated \
  --set-env-vars="VC_SERNUM=607861,VC_UID=0028680530_line_school,\
ISSUER_ACCESS_TOKEN=...,VERIFIER_SPORT_REF=...,VERIFIER_ACCESS_TOKEN=...,\
VISITOR_TTL_HOURS=4"

To switch to the formal visitor card in Option 2 later, just add VISITOR_VC_SERNUM=<new template vcId>,VISITOR_VC_UID=<new template vcCid> to this --set-env-vars string and redeploy; HAS_VISITOR_TEMPLATE will automatically become true.

Summary and Future Outlook

The focus this time wasn't "making another demo," but three things:

The full DID chain is feasible: Playing both Verifier and Issuer in the same scenario—verifying one card and then issuing another—connects the ecosystem chain, and the experience is smooth.
Pitfalls are in the details: Field naming (verifyResult vs verify_result), mandatory template fields, QR size—these wouldn't be discovered without looking at the raw response and actually scanning with a phone.
Fallback design allows the demo to work first: No need to wait for every template/ref to be built on the backend; use existing resources to get the whole chain running first, then gradually switch to formal settings. The development rhythm is much better.

There are truly many application scenarios for digital certificate wallets; "visitor endorsement" is just one of them. The employee card from the previous article could also be extended to commissary discount redemption, seniority milestone gifts, childcare facility access, gym point accumulation... each is a new application for a "verifier." I look forward to seeing more creative scenarios being built.

[GCP Billing & Vertex AI] Solving Gemini Cost Allocation in a Single Project: Vertex AI Dynamic Billing Labels in Action

Evan Lin — Sun, 12 Jul 2026 15:09:09 +0000

Pain Point: How to Accurately Allocate Gemini API Costs Within the Same Project?

When developing enterprise-level LLM services or operating multi-tenant platforms, the question most frequently asked by finance and operations teams is:

"We have many different business lines and LINE Bots connected within the same GCP project. Every day, the Gemini Key costs all appear under the Gemini API category. Is there a way for us to split the costs based on different Gemini Keys or different users?"

Direct answer to your question: In Google Cloud Billing reports, it is not possible to directly display costs "based on different API Key names." The smallest attribution dimensions for Google Cloud billing reports are "Project," "Service," and "SKU (Product Line Item)." The system does not treat individual API Key strings as independent billing items. For the billing system, whether you create 10 or 100 API Keys within the same project, they will all be lumped together as a single Gemini API total.

A Workaround: Vertex AI "Request Labels" to the Rescue

If architectural constraints force you to stay within the same project, the most recommended approach is: switch to Vertex AI calls and use "Request Labels."

If you are currently using a Google AI Studio API Key, it cannot pass billing labels within a single project. However, if you change your code to call the Vertex AI Gemini API (still within the same project), Vertex AI supports dynamically including custom labels with each request.

Principle and Workflow

When sending each request (e.g., calling generateContent), include specific metadata in the API Request:

{
  "contents": { ... },
  "labels": {
    "client_id": "info_helper",
    "api_key_group": "marketing_team"
  }
}

These custom labels are passed directly to the GCP billing system. Later, when you go to the GCP Billing report and select your set label key (e.g., client_id) in "Group by," you can clearly see the costs for different labels (representing different services, clients, or users) within the same project!

Project Implementation: Full Adoption of the Labels Mechanism

To fulfill this requirement, we audited the current API call architecture of the LINE Bot project and performed the following refactoring.

1. Project API Call Audit

Through scanning, we found that the vast majority of calls in the project use Vertex AI (14 out of 17 clients use vertexai=True), with only a few exceptions:

Vertex AI calls: Including GitHub summaries, multiple Google Maps Grounding tools, text summarization, image analysis, speech-to-text, etc. (total of 11 files, 19 call points).
Gemini API Key calls: Live API in main.py, Batch service in batch_service.py, and TTS speech synthesis in tts_tool.py.

[!IMPORTANT] The labels parameter is only supported by Vertex AI. If this parameter is included under an API Key (vertexai=False), it will cause the SDK to throw an error. Therefore, we only modified the 11 files that use Vertex AI.

2. Implementation Method

For the google-genai Python SDK, we have two main modification scenarios:

Scenario A: Already contains `GenerateContentConfig`

If the original call already includes a Config, we just need to pass an additional labels={"client_id": "info_helper"} into the config:

# Before (e.g., loader/gh_tools.py)
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=prompt,
    config=types.GenerateContentConfig(
        temperature=0,
        max_output_tokens=2048,
    )
)

# After
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=prompt,
    config=types.GenerateContentConfig(
        temperature=0,
        max_output_tokens=2048,
        labels={"client_id": "info_helper"}, # Include billing label
    )
)

Scenario B: No Config parameter

If the original call is very simple (e.g., searchtool.py or youtube_gcp.py), we need to proactively include a GenerateContentConfig containing labels:

# Before (e.g., loader/searchtool.py)
response = client.models.generate_content(
    model="gemini-3.1-flash-lite-preview",
    contents=prompt,
)

# After
response = client.models.generate_content(
    model="gemini-3.1-flash-lite-preview",
    contents=prompt,
    config=types.GenerateContentConfig(
        labels={"client_id": "info_helper"}, # Add config to include label
    ),
)

3. List of Modified Files

We performed precise modifications on a total of 19 call points across the following 11 files, and used Python's AST module (ast.parse) and Flake8 for syntax and formatting checks before submission:

agents/chat_agent.py: Modify _create_chat_config() to add labels to both general Q&A and Grounding conversations.
loader/chat_session.py: Include labels in Chat session config.
loader/gh_tools.py: GitHub summary API.
loader/langtools.py: Text summarization, image JSON generation, social media post generation.
loader/maps_grounding.py: Maps search API.
loader/searchtool.py: Keyword extraction tool.
loader/youtube_gcp.py: YouTube video understanding API.
tools/audio_tool.py: Asynchronous speech-to-text.
tools/maps_tool.py: 5 call points including nearby search, restaurant name extraction, batch and review search, etc.
tools/summarizer.py: Text summarization and Agentic Vision image understanding.
tools/youtube_tool.py: YouTube summary tool.

Pitfall Guide: Watch Out for SDK Module Import Issues

When refactoring calls without Config for youtube_gcp.py and youtube_tool.py, since these two files originally only used named imports for specific types:

from google.genai.types import HttpOptions, Part

When we write types.GenerateContentConfig(...) in the code, the system throws a NameError: name 'types' is not defined error.

Solution: We need to correct the import statement and directly import GenerateContentConfig:

# Before
from google.genai.types import HttpOptions, Part

# After
from google.genai.types import HttpOptions, Part, GenerateContentConfig

And use it directly in the call without the types. prefix:

config=GenerateContentConfig(labels={"client_id": "info_helper"})

Summary and Next Steps

This modification successfully injected the client_id=info_helper label into all Vertex AI API calls within the LINE Bot project.

Billing Delay: Please note that after we start including labels, GCP billing data usually has a 24 to 48-hour delay before taking effect.
Configure in GCP Billing: After two days, you can go to the GCP Console -> Billing -> Reports. In the "Group by" section on the right, select Labels and enter our key client_id.
Mission Accomplished: At this point, the report will draw info_helper as a separate billing row, perfectly solving the problem of separating project costs for reimbursement and statistics!

[AI in Action] Refining a macOS Meeting Translation App with Claude Code: Auto-reconnect, Floating Captions, and Meeting Minutes Export Evolution

Evan Lin — Sun, 05 Jul 2026 11:00:46 +0000

Foreword: Round Two, Switching to a Sharper Tool

In the previous article, we used AGY CLI (Antigravity) to build a macOS real-time meeting translation App from scratch: capturing audio from Zoom / Google Meet via ScreenCaptureKit, sending it to the Gemini Live API for real-time translation, and displaying Traditional Chinese bilingual subtitles in the App window.

After the App went live, the developer discovered several issues during actual meetings that raised eyebrows, while also coming up with more functional ideas. This time, we switched to Anthropic's Claude Code to start the second round of deep polishing in the terminal.

The following records the complete dialogue flow of this collaboration, restoring every key decision point.

Phase 1: Uncovering Hidden Dangers — The Mystery of the WebSocket Stopping After 10 Minutes

The App seemed to work perfectly, but the developer returned with a question after a real, long meeting:

User: Check this code. Why does the real-time translation stop after about ten minutes? Help me look into possible reasons.

Claude Code read all five Swift source files and, combined with the built-in Gemini Live API documentation, precisely pointed out the root of the problem:

The Gemini Live API's WebSocket connection has a Session limit of about 10 minutes. Once the time is up, the server actively closes the connection and sends a GoAway signal. However, the original code was completely unprepared for this scenario, causing a three-layer failure:

No reconnection after disconnection: The didCloseWith callback only updated the status text on the UI without any reconnection logic.
Silent audio discarding: After isConnected = false, every audio chunk from the microphone was silently consumed by guard isConnected else { return }, without the user noticing.
Incorrect isRunning state: The "Translating" icon in the main window was still flashing, but in reality, nothing was happening.

Claude Code immediately refactored GeminiLiveConnection.swift, introducing three lines of defense without changing any external interfaces:

Proactive GoAway Signal Detection: Parse the goAway JSON message sent by the server in parseServerResponse(), and actively reconnect before the connection actually drops to achieve seamless translation continuity.
Exponential Backoff Auto-Reconnection: After disconnection, retry at increasing intervals of 2s → 4s → 6s, up to 10 times; the count resets after a successful reconnection, ensuring the next disconnection also has a full set of retry opportunities. The entire process is silent and transparent to the user.
30-second Ping Keep-Alive: Start a Timer after a successful connection to send a sendPing to the server every 30 seconds, preventing intermediate network equipment from cutting the connection due to inactivity.

After the modifications were completed, the developer executed bash build_app.sh and pushed to GitHub:

Claude Code: Build successful, commit completed, pushed. Real-time translation should now be able to operate continuously for a long time, silently reconnecting automatically when the Session expires without the user noticing an interruption.

Phase 2: Feature Interview — Five Questions to Lock Down Two Priority Development Directions

With stability resolved, the developer began thinking about how the App could go further:

User: Help me research carefully and give me three new feature recommendations.

After carefully reading the code, Claude Code first proposed a directional question instead of directly giving a list:

Which category of these three new feature directions do you prefer?

A. Utility / UX — Making daily use more convenient (transcript export, hotkeys, meeting notes)

B. Translation Quality — More accurate and natural (multi-language detection, speaker identification)

C. System Integration — Connecting with other tools (Notion, Zoom overlay)

User: A

Three UX features were immediately produced: Floating Subtitle Window, Automatic Meeting Transcript Export, and Global Hotkeys. The developer's response was direct:

User: I want both 1 and 2.

Next was a brief requirement interview, where Claude Code asked only one most critical question at a time:

How many lines should the floating window display? → Double lines (small text for original + large text for translation)
Background style? → Vibrancy effect (frosted glass)
Export method? → Automatically save to the desktop, no dialog box

After five questions, the design direction was completely clear. Claude Code proposed a complete design plan and wrote the specification document. After the developer confirmed "no problem," it entered the implementation phase.

Phase 3: Plan-Driven Development — Subagent Closed-Loop Delivery, Review Catches Critical Bugs

With clear specifications, Claude Code entered its most proficient work mode: Write a plan first, then use multiple independent Subagents to execute tasks, with each Task immediately reviewed by a Reviewer Subagent upon completion.

The entire process was divided into three Tasks; the two most critical ones are recorded below:

Task 1: Automatic Meeting Transcript Export

The Implementer Subagent quickly completed three things: removed the original 25-line history limit, added the exportTranscript() method, and automatically saved the complete bilingual comparison record in Markdown format to the Desktop when translation stopped.

However, the Reviewer Subagent immediately raised a flag:

Critical Issue found: status = "Stopped" in stop() is executed immediately after exportTranscript(), instantly overwriting the save path message. The user will only ever see "Stopped" and will never know where the file was saved.

This was a logic bug just one line away, which would have been very easy to overlook without a Reviewer. The Fix Subagent then intervened, changing exportTranscript() to return a Bool: when export is successful, stop() no longer overwrites the status; "Stopped" is only displayed when there are no records to export. After the modification, the Reviewer confirmed again, and all passed.

Task 2: Floating Subtitle Window

Added FloatingSubtitleWindow.swift, with a core structure of three layers:

NSPanel (level = .floating): Always on top, does not steal focus (.nonactivatingPanel), and can be displayed across full-screen Apps.
NSVisualEffectView (material = .hudWindow): Native macOS vibrancy effect.
NSHostingView embedding SwiftUI's FloatingSubtitleView: Directly bound to TranslatorViewModel.currentLine, updating in real-time.

At the same time, ownership of TranslatorViewModel was moved up from ContentView to TranslatorApp, allowing the main window and the floating window to share the same data source, avoiding data duplication or synchronization issues. The window position is saved to UserDefaults after dragging and automatically restored after a restart.

The Task Reviewer checked all 11 specifications one by one; all passed without any need for correction.

The entire "Implementation → Review → Correction → Re-review" closed loop was completed automatically by subagents. The developer only needed to confirm that the final bash build_app.sh passed cleanly:

Claude Code: Build successful, commit completed, pushed.

Phase 4: App Brand Upgrade — Real-time Generation of Professional Icons with Python

With features complete, the developer turned their attention to the appearance:

User: The app icon doesn't look good, help me generate a professional one.

Claude Code first confirmed that Pillow (Python image library) was in the environment, then directly wrote a complete Icon generation script with the following design description:

Background: Deep sea blue gradient (#0D1B4E → #1565C0), standard macOS 22% rounded corners, echoing the macOS Design Language.
Core Pattern: Two overlapping speech bubbles. The upper bubble (semi-transparent white) contains "A" representing the original English audio, and the lower bubble (pure white) contains "中" representing the translated output. They are connected by a bidirectional arrow in the center, making the "real-time translation" product positioning clear at a glance.
Fonts: Avenir Next for English and Apple SD Gothic Neo for Chinese, both of which are built-in macOS fonts, requiring no external resources.

The script output 10 sizes at once (16px → 1024px), converted them into an .icns file using the system's iconutil command, and automatically updated build_app.sh to copy the icon into the App Bundle, adding the CFBundleIconFile declaration to Info.plist. The entire process did not require opening Xcode or using any image design tools.

Phase 5: Code Quality Refinement — Clearing All Compilation Warnings

When the developer executed bash build_app.sh for acceptance, they noticed a few lines of yellow warnings in the output:

User: There are some warnings when running build_app.sh, help me check them.

Claude Code carefully executed the Build and categorized three types of warnings, treating them accordingly:

Warning Type	Root Cause	Fix
`onChange(of:perform:)` deprecated × 2	`swiftc` did not specify a deployment target, defaulting to the latest SDK rules	Added `-target arm64-apple-macos13.0` to `build_app.sh` to let the compiler know we are targeting macOS 13, where the old API is the correct choice
`SCRunningApplication` non-Sendable × 2	Types in the ScreenCaptureKit framework are not marked `Sendable`	Changed `import ScreenCaptureKit` to `@preconcurrency import ScreenCaptureKit`
`TranslatorViewModel` non-Sendable captured	ViewModel was captured in a `@Sendable` closure	Added `@MainActor` to `TranslatorViewModel` (modern standard practice for SwiftUI ViewModels) and added `@preconcurrency` to delegate conformance to suppress derived warnings

The final Build output was as clean as new, without any Warnings:

🛠 Starting compilation of Swift files (target: arm64-apple-macos13.0)...
🎨 Copying App Icon...
📝 Generating Info.plist...
✅ Packaging complete!

All modifications were committed and pushed to GitHub together.

Phase 6: Real-World Pitfalls — The ScreenCaptureKit Permission Labyrinth

The App's functionality seemed complete until the developer actually turned it on to start using it:

User: Is it a permission issue? I open the app and it keeps failing to scan the "Target App" list. Help me check the relevant code.

The App list was always empty. "Screen Recording" in System Settings was indeed checked. This is a typical "permissions are granted, but it just doesn't work" dead-end problem.

First Cut: Handling Silent Failures

After reading AudioCaptureManager.swift, Claude Code immediately spotted the problem: when the fetchShareableApps() call to SCShareableContent.current failed, it only printed to the console. The UI showed an empty list without any prompt. The developer had no idea what was happening.

The first wave of modifications did three things:

Added NSScreenCaptureUsageDescription to Info.plist: Without this key, the macOS authorization dialog will never pop up.
Added an ad-hoc signing step: codesign --sign - --force --deep — ScreenCaptureKit requires the App to have a code identity to appear in the "System Settings > Screen Recording" list.
Surfaced errors to the UI: Changed fetchShareableApps() to return (apps, errorMessage?). Any failure would be displayed in the App's status bar, allowing the developer to see immediately what happened.

Build completed, tested again—still the same error message.

Second Cut: Overly Aggressive Error Classification Logic

Looking closely at the error judgment code:

let isPermissionDenied = nsError.domain == "..." && nsError.code == 1
    || error.localizedDescription.lowercased().contains("permission")
    || error.localizedDescription.lowercased().contains("denied")

The contains("permission") line was too aggressive. As long as any word containing "permission" appeared in the error description, it would be incorrectly judged as "Permission Denied," displaying "Please go to System Settings to enable authorization." In reality, it could be a completely different error.

Claude Code corrected the judgment logic—only the exact ScreenCaptureKit userDeclined error code (-3801) is treated as a permission issue. All other errors display the actual domain, code, and description for easier diagnosis:

let isPermissionDenied = nsError.code == -3801
let message = isPermissionDenied
    ? "Screen recording permission required: Please go to System Settings to enable authorization"
    : "Unable to get App list (code \(nsError.code)): \(error.localizedDescription)"

Third Cut: Finding the Root Cause — TCC Identity Mismatch

After correcting the error classification, Claude Code ran the App and captured the logs, finding that the status bar displayed a new message with a code number, not -3801. This confirmed: The problem wasn't that the user hadn't given permission, but that macOS didn't recognize the App at all.

The root cause:

Every time build_app.sh is executed and re-signed ad-hoc, the hash of the binary changes, and the macOS TCC database treats it as a completely new App. The old screen recording authorization was given to the previous binary; the new binary did not inherit it. System Settings shows it as checked, but that's authorization for the old identity, which is invalid for the new binary.

The solution is to reset TCC to let macOS re-trigger the authorization dialog:

tccutil reset ScreenCapture com.poc.MeetingTranslator

After execution, reopening the App and clicking "↻" caused macOS to immediately pop up the "MeetingTranslator wants to record the contents of this screen" dialog. Clicking "Allow" instantly listed all running applications in the App list.

Permanent Countermeasure: Writing the Reset into the Build Process

The ad-hoc signing issue persists during development—every rebuild requires re-authorization. Claude Code added tccutil reset directly as the last step of build_app.sh:

tccutil reset ScreenCapture com.poc.MeetingTranslator 2>/dev/null && \
  echo "✅ Reset complete. The system will ask for authorization again after opening the App" || true

From then on, after every bash build_app.sh, simply open MeetingTranslator.app, and the system will ask for authorization again. The entire development cycle will never again get stuck in the "permissions are granted but it doesn't work" loop.

Conclusion: The True Value of the "Plan → Subagent Implementation → AI Review" Closed Loop

This collaboration with Claude Code made me feel a completely different way of working compared to the first AGY CLI development:

Proactively asking questions instead of just starting: Faced with "give me three new feature recommendations," Claude Code's first step was to ask for a direction; faced with the "floating window," it confirmed style and details one by one. This rhythm of "align first, then implement" is much more reliable than directly guessing requirements.
The plan is a moat for quality: Writing specification documents and implementation plans before implementation gives each Subagent clear boundaries and acceptance criteria. This seemingly "redundant" step directly discovered a state-overwriting bug in the Task 1 review that human developers could easily overlook.
AI Reviewing AI is a different layer of protection: The Reviewer Subagent and Implementer Subagent are started completely independently; they share no context. Because of this, the Reviewer can discover the Implementer's blind spots from a fresh perspective—this is the extra protection brought by "AI double-checking," not a replacement for human Code Review, but a completely new level of quality.
Tool boundaries are functional boundaries: App Icon generation, Warning fixes, Git commit/push—Claude Code moves freely throughout the development environment. The developer doesn't need to switch tools; all actions are completed within the dialogue.
Real-world use is the best test: The ScreenCaptureKit issue in Phase 6 never appeared in any build tests until the developer actually turned it on to use it. This kind of "silent failure + system-level identity mismatch" problem only surfaces in real-world scenarios. Claude Code's diagnostic method—from correcting error classification to letting the UI display real error codes, to finding the TCC root cause—is a typical "narrowing the hypothesis range and letting the problem speak" debugging approach.

If the first article was about "from zero to one," this record is about "from usable to good, and then to standing firm in real-world scenarios." Two types of AI Agents, two collaboration styles, together completed a full Native macOS App covering low-level audio, WebSocket connections, SwiftUI UI, Python image generation, and system permission diagnosis. See you next time!

[Gemini API in Action] Building MemeFinder: A Native Mac Menu Bar Widget for Finding Memes via Text Using Gemini Vision & Semantic Embeddings

Evan Lin — Mon, 22 Jun 2026 00:41:17 +0000

The Origin: Mid-Conversation, Where on Earth Is That Meme?

Anyone who chats a lot has a folder full of memes on their phone and computer, but the moment you actually need one — the conversation is rolling, you want to drop a "thanks but no thanks" or an "I'm trash" reaction — you can't find it. The filename is IMG_4821.jpg, the photo library has no categories, and search is a non-starter.

I first came across a wonderful open-source project, ShiQu1218/MemeTalk. It builds a local meme semantic-search system with Python + Streamlit + SQLite: it scans your local meme folder, indexes images with OCR and vector embeddings, then does multi-route retrieval. Feature-complete, but research-oriented and requires opening a browser to run Streamlit.

What I wanted was something closer to an "everyday handy tool":

A native Mac app, one search box. I type what I'm looking for and the relevant meme pops up. Click it and it's copied straight to the clipboard.

So MemeFinder was born. This post records its journey from zero to "menu-bar resident + global hotkey," and several representative pitfalls along the way.

System Design and Architecture

The core concept is simple: point at a local meme folder → have Gemini build an index for each image → type to do a semantic search → click to copy.

I made three key technical decisions:

Native SwiftUI app, not Electron. Copying images to the clipboard, global hotkeys, menu-bar residency — with AppKit these are all first-class citizens.
Gemini does two things: the vision model gemini-3-flash-preview reads the text in each image and generates a Traditional Chinese description plus emotion tags; gemini-embedding-2 turns that semantics into a 768-dimensional vector.
Hybrid semantic-vector + keyword search. Pure keyword recall for Chinese is too poor; only semantic vectors achieve "type a related description and find the image."

System Architecture Flow

The project is deliberately split into two Swift Package targets:

Target	Type	Contents
`MemeFinder`	library	Logic, models, services, ViewModels (all unit-tested)
`MemeFinderApp`	executable	SwiftUI views + menu-bar shell (thin layer, depends on the library)

This split isn't decorative — it directly determines whether the tests can run smoothly, as "Pitfall #2" will explain.

Core Implementation

1. Auto-tagging memes with the Gemini vision model

During indexing, each image is sent to the vision model with a request to output only JSON: the text in the image, a Traditional Chinese description, tags, and emotion. responseMimeType is set to application/json to keep the output format stable:

public static func annotateRequest(apiKey: String, imageData: Data, mimeType: String) -> URLRequest {
    let prompt = """
    你是迷因圖標註助手。請閱讀這張圖，輸出 JSON，欄位：
    ocr_text(圖中所有文字), description(用繁體中文描述畫面與梗),
    tags(3-8 個繁體中文關鍵字陣列), emotion(單一情緒詞)。只輸出 JSON。
    """
    let body: [String: Any] = [
        "contents": [[
            "parts": [
                ["text": prompt],
                ["inline_data": ["mime_type": mimeType, "data": imageData.base64EncodedString()]]
            ]
        ]],
        "generationConfig": ["responseMimeType": "application/json"]
    ]
    // ... set URL, x-goog-api-key header, POST body
}

2. Hybrid semantic + keyword ranking

After the query string is embedded into a vector, we compute cosine similarity for every image, then add weight for keywords that hit the OCR text and tags, and merge-sort:

public func search(queryEmbedding: [Float], queryText: String,
                   in images: [IndexedImage], limit: Int) -> [SearchResult] {
    let tokens = queryText.lowercased().split(whereSeparator: { $0.isWhitespace }).map(String.init)
    let results: [SearchResult] = images.compactMap { image in
        let cos = cosineSimilarity(queryEmbedding, image.embedding)
        let haystack = (image.ocrText + " " + image.tags.joined(separator: " ")).lowercased()
        let matches = tokens.filter { !$0.isEmpty && haystack.contains($0) }.count
        let boost = 0.1 * Float(min(matches, 3))   // keyword boost capped at 0.3
        let score = cos + boost
        return score > 0 ? SearchResult(image: image, score: score) : nil
    }
    return Array(results.sorted { $0.score > $1.score }.prefix(limit))
}

The whole search engine is a pure function, with Gemini hidden behind a protocol, so this logic can be fully unit-tested offline without hitting the real API.

Major Pitfalls and Solutions

The real time sink in this project was never the happy path — it was the pitfalls below.

Pitfall #1: The mysterious `GeminiError error 0` — indexing and search both fail

App packaged, key set, folder chosen, hit search — and nothing shows below, just GeminiError error 0.

Rather than guessing, I hit the embedding endpoint once with a real key and printed the response:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
  -H "x-goog-api-key: $KEY" \
  -d '{"content":{"parts":[{"text":"貓"}]},"output_dimensionality":768}'

The evidence was unmistakable:

{ "embedding": { "values": [ -0.0063, -0.0200, ... ] } }

The problem: my parser was reading the plural embeddings[0].values (that's the batchEmbedContents batch-endpoint format), but the single embedContent call returns the singular embedding.values. So every embed call failed — indexing each image failed, embedding the query string failed — all throwing badResponse (shown in the UI as GeminiError error 0).

[Solution]
Fix the parser to read the singular embedding.values, keeping the plural format as a fallback; I also hardened the annotation parser (a thinking model sometimes returns a textless "thought" part first, so skip to the first part that actually has text):

public static func embedding(fromEmbedContent data: Data) throws -> [Float] {
    guard let root = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
        throw GeminiError.badResponse("cannot parse embedContent payload")
    }
    // A single embedContent returns {"embedding":{"values":[...]}}
    if let embedding = root["embedding"] as? [String: Any],
       let values = embedding["values"] as? [Double] {
        return values.map(Float.init)
    }
    // batchEmbedContents is {"embeddings":[{"values":[...]}]} — tolerate it too
    if let embeddings = root["embeddings"] as? [[String: Any]],
       let values = embeddings.first?["values"] as? [Double] {
        return values.map(Float.init)
    }
    throw GeminiError.badResponse("cannot parse embedContent payload")
}

Lesson: trust the actual API response over your memory or secondhand docs. A single line of curl saved countless guesses.

Pitfall #2: SwiftPM's `main` entry-point conflict and the SwiftUICore linking error

I initially made the whole project a single executableTarget with the tests depending on it directly. The result: tests failed to link no matter what. An executable target needs a main entry point, but that entry point only exists at the UI step's @main App; and casually adding a placeholder main.swift then conflicts with @main (Swift doesn't allow two entry points in one target). Worse, SwiftUI in an executable target spews SwiftUICore.tbd ... not an allowed client linker warnings.

[Root cause analysis and solution]
This is actually an architecture problem, not a compilation problem. The right approach is to split the project into two layers:

MemeFinder (library target): all logic, models, services, ViewModels — the tests depend only on this layer, it has no entry point, and it links cleanly as a library. ViewModels import Combine (not SwiftUI) to get ObservableObject.
MemeFinderApp (executable target): only SwiftUI views and @main, with import MemeFinder to use the public types above.

After the split, the library and tests don't touch SwiftUI at all, the linker warnings disappear, and the @main conflict no longer exists. "What the tests need to depend on" often forces out clean module boundaries.

Pitfall #3: Parallel indexing's rate limit and "I want to stop indexing halfway"

The first version indexed one image at a time, serially calling Gemini (annotate then embed). For hundreds of images this was painfully slow. So I switched to bounded parallelism with withTaskGroup (at most 4 at once), which brought three new problems:

The Gemini free tier has a rate limit — too much concurrency triggers 429.
The user wants to cancel halfway through a large folder.
Parallel completion order is chaotic, but the results need stable sorting.

[Solution]
Handle the three problems separately, all converging in the same buildIndex:

429 backoff retry: retry only GeminiError.rateLimited with exponential backoff (max 3 attempts); other errors are recorded without retry.
Cooperative cancellation: honor Task.isCancelled; on cancel, stop scheduling new work and keep the completed portion. Even the backoff Task.sleep lets CancellationError propagate normally instead of swallowing it and firing one more API call.
Stable sorting: collect results into a [path: image] dictionary, then reassemble the output in the order of the pre-sorted file list, decoupled from completion order.

// Seed maxConcurrent tasks first, then refill one per completion — strictly cap concurrency
for _ in 0..<maxConcurrent { if !scheduleNext() { break } }
while let res = await group.next() {
    if let img = res.image { resultsByPath[res.path] = img }
    if let err = res.error { errors.append(err) }
    done += 1
    progress(done, total)
    _ = scheduleNext()
}

Incidentally, the HTTP status code was also extracted into a pure function mapResponse(data:statusCode:): 429 → rateLimited, other non-2xx → httpError(code), 2xx → return the data. The retry logic then has a basis, and this part is easy to test too.

Pitfall #4: Evolving from a "windowed app" into "menu-bar resident + global hotkey"

Whether a tool is pleasant to use comes down to "how many steps to summon it." I wanted to hit ⌃⌘M mid-conversation to bring up the search popover, with the app tucked into the menu bar, not occupying the Dock. This step hit two classic macOS pitfalls:

(a) Does a global hotkey need accessibility permission? No. Use Carbon's RegisterEventHotKey to register a fixed hotkey, which doesn't need Accessibility permission (unlike monitoring the whole keyboard). But under Swift 6 strict concurrency, the C event callback has to dispatch through a static id → instance registry, requiring nonisolated(unsafe) and relying on the invariant that "Carbon events are delivered on the main thread" for safety. If ⌃⌘M is already taken, RegisterEventHotKey returns failure — in which case we silently degrade, log a line, and the menu-bar icon still works.

(b) The timing race in the menu-bar right-click menu. The initial approach was "set statusItem.menu → performClick → immediately clear menu," but clearing synchronously fights AppKit's menu-tracking loop, and the menu flashes and disappears.

[Solution]
Pop the menu up directly, fully bypassing the assign-and-clear of statusItem.menu:

@objc private func statusButtonClicked() {
    guard let event = NSApp.currentEvent else { togglePopover(); return }
    if event.type == .rightMouseUp {
        // Pop up directly; don't assign then synchronously clear statusItem.menu
        // (it races AppKit's menu-tracking loop)
        if let button = statusItem?.button {
            NSMenu.popUpContextMenu(makeMenu(), with: event, for: button)
        }
    } else {
        togglePopover()
    }
}

Finally, adding LSUIElement = true to the Info.plist produced by build-app.sh makes the Dock icon disappear, and MemeFinder officially becomes a pure menu-bar tool.

Pitfall #5: The settings form is blank — one symptom, three layers of cause

After moving to the menu-bar version, a user reported "the settings window is completely blank." This seemingly simple bug, peeled apart, actually had three layers, each highly representative.

Layer 1: a Form collapses to zero height inside a hand-rolled NSWindow.
Originally the settings screen lived in SwiftUI's native Settings { } scene, which sizes it sensibly. After the refactor it was hosted in a hand-rolled NSWindow(contentViewController: NSHostingController(rootView: SettingsView())), and SettingsView ended with only .frame(width: 460) — width only, no height. NSWindow(contentViewController:) sizes the window from the content's natural size, but a SwiftUI Form is vertically greedy; with no constraint, its natural height resolves to nearly 0, so the window opens as a 460-wide, near-zero-height blank strip. The fix is just to add a height:

.padding(20)
// When hosted in a hand-rolled NSWindow (not a SwiftUI Settings scene), a Form
// with no height constraint collapses to ~0, turning the window into a blank strip.
.frame(width: 460, height: 320)

Layer 2: ⌘, and the menu-bar "Settings…" go down two different paths.
After adding the height, the user said "still blank." On follow-up I found out he was summoning settings with ⌘,, while the menu-bar right-click "Settings…" went down a different path. The reason: ⌘, in a SwiftUI app triggers the Settings { } scene, and to dodge a state-sharing problem during the refactor, I had set that to Settings { EmptyView() }:

// During the refactor, the Settings scene was left empty to avoid state-sharing
// — so ⌘, opens a blank window
var body: some Scene {
    Settings { EmptyView() }
}

In other words, settings had two entry points pointing at different things: ⌘, pointed at the empty scene, the menu-bar "Settings…" pointed at the real window. The fix unifies the two paths — let the Settings scene host the real SettingsView (so ⌘, works directly), and make the menu-bar "Settings…" open the same native settings window too:

Settings {
    SettingsView(vm: appDelegate.settings, indexing: appDelegate.indexing,
                 onReindex: { appDelegate.reindexNow() },
                 onCancel: { appDelegate.cancelReindex() })
}

// The menu-bar "Settings…" now opens the same Settings scene
@objc private func openSettings() {
    NSApp.activate(ignoringOtherApps: true)
    NSApp.sendAction(Selector(("showSettingsWindow:")), to: nil, from: nil)
}

This also leverages the fact that a SwiftUI App body is @MainActor-isolated — so reading the @MainActor appDelegate.settings directly from the body is legal, with no extra bridging needed.

Layer 3 (the most insidious): open doesn't reload a menu-bar app at all.
The biggest time-waster in the process was that after recompiling, I'd ask the user to open MemeFinder.app, yet he kept seeing the old behavior. Because MemeFinder is an LSUIElement menu-bar-resident app — when an instance is already running, open only wakes the existing old process instead of relaunching with the new binary. So we were actually testing the same old build the whole time. The correct dev loop is to truly kill it first, then run from source:

killall MemeFinderApp 2>/dev/null; swift run MemeFinderApp

This layer reminds me: when debugging, first confirm "what you're testing really is the version you changed" — otherwise all your reasoning is built on faulty observations.

On the "Development Process" Itself

This project was driven almost entirely by an AI agent workflow of spec → plan → subagent task-by-task implementation → two-stage review: each feature started with a design spec, was broken into independently testable small tasks, every task wrote a failing test first (TDD) before implementing, and after completion an independent review agent checked spec compliance and code quality, followed by one final whole-branch review.

Several of the pitfalls — GeminiError error 0, the library/executable split, swallowing CancellationError during backoff, the menu timing race — were in fact caught half the time during the review stage, not written correctly on the first pass. This echoes that old principle: having tests as armor, and someone (or an agent) seriously reading the diff, matters far more than writing fast. The final project maintains 47 unit tests and a zero-warning release build.

Results and Benefits

Type to find, click to paste: type a Chinese description in the menu-bar popover, semantic search instantly lists relevant memes, click one to copy it to the clipboard and paste straight into LINE / Slack / Messages.
Privacy-friendly, searchable offline: images and the index live locally (~/Library/Application Support/MemeFinder/index.json); only the "build the index" step calls Gemini.
A truly handy tool: ⌃⌘M is available anytime, menu-bar resident, no Dock footprint; incremental indexing only processes new/changed images, and indexing can show progress and be canceled.
A clean, maintainable architecture: a two-layer library/executable design, Gemini hidden behind a protocol, pure logic fully covered by tests.

All the development code for this project is open-sourced on GitHub: kkdai/meme-finder-app. Feel free to clone it, point it at your own meme-collection folder, and experience the joy of "type to find your meme"!

[Gemini API] Gemini Batch API and Webhook API practical usage on restaurant survey

Evan Lin — Mon, 15 Jun 2026 04:09:16 +0000

A Powerful Tool for Asynchronous Processing: Gemini Batch API & Webhooks

When developing LLM-based applications, we often need to handle a large number of data analysis tasks—for example, analyzing reviews from dozens of restaurants at once, classifying a large volume of articles, or batch generating translations. If we use traditional synchronous APIs (real-time calls), we would not only face severe Rate Limit blockages but also fail due to network connection timeouts and extremely high computing costs.

To overcome this limitation, Google has launched the Gemini Batch API and Webhook API:

Gemini Batch API: Allows developers to package a large number of requests into a JSONL file and upload them all at once. Gemini performs asynchronous scheduled computations in the background, without consuming your daily real-time API quotas (Rate Limits), and its computing cost is usually half that of real-time APIs, making it a perfect choice for non-urgent big data processing.
Webhook API: Traditional Batch tasks require us to constantly write polling logic locally to check the status. With Webhooks, when Gemini completes a Batch computation, it actively sends an HTTP POST callback to your specified URL, instantly notifying you that the task is complete, making the system architecture more elegant and energy-efficient.

This article will document how we integrated these two powerful APIs into our LINE Bot Restaurant Analysis Assistant to achieve one-click deep review and signature dish big data analysis for specific restaurants on mobile devices.

System Design and Optimized Architecture

Originally, the restaurant analysis function worked by having the Bot list nearby restaurants when a user sent their location, and then providing a generic "Deep Review Analysis (Batch)" button. Clicking it would send all nearby restaurants for analysis at once. However, this led to a poor UX: analyzing all restaurants took too long, and users often only wanted to delve into one specific restaurant they were interested in.

Therefore, we optimized the function into dynamic Quick Reply buttons:

The user sends their location, and the Bot searches for nearby restaurants via Google Maps Grounding.
After the client receives a plain text list of restaurants, the Bot automatically uses Gemini to extract the top 3 highest-rated restaurant names.
Three customized Quick Reply buttons are generated (e.g., 🍴 Analyze Din Tai Fung).
After the user clicks a specific restaurant button, the Bot immediately replies "Processing" to avoid LINE timeouts, and submits the Batch task for that single restaurant in the background. Once Gemini completes the computation, it proactively pushes a dedicated big data report.

System Architecture Flow

graph TD
    A[User Sends Location] -->|Location Message| B[Google Maps Grounding Search]
    B -->|Plain Text Restaurant List| C[Gemini-2.5-flash Extracts Top 3 Restaurants]
    C -->|Dynamically Generates Quick Reply| D[LINE Bot Replies with 3 Customized Analysis Buttons]
    D -->|User Clicks Specific Analysis| E[FastAPI Background Task]
    E -->|Immediate Reply ACK| F[LINE Chat Message]
    E -->|Package JSONL and Upload| G[Gemini Batch API Submission]
    G -->|Computation Complete Webhook/Polling Callback| H[Proactively Pushes Deep Report to User]

Core Implementation

1. Precisely Extracting Restaurant Names from Grounding Text using Gemini

In tools/maps_tool.py, the map search returns a plain text string rich in formatting and descriptions. We use Gemini-2.5-flash's structured output concept to precisely extract restaurant names in JSON format:

        # Extract top three restaurant names for Quick Reply
        names = []
        if place_type == "restaurant":
            try:
                extract_prompt = f"Please extract all restaurant names from the following text and return them in a JSON array format (e.g., [\"Restaurant A\", \"Restaurant B\"]). Please output the JSON array directly, without any markdown tags (like ```
{% endraw %}
json) or explanatory text.\n\n{result}"
                extract_res = client.models.generate_content(
                    model="gemini-2.5-flash",
                    contents=extract_prompt
                )
                extract_text = extract_res.text.strip() if extract_res.text else ""

                try:
                    names = json.loads(extract_text)
                except Exception:
                    import re
                    array_match = re.search(r"\[(.*?)\]", extract_text, re.DOTALL)
                    if array_match:
                        import ast
                        names = ast.literal_eval(f"[{array_match.group(1)}]")

                names = [str(n).strip() for n in names if n]
                logger.info(f"Extracted restaurant names for Quick Reply: {names}")
            except Exception as e_extract:
                logger.error(f"Failed to extract restaurant names: {e_extract}")
{% raw %}

2. Dynamically Generating LINE Quick Reply Buttons

In main.py, after obtaining the restaurant list, we dynamically generate QuickReplyButton. We need to pay special attention to LINE API's length limit for button label:


python
        quick_reply = None
        if place_type == "restaurant" and result.get("status") == "success":
            restaurant_names = result.get("restaurant_names", [])
            if restaurant_names:
                buttons = []
                for name in restaurant_names[:3]:
                    clean_label = name
                    # LINE label limit is 20 characters
                    if len(clean_label) > 10:
                        clean_label = clean_label[:9] + "…"
                    buttons.append(
                        QuickReplyButton(
                            action=PostbackAction(
                                label=f"🍴 分析 {clean_label}",
                                data=json.dumps({
                                    "action": "specific_foodie_deep_analysis",
                                    "restaurant_name": name
                                }),
                                display_text=f"🔍 進行「{name}」深度評論與招牌菜色分析"
                            )
                        )
                    )
                quick_reply = QuickReply(items=buttons)

Major Pitfalls and Solutions

During the process of connecting this dynamic Quick Reply to the Batch API, we encountered several critical UX and API limitation issues:

Pitfall One: LINE 20-character Limit Causing API Sending Errors

Initially, when implementing, we directly used the full restaurant name in the button's Label, for example: 🍴 Analyze Love Hot Pot Ultimate Hot Pot. As a result, the LINE API immediately returned a 400 error, and the message could not be sent at all:


plaintext
LineBotApiError: status_code=400, error_message=The property 'label' must be less than 20 characters.

[Cause Analysis and Solution] LINE's official label limit for Quick Reply is extremely strict; including emojis and spaces, it can have a maximum of 20 characters. To address this, we added a character count check and dynamic truncation mechanism in our code:

First, the original restaurant name (clean_label) is truncated: if its length exceeds 10 characters, it is forcibly cut to the first 9 characters and appended with "…" (occupying 10 characters).
Adding the prefix 🍴 Analyze (a total of 5 characters), the maximum total length becomes 15 characters, safely staying within the 20-character limit, thus eliminating the error!

Pitfall Two: Batch API Asynchronous Delay and LINE Webhook's "Three-Second Timeout Survival Battle"

When a user clicks the "Analyze Restaurant" button, the Bot must first call Google Search Grounding to collect online reviews for that restaurant, then package the JSONL file and upload it to Gemini to submit the Batch task. This entire sequence usually takes 3 to 8 seconds. However, the LINE Webhook server requires the Bot to return an HTTP 200 OK response within 3 seconds, otherwise it will be deemed a connection failure and re-send the request, leading to severe server congestion.

[Cause Analysis and Solution] We completely asynchronous the processing architecture:

Fast Response: When the Bot intercepts a specific_foodie_deep_analysis Postback action, it does not execute the analysis directly within the Request flow. Instead, it immediately calls LINE's reply_message to respond to the user: 🔍 Received! Performing deep analysis for you... This will take about 1-2 minutes..., and then instantly returns HTTP 200 to end that Webhook request.
Background Task Dispatch: Use Python asyncio.create_task to dispatch heavy network search, upload, and submission tasks to FastAPI's background Worker for execution.
Big Data Push: When the background Polling listener or Gemini Webhook receives a task completion notification, it then uses LINE's push_message to proactively send the analysis report to the specific user.

Pitfall Three: Gemini Batch API's Queuing and Pending Status

During testing, users sometimes got confused, "Why hasn't there been a reply after three minutes? Is the Bot down?". After checking the system logs, we found that our JSONL file had been successfully uploaded, but the task status on the Gemini server side was stuck at JobState.JOB_STATE_PENDING.

[Solution] This is a characteristic of the Batch API; tasks need to be queued, waiting for Google's server resources. We adopted two major optimizations:

Minimize Workload: Reduce the number of restaurants for batch analysis to 1, shrinking the number of request lines in the JSONL to the extreme, to speed up Gemini's scheduling and processing.
UX Optimization and Deduplication Mechanism: When a user clicks to analyze, we first check if that user already has a Batch Job running. If so, we reply: ⏳ Your deep analysis task is currently running, please wait patiently, preventing users from submitting multiple duplicate Batch Jobs due to anxious repeated clicks, which would consume unnecessary resources.

Results and Benefits

This optimization of Quick Reply and Gemini Batch API for the LINE Bot Restaurant Assistant has achieved excellent practical value:

Highly Customized Mobile Experience: After locating, users don't need to type; they can directly click on a restaurant of interest with one tap to precisely get a summary of its signature dishes and review pain points.
Robust Backend Architecture: By leveraging asynchronous background tasks and LINE's character limit safety valve, the risks of Webhook timeouts and LINE API errors have been completely resolved.
Cost Advantage for Big Data Processing: Through the Batch API's half-price advantage and Webhook's proactive callback, while ensuring user experience, it also saves significant computing resources and API costs for the server.

Through this architecture, the LINE Bot truly achieves a low-latency, highly stable big data deep analysis experience on mobile!

All development code for this project has been open-sourced on GitHub: kkdai/linebot-helper-python. Everyone is welcome to deploy and personally test this one-click analysis function, which we believe can bring a higher level of intelligent experience to your LINE Bot projects!

DEV Community: Evan Lin

[Claude Code in Practice] Rethinking Terminal Workflows: From zsh Autocomplete to Search and Diff Toolchains

Pain Point: Starting Over with Every Command

Solution 1: Let Zsh Remember What You've Typed

Solution 2: Add Color to Read the Terminal Faster

Solution 3: Replace ls, cat, and cd with Smarter Versions

Solution 4: Make File Searching and Comparison Faster for Claude Code

Solution 5: Add Common Read-Only Commands to Claude Code's Permission Whitelist

Three Easily Overlooked Pitfalls

Pitfall 1: compinit complaining about "insecure directories"

Pitfall 2: zsh-syntax-highlighting must be the last line

Pitfall 3: ast-grep was intentionally left out of the whitelist

Summary and Benefits

[Dev Log][Python] Create short videos from photos and clips with Gemini 3.7 Flash: ReelCraft

Preface:

TL;DR

Omni Flash is not what I thought it was

Bypassing limitations: Per-file understanding, then text aggregation

Using edl.yaml as a human confirmation point

The difference after switching to Gemini 3.7 Flash

Background music: Lyria 3 uses a different API

ffmpeg will silently fail your edits

Subtitles: Two issues only visible after burning them in

Other pitfalls

Conclusion

Reference Links:

[Learning Notes][Golang] Authorization Challenges in the AI Agent Era: What is ID-JAG and Why I Re-implemented It in Go

Preface:

TL;DR

What is ID-JAG? Why is it needed?

From OAuth2 and PKCE to new problems in the Agent era

Two RFC cornerstones: Token Exchange and JWT Bearer

The complete ID-JAG token exchange flow

Downscoping permissions at every hop: How the Principle of Least Privilege is implemented

Why re-implement this MCP Server in Go?

Hands-on: Installation, Execution, and Testing

Conclusion

Related Articles:

[Dev Log][Node.js] Feedly Classic is gone, so I built my own FeedFlow (Part 1)

Introduction:

TL;DR

Why build an RSS reader from scratch

The significance of LINE Login in this project

The RSS reader development process: From standalone MVP to multi-user cloud sync

Why Gemini was chosen as the translation engine and the pitfalls encountered

Frontend interface: Four view modes and mobile-first design

Current progress and the direction of the next post

Conclusion

Reference Links:

[Book Sharing] Tsaisang’s Tales of the Strange: Japanese Mythology, Ghost Stories, and Sometimes Taiwan

Recommended links to buy the book:

Foreword:

Synopsis

Summary of the Three Core Sections

I. Japanese Mythology: A First Family More Dramatic Than a Soap Opera

II. Yokai and Urban Legends: Collective Anxiety of Modern People

III. And Sometimes Taiwan: The Mysterious Connection Between Taiwanese and Japanese Gods and Ghosts

Reflections

[Book Sharing] Taiwan's AI Future: Analyzing Trends, Local Landscape, Corporate Strategy, and Personal Development

Recommended links to buy the book:

Preface:

Outline

Overview of the Book's Four Core Frameworks

I. Latest AI Trends: The 1:99 "Superhuman" Challenge

II. Taiwan's Situation: From "Island Involution" to the "Age of Discovery"

III. Corporate Layout: Hardware-Software Integration, Letting "Old-ventures + New-ventures" Dance Together

IV. Personal Development: Refuse "Brain Outsourcing," Be a High-Level "Questioner"

Personal Thoughts

[GCP in Action] LINE Business Card Bot Evolution: Dual-Side Recognition and Merging with Gemini

Pain Point: One Chinese Business Card is Actually Two Business Cards

Solution: First Ask, "Is there a back side?"

Core: Let Gemini See Two Images at Once and Merge Them

Two Easily Overlooked Pitfalls

Pitfall 1: Timing of Duplicate Checks

Pitfall 2: Don't Clear All States Indiscriminately

Incidental Resource Cleanup: Don't Let Back-Side Images Linger in Memory

Summary and Benefits

[Digital Certificate Wallet] Advanced: Building "Visitor-Endorsed Issuance" – A Full-Chain DID Application as Both Verifier and

Premise:

Scenario: Employee Access Control + Visitor Endorsement and Issuance

Solution 3: Replace `ls`, `cat`, and `cd` with Smarter Versions

Pitfall 1: `compinit` complaining about "insecure directories"

Pitfall 2: `zsh-syntax-highlighting` must be the last line

Pitfall 3: `ast-grep` was intentionally left out of the whitelist

Scenario A: Already contains `GenerateContentConfig`

Pitfall #1: The mysterious `GeminiError error 0` — indexing and search both fail

Pitfall #2: SwiftPM's `main` entry-point conflict and the SwiftUICore linking error