@shimatoworks/stw-agent

CLI for the Shimatoworks agent read API. It fetches a project's registry entries (Notion / Drive / Slack / repo) and the Slack discussion attached to them, so an agent or a person can get the background of a project in one command instead of assembling curl calls by hand. It also serves the admin console manual (stw-agent help) and the current commerce figures — stock, lots, orders, purchase orders, partners and consignment stock and sales reports (stw-agent commerce) — and accommodation bookings and room availability (stw-agent stays). It has no dependencies and needs a read token issued by Shimatoworks; without one it does nothing. The API contract, the permission model and the error semantics live in the stw-manage repository, not here.

インストール

npm i -g @shimatoworks/stw-agent

stw-agent コマンドが PATH に入る。Node 20 以上が要る。

token

読み取り token（STW_AGENT_TOKEN）が要る。発行と配布は たまが行う。 自分で作らない。無ければ人に頼む。

set -a && source ~/.config/tamai/stw-agent.env && set +a

~/.config/tamai/stw-agent.env に置いてあれば CLI が自動で読むので、 上の source は毎回は要らない。接続先を変えるときだけ STW_API_BASE を指定する。

token は CLI のどの出力にも出ない（stdout / stderr / エラー文のいずれにも）。

token は人ごと（代理 token）。サーバ側でその人の現在の権限が上限になり、 参加していない private や、役割が変わった後の読み取りは返らない（403 / 404）。

• 他人の token を使わない。 読めないときに別の人の token や共用 token へ自動で切り替えない
• 共用の bot（複数人へ結果を返すもの）に個人の token を置かない
• 退職・停止・端末の紛失では、たまが token を失効させる（CLI 側に代理先を指定する口は無い）

使い方

stw-agent --help

動詞は doctor / help / commerce skus / commerce orders / commerce purchase-orders / commerce partners / commerce stock-counts / commerce stock-count-history / commerce stock-txns / commerce inquiries / commerce consignment-balances / commerce consignment-reports / commerce consignment-returns / commerce consignment-missing-reports / projects list / projects context / projects resources / projects next / slack channels / slack messages / slack next / stays list / stays show / stays day / stays availability の 25。 正確なオプションは常に --help を見る（ここに写経しない）。 サブコマンドの後ろに --help（-h）を付けても同じ使い方が出る。

管理画面の操作手順書（help）

stw-agent help                       # トピックの一覧
stw-agent help wholesale-orders      # トピックの本文
stw-agent help --q 発注単位           # 語句検索
stw-agent help --error 'ロット残数不足のため出荷できません (lot=L-1, 残=3, 必要=10)'

token に help:read が要る（doctor の「token の権限」に help:read=あり と出る）。 手順書の正本は stw-manage の docs/guides/操作手順/ で、API が deploy した版を返す。 管理画面のヘルプ（/help）は 2026-09-29 に削除した。

--error は画面に出たエラー文を数字入りのまま貼ればよい。サーバが文言の安定した先頭部分で トピックへ当て、出力の先頭に「判定:」を出す。

• 判定: 答えてよい（answer） … 1 つのトピックに当たった。そのトピックの手順で答える
• 判定: 確認へ回す（confirm） … 当たらない・複数に当たる・当たったトピックが改修中。 推測で操作を指示せず、たまへの確認に回す

一覧やトピックに 状態: 改修中… が付いたものも同じで、手順を断定しない。 AI は案内と読み取りだけを行い、画面の操作は本人が行う。

使い方（--help）は 0.4.0 から stw-agent --help で出す（stw-agent help は手順書になった）。

物販のいまの数字（commerce）

