• #Hermes Desktop
  • #tool-call-malformed
  • #テスト
  • #トラブルシュート
  • #Nous Research
開発misc-dev

開発ツール周りの調べ物とトラブル対処

今日は新機能を作るというより、ツール周りの調べ物とトラブル対処で時間を使った。3つある。Hermes Desktopを調べて記事にした件、積み残しを片付けようとしたらClaude Codeのツール呼び出しが壊れて連発で落ちた件、そして fail しているテストを「直すもの」と「放っておくもの」に切り分けて別ドキュメントに残した件。あとで自分が読み返して状況を思い出せるように、流れを書いておく。

1. Hermes Desktop を調べて Windows 向け記事にした

朝イチで「Hermes Desktop について調べて公開記事を作ってほしい。インストールはWindowsで」と投げた。Nous Research が出している AI エージェント Hermes Agent のデスクトップ版だ。

最初のセッションは出だしから API Error: 500 を連発して、/clear を打っても 500 が返ってきて何も進まなかった。サーバー側の一時障害だったらしく、しばらく置いてからやり直した。

調べて分かったのは、Hermes Desktop が単なるチャットアプリではないということ。CLI・TUI・Web Dashboard・Desktop App が、同じ設定・APIキー・セッション・スキル・メモリを共有する設計になっている。だから Desktop App は「Hermes の入口」にも「既存の Hermes 環境を GUI でも触れる管理画面」にもなる。モデル提供元も OpenAI・OpenRouter・Nous Portal・Anthropic・ローカルの OpenAI 互換エンドポイントまで選べる。

Windows での入れ方は、公式サイトの Windows 版インストーラーを使うのが一番素直だった。

  • 公式ページ: https://hermes-agent.nousresearch.com/desktop
  • 実体: Hermes-Setup.exe（hermes-assets.nousresearch.com 配下）

初回起動時に Electron シェルが Hermes Agent 本体のランタイムを用意して、Windows では %LOCALAPPDATA%\hermes 配下に実行環境を作る。CLI 版と Desktop 版が同じデータを使うので、あとから hermes コマンドでも同じ環境を操作できる。このあたりを hermes-desktop-windows-install.md として記事化した。日記としてはここまで覚えておけば十分で、詳しい手順は記事の方を見ればいい。

2. 「昨日の積み残し」を片付けようとしたら malformed が連発した

別のセッションで「君の積み残しがあったはずだから調べて」と頼んだ。昨日付の memo を見させたら、/beat-monitoring/scatter ページの表示バグが「翌日2026-06-03着手予定」として残っていた。今日が 6/3 なので、まさに今日やる宿題だ。「全部一気に片付けて」と続けた。

ここでハマった。memo と Google タスクを並行確認させようとした最初の一手から、

Your tool call was malformed and could not be parsed. Please retry.

が返ってきて、リトライさせても

The model's tool call could not be parsed (retry also failed).

で止まった。「昨日の積み残しは何ですか」と質問を素直に言い直すと積み残しの中身はちゃんと返ってくるのに、「関連ファイルを並列で読んで現状を把握します」と複数ファイルを一気に掴ませようとした瞬間にまた malformed で落ちる。「続けて」と促してもまた malformed。同じ場所で何度も転んだ。

最初はセッションが何か巨大なものを抱えて重くなっているのかと疑ったが、それは筋が悪い。前に調べたとおり、malformed の真因はファイルサイズではなく、ツール呼び出しの引数の構造が壊れること。実際、落ちた直前にやらせていたのは「複数ファイルを並列で読む」「memo とタスクを同時に見る」みたいに、一回の呼び出しに対象を詰め込む動きだった。引数を盛ると壊れる、という今までの整理どおりだ。

対処はシンプルにすることに尽きた。並列で一気に、をやめて、一個ずつ単純に呼ばせる。質問も「全部把握してから片付けて」ではなく「このファイルだけ読んで」と粒度を小さくする。複雑なことを一手に詰めるのをやめたら malformed は止まって、積み残しの調査自体は前に進んだ。

教訓として今回腹落ちしたのは、malformed が出たらまずファイルサイズを疑うのではなく、直前のツール呼び出しの引数を疑うこと。そして連発したら深追いせず、シンプルな呼び出しで仕切り直す。人間側は「引数を盛りすぎるな」と方針を決める係で、実行を細かく刻ませるのが効く。