stw-agent commerce skus --q '夏空 お箸'          # SKU・価格・在庫・ロットごとの残数
stw-agent commerce orders --status pending       # 卸注文・明細・金額・連絡先・出荷できない理由
stw-agent commerce purchase-orders               # 発注・明細・金額・入荷の状況
stw-agent commerce partners --role wholesale_customer   # 取引先・連絡先・卸の申込の状態
stw-agent commerce skus --status active --stock-level low   # 最低在庫を割った SKU（発注の候補）
stw-agent commerce orders --partner-id <uuid> --terms consignment   # 取引先・取引の形・種別で絞る
stw-agent commerce stock-counts                  # 進行中の棚卸と差分
stw-agent commerce stock-count-history           # 確定済みの棚卸（1 棚卸 1 行。差分の全部は --json）
stw-agent commerce stock-txns --q HASHI-SKY --from 2026-09-01 --to 2026-09-30   # 取引履歴（1 取引 1 行）
stw-agent commerce inquiries                     # 卸の申込（承認待ち）と希望の商品と数
stw-agent commerce consignment-balances          # 委託先 × SKU の預け数（出荷・売上・返品・減耗の内訳）
stw-agent commerce consignment-balances --as-of 2026-10-31   # その日の終わりの時点の預け数（決算など）
stw-agent commerce consignment-reports --period 2026-10      # 委託の売上報告（1 報告 1 行。明細は --json）
stw-agent commerce consignment-returns --from 2026-10-01     # 委託の返品（1 返品 1 行）
stw-agent commerce consignment-missing-reports               # 前月分の報告が来ていない委託先

token に commerce:read が要る（doctor の「token の権限」に commerce:read=あり と出る）。 --q は空白で区切った語を全部含むものを返す（商品名とバリエーションにまたがってよい）。 金額は円で、価格の税込を除いて税抜。

• ロット管理ありの SKU は、ロットごとの残数（入荷日つき）と「在庫とロット合計の差」を出す。 差が 0 でなければ、ロットに紐づかない記録（棚卸の調整など）が在庫を動かしている

• ロット管理なしの SKU は在庫だけを出す

• 受注中の卸注文には「出荷: できる見込み／できない見込み — 理由」を出す。理由は出荷登録が実際に拒否する 3 つだけ: ロット不足（同じ SKU の明細を合算し、1 明細 1 ロットで割り当てられるかまで見る）・在庫不足・ 卸先が申込中や停止中。出荷は止めないが確かめてほしいこと（出荷前なのに freee の請求書が結びついている など）は 「注意:」行に分ける。ロットの割り当てを確かめ切れなかったときは「出荷: 判定保留」と出す（できるとは言わない）。 見込みであって、最後は出荷登録の画面で確かめる

• SKU には在庫の段階の印（[在庫少]・[在庫切れ]・[在庫マイナス]）を付ける。--stock-level <negative|out|low|ok> で絞れる （low は最低在庫があり 1 以上それ未満。--status active と合わせると管理画面のダッシュボードの在庫アラートと同じ）

• commerce orders は --partner-id <uuid>・--terms <purchase|consignment>・--kind <delivery|consignment_settlement> でも絞れる

• 取引履歴（stock-txns）は在庫取引を新しい順に 1 取引 1 行（時刻は JST・種類・増減・商品・ロット・相手の取引先・メモの先頭）。 --q（商品名・SKU コード・バリエーション・ロット番号・メモ）・--txn-type・--sku-id・--from/--to（発生日・JST・両端を含む）で絞る

• 卸の申込（inquiries）は承認待ち（既定）か --status rejected を 1 申込 1 行（連絡先・業務形態・希望の商品の先頭 3 品）。 希望の商品の全部・住所・メモは --json

• 確定済みの棚卸（stock-count-history）は 1 棚卸 1 行（確定日・対象の SKU の数・差分の先頭 3 SKU）。進行中は stock-counts

• メモ・名前・商品名などの入力は改行を空白に畳み、1 行に先頭だけを出す。明細は先頭 3 件と「他 N」。全文は --json

• 日時（申込・棚卸・下書きの作成など）は JST の日付で出す。返品日・受領日など日付だけの値はそのまま