3. fail しているテストを切り分けて別ドキュメントに残した

別の銘柄追加作業（こっちは別記事に分ける）の途中で pnpm test:run を全体実行したら、複数のテストが赤くなっていた。中身を見ると、自分がいま触っている領域とは無関係の既存 fail が混ざっている。全部いっぺんに直そうとすると作業が膨らむので、「連結精算表のところはまだ放っておいていい。それ以外は調査してほしいから、別ドキュメントに残して別セッションでやりたい」と切り分けを指示した。修正はさせず、調査とドキュメント化だけ。

切り分けると、fail は性格の違う3系統だった。

テスト状態扱い
url-migration.test.ts❌ 2件要対応
og-meta-tags.test.ts❌ 3件要対応
check-sequential-ids.test.ts✅ 現在 pass監視のみ
consolidation-engine*.test.ts❌対象外（放置でよい）

コンテンツのタイトル欠落（url-migration） は、getAllMarkdownFiles() が隠しディレクトリまで再帰走査して、frontmatter を持たない 1 ファイルを「公開記事」と誤認していたのが原因。content/.claude/codex-review/ に残った codex のレビュー生ログだった。記事ではない迷子のログが1本混ざっただけで「公開記事1158本のうち1本に title が無い」と落ちていた。content にツールの吐き出しを置かない、というのが本筋の対応になる。

新規記事の OG タグ（og-meta-tags） は、3つの Vue ページ（blog/analemma-claude.vue・investment-income-matrix.vue・sp500-backtest.vue）が useHead({...}) は持つのに useSeoMeta({...}) を持っていなくて「useSeoMeta 自体が存在しない」で落ちていた。dev 限定ページではなく公開ページなので、除外ではなく OG タグを付けるのが筋。beat-monitoring/scatter.vue がそのまま手本になる。

連番 ID（check-sequential-ids） は調査した時点では pass に戻っていた。セッション序盤では落ちていたのに、その間に複数ファイルが並行編集されていて解消したらしい。再発したらテストの console 出力に重複/欠番 ID が出るので、それを見て該当ファイルを直せばいい。今は監視だけ。

連結精算表（consolidation-engine 系） は今回放置でよいと決めていたので、失敗内容を記録だけして手を付けなかった。連結エンジンのロジックか事例データの整合性の問題で、別タスクとして扱う。

この4系統を memo/2026-06-03/failing-tests-investigation.md に残させた。再現コマンド・根本原因・推奨対応・次セッションの最小手順まで書いてあるので、別セッションで開いたら url-migration の迷子ログを退避 → 3ページに useSeoMeta を足す → 緑を確認、の順でそのまま進められる。

切り分けて別ドキュメントに逃がす判断は今回正解だった。赤いテストを全部その場で潰そうとすると、いま乗っている本筋の作業から気が逸れて、しかも無関係なものまで抱え込む。「いま直すもの」と「あとで別セッションでやるもの」を分けて、後者は調査結果だけ残す。違和感を拾って切り分けるのは自分の仕事、調査とドキュメント化は回させる係、という分担にした。

振り返り

3つとも「作る」より「整える・切り分ける」作業だった。

  • Hermes Desktop は、500 エラーで足止めを食らったが、調べて記事まで落とせた。CLI/TUI/Web/Desktop が設定とメモリを共有する作りが面白かった。
  • malformed は、引数を盛ると壊れるという過去の整理が今日また当たった。シンプルな呼び出しに刻めば抜けられる。
  • テスト失敗は、全部直そうとせず「直す2系統・監視1系統・放置1系統」に分けて別ドキュメントに残した。これで本筋に戻れた。

明日以降にやること

  • content/.claude/codex-review/2026-05-22_104825.md を git status で確認してから content から退避 or 削除し、url-migration の2件を緑にする
  • blog/analemma-claude.vue・investment-income-matrix.vue・sp500-backtest.vue の3ページに useSeoMeta（OGタグ6項目）を足して og-meta-tags の3件を緑にする
  • 上記2つを直したら pnpm test:run tests/url-migration.test.ts tests/og-meta-tags.test.ts で緑を確認する
  • check-sequential-ids が再発したら console 出力の重複/欠番 ID を見て該当ファイルを直す（今は監視だけ）