• どれも頁で返る（--limit は最大 100）。続きがあると最後に「次:」行が出るので、そのまま実行する （絞り込みや --limit を変えると cursor は 400 になる）

• 価格・仕入価格・卸価格・金額・取引先の連絡先まで返る（社内のメンバー向け）。 公開発注 URL の token は返らない（発行済みか・いつ発行したかだけ）

• 委託販売（0.6.0）

  • consignment-balances は委託先 × SKU の預け数（委託先に置いてある数）と、出荷・売上・返品・減耗の内訳。 --as-of <YYYY-MM-DD> でその日の終わり（翌日の JST 0:00 より前）の時点の数（省略は今日）。 省いたときの「次:」行には最初の頁の日付を --as-of で付けるので、日付をまたいで続きを取っても同じ時点の数になる。 売上は先方の報告を受け取った日で数えるので、まだ受け取っていない月の分は預け数に残る
  • consignment-reports は委託の売上報告を 1 報告 1 行（対象の月・委託先・状態・受領日・売れた数と金額・減耗・ 委託精算の卸取引と freee の請求書の状態）で出す。商品ごとの明細と委託精算の id は --json で見る。 --period <YYYY-MM>・--status <draft|confirmed|voided> で絞る 預け数には仕入価格と金額（預け数 × 仕入価格）も出す。見出しの下に絞り込み全体の預け在庫の金額・仕入価格が 未設定の行の数（金額の合計に入らない）・委託に切り替えていない卸取引を出す（どの頁でも同じ値）
  • consignment-returns は委託の返品を 1 返品 1 行（返品日・委託先・理由・戻った数と商品・取り消した明細の数・メモの先頭）。 --from/--to は返品日。ロットと取消の理由は --json
  • consignment-missing-reports は報告が来ていない委託先（その月の末日に預け数があり、報告が確定していない）を 1 委託先 1 行（末日の預け数・未入力か入力中か）。見出しに対象の月・締め日からの日数・管理画面に知らせが出ているか。 --period <YYYY-MM>（省略は前月。「次:」行には最初の頁の月を --period で付ける）
  • consignment-balances・consignment-reports・consignment-returns は --partner-id <uuid>（commerce partners の id）で委託先を絞れる
  • commerce orders は委託の卸取引に [委託]・[委託精算] の印を付け、委託の出荷の「出荷済」を「預け中」、 委託精算の「出荷済」を「請求待ち」と出す。commerce partners は委託の取引先に「取引の形: 委託」を出す

AI は数字を読んで答えるだけで、在庫や注文を変える操作は本人が画面で行う。

宿泊の予約と空き（stays）

stw-agent stays list                             # 今日から 30 日の予約（最初の行に期間）
stw-agent stays list --check-in 2026-10-01       # その日に着く予約（--check-out は発つ予約）
stw-agent stays list --from 2026-09-01 --to 2026-09-30 --facility konyamachi   # 泊まる期間が重なる予約
stw-agent stays list --outstanding               # 未収がある予約（--pending-request は未処理の依頼あり）
stw-agent stays show <id>                        # 予約 1 件と決済・入出金・取消・返金・依頼
stw-agent stays day                              # 今日の着・発・連泊と施設ごとの件数（stays day 2026-10-01）
stw-agent stays availability --facility konyamachi --from 2026-10-01 --to 2026-10-07   # 部屋 × 夜の空き

token に accommodation:read が要る（doctor の「token の権限」に accommodation:read=あり と出る）。

• 宿泊客は表示名（「山田 様」）だけを出す。 区切りの無い氏名は「山… 様」、匿名化の済んだ予約は「（匿名化済み）」
• フルネーム・かな・連絡先は、token に accommodation:pii があるときの --json にだけ入る。 pii の token でも既定の 1 行には出さない（端末のログや transcript に積み上げない）
• --q（氏名・かな・メール・電話での検索）と --notes（申込の目的・メッセージ・メモなどの自由記述。--json で見る）は accommodation:pii が要る。無い token では 403 で、「日付・施設で絞るか、たまに確認する」と出る
• 1 行は 09/30→10/02 2泊 2名 紺屋町 101 山田 様 確定 当日払いの予定（未収 24,000 円） id <id>。 支払いは 支払い済み・未収・当日払いの予定・OTA 集金・返金の途中・金額なし で読む（当日払いでチェックインの前は未払いではない）。 未処理の依頼・チェックイン済み・保管済みには印が付く
• stays list は期間を省くと今日から 30 日（最大 186 日）。--from/--to は泊まる期間の重なり、 --check-in/--check-out はその日に着く・発つ予約（一緒には使えない）。--status はカンマ区切り、 --archived で保管済みも含める
• stays day [<日>] は施設ごとの件数（着・発の「確定」はダッシュボードの本日のチェックイン・チェックアウトと同じ数え方）と、 着・発・連泊の予約を 1 件 1 行
• stays availability は日付 × 部屋の表（○ 空き・× 予約・休 休館・止 部屋の NG。最大 31 泊）と、全室が塞がっている夜
• stays show は決済・入出金・依頼などを先頭 5 件まで出す（残りは --json）。決済と返金の外部の ID・URL は API が返さない
• stays list・stays day は頁で返る（--limit は最大 100）。「次:」行の期間と日付は cursor に入っているので、 翌日に実行しても最初の頁と同じ範囲を読む

AI は予約を読んで答えるだけで、予約や鍵を変える操作は本人が画面で行う。

Drive の資料を探す（projects resources）

stw-agent projects resources yoshino

案件に紐付いた Drive 入口フォルダ配下の索引（名前・MIME・更新日・親子・ ショートカット先・「資料候補」の印）を返す。入口の URL だけでは 「直下に 1 フォルダしかなく、主要資料はさらに下」という形に辿り着けないため。

本文は返らない。 fileId を gog へ渡して読む（guide §4）。

読み方で気をつけること:

• 索引は「SA が読めるメタデータを、台帳で指定された受け手へ公開する」もので、 本人が Google で読める全ファイルではない。入口ごとに admin が有効化したものだけが出る
• indexes[].complete が false ならまだ全部ではない（reason に理由がある）。 終了コード 0 でも起こるので、「これで全部」と書かない
• 続きは出力の「次:」行をそのまま実行する（projects next '<query>' --slug <slug>）。
• 並びは文書 → その他 → 画像（同じ段では浅い順）。頁の確認が 15 秒で切れると 「確認の予算で切れました」と出て、確認済みの先頭だけが返る（verification.complete=false）。 残りは「次:」の query を変えずに続ける（cursor と limit は組で、変えると 400）。 件数を絞るなら --cursor なしで先頭から --limit を小さくして取り直す。 cursor は不透明な値で、手で組み立てると 400 になる
• 409 は索引が作り直された合図。--cursor を外して取り直す
• 503 drive_unavailable は一時的な確認失敗。古い一覧を成功として返さないので、 空ではなくエラーになる

まず doctor

stw-agent doctor

token・読み取り API への到達・token の権限・周辺ツール（ntn / gog / hub / gh / bun）の有無と認証を一度に見る。各項目は OK / 未導入 / 未認証 / 権限なし / 到達不可 / 不明 のどれかで、 要対応には直し方が 1 行付く。--json あり。

不明 は失敗ではない（確かめられなかっただけ）。終了コードは 要対応があるときだけ 1 になるので、stw-agent doctor && 次の作業 と繋げられる。 たとえば hub は認証を検証する手立てが無いので、設定があっても 不明 のままになる。

秘密は出さない。token は値も長さも先頭数文字も出さない（出すのは env から読んだのか 設定ファイルから読んだのかだけ）。接続先は origin だけを出し、STW_API_BASE に 資格情報（user:password@）が入っていれば要求を投げる前に断る。

既定の出力は 1 行要約で、メッセージの本文は先頭だけを出す。 会社の内部のやり取りが端末のログや transcript へ機械的に積み上がるのを避けるため。 全文が要るときだけ --json を付ける。

契約と権限

読める範囲（案件との紐付き・visibility・チャンネルの種別）はサーバ側の SQL が決める。 期間や検索語の妥当性もサーバが判定する。CLI は要求を組み立てて表示するだけである。

• 契約・権限・エラーの意味・読むときの約束: stw-manage の docs/guides/案件コンテキストの集め方.md
• なぜこの形なのか・過去の判断: stw-manage の docs/records/235-agent-read-api.md

変更履歴

• 0.7.0 — stw-agent stays list|show|day|availability（宿泊の予約と空き。記録 285 の API）を追加。 既定の 1 行は宿泊客の表示名だけで、フルネーム・連絡先は accommodation:pii の token の --json だけ。 --outstanding・--pending-request・--archived・--notes は値を取らないフラグ。 doctor の「token の権限」に accommodation:read・accommodation:pii を出す（集計には入れない）

• 0.6.0 — stw-agent commerce consignment-balances|consignment-reports（委託販売の預け数と売上報告）を追加。 --partner-id・--as-of・--period・--status と、ほかの commerce と同じ --limit・--cursor・「次:」行。 commerce orders に委託の印と「預け中」「請求待ち」、commerce partners に取引の形を出す。 あわせて commerce stock-txns（取引履歴）・consignment-returns（委託の返品）・consignment-missing-reports （報告が来ていない委託先）・inquiries（卸の申込）・stock-count-history（確定済みの棚卸）を追加し、 commerce skus --stock-level・commerce orders --partner-id|--terms|--kind、預け数の仕入価格・金額・ 切り替えていない卸取引を足した（記録 282 の API）。新しいコマンドの既定の出力は 1 件 1 行

• 0.5.0 — stw-agent commerce skus|orders|purchase-orders|partners|stock-counts（物販のいまの数字）を追加。 doctor の「token の権限」に commerce:read を出す（集計には入れない）。5 つとも --limit と --cursor で頁を辿る

• 0.4.0 — stw-agent help（管理画面の操作手順書。一覧・トピック・--q・--error）を追加。 stw-agent help は使い方ではなく手順書を出すようになった（使い方は --help）。 サブコマンドの後ろの --help / -h を受け付ける（0.3.0 までは「未対応のオプション」）。 doctor の「token の権限」に help:read を出す（集計には入れない）。 403 の案内に「代理先が現在利用できない」場合を含め、別の token への 切替を勧めないようにした。503 service_unavailable（権限の確認が一時的にできない）の案内を追加

• 0.3.0 — projects resources（Drive 入口配下の索引）と projects next を追加。 資料候補をページ内で先に出し、complete=false のときは理由を必ず添える。 409 / 503 drive_unavailable に「取り直す」「一時的」の案内を付けた。 本文は返さない（fileId を gog へ渡す）

• 0.2.1 — doctor の bun の案内を「入れたあと PATH に ~/.bun/bin を足す」まで書くようにした。 publish は GitHub Actions（npm trusted publishing・タグ push）へ移した （repo が private なので provenance は付かない）

• 0.2.0 — stw-agent doctor を追加（token・API 到達・権限・周辺ツールの一括確認）。 STW_API_BASE に資格情報が入っていれば要求前に拒否し、表示は origin だけにする。 slack channels の既定出力に、サーバが返すようになれば保存範囲（最古〜最新・件数）と 到達状態（上限到達／さかのぼり中／読み切り／未走査）・最後の失敗が出る

• 0.1.1 — npm i -g した stw-agent（symlink）が無出力で終了する不具合を修正。 実体パスでの直接実行は 0.1.0 でも動いていた

• 0.1.0 — 最初の公開

ライセンス

UNLICENSED（社内利用）。npm の scope は公開だが、利用許諾を与えるものではない。