Green Material Search Toolkit

Green Material Search & Advisory Toolkit

Overview

A self-contained local web tool + Python backend for browsing Taiwan's TABC green-material certification database, grouping selected materials into a named "Set", and getting the AI to draft a material-selection advisory document (建材選用說明書) for that Set — CNS testing basis, qualified items, and suggested application location per material. Sets can be saved, edited, and exported/imported as project files so they carry over between projects.

This skill is intentionally scoped to search + Set management + advisory Q&A only. It does not perform any BIM-software model write (no Revit, Archicad, or other native-format injection). If a future skill needs to push a Set's materials into a specific BIM tool's model, that belongs in a separate, BIM-tool-specific skill — do not extend this one to do that.

Data Reality — Read Before Answering Questions About a Material

assets/tabc_master_database.json has two tiers of trustworthiness per record:

• Real, scraped from the TABC list page: licno, title, company, period (validity dates, ROC calendar), category, subCategory, img.
• Inferred from a keyword-rule template, not scraped per-record from TABC's detail page: cnsSpec, testItems, qualifiedItems, productSpecFull, specList, specs, keywords. These are plausible placeholder values grouped by subCategory/title keywords, not authoritative lab data for that specific product.

Always disclose this distinction when the advisory document or a direct answer states a specific CNS standard or test value. Never present the inferred fields as officially verified numbers — tell the user to confirm against the TABC record's detail_url (CaseDataInfo.aspx) or the manufacturer's certificate before using the figures in a formal submission.

Trigger Confirmation Rule

Mentioning "綠建材" (or a related term — 綠建材標章, TABC 綠建材, 健康/高性能/再生/生態綠建材, etc.) in conversation is enough to make this skill relevant, but it is not enough to launch anything on its own. Before running python scripts/local_server.py (which opens a local port and a browser tab), ask the user whether they want to open the search tool. Only skip the confirmation when the user's message is already an explicit request to open it (e.g. "open the green material search tool", "打開綠建材檢索工具"). This mirrors the equivalent policy in the origin project's domain/green-material-keyword-search.md (.claude/skills/GMweb/SKILL.md there) — a passing mention should never silently trigger a running process.

Setup — Obtaining the Data Assets (First Run Only)

assets/tabc_master_database.json, assets/green-material-toolkit.html, and assets/exported_material_sets.json are not included in this skill's files. They contain TABC's (財團法人臺灣建築中心) certification data and/or a specific user's project output, neither of which belongs under this repository's CC BY-SA 4.0 license — see .gitignore in this directory. The interface itself (assets/green-material-toolkit.template.html) is shipped with the skill, empty of TABC data (const tabcDatabase = [];), so this step is self-contained — no manual download from anywhere.

Before first use:

1. Run python scripts/update_tabc_database.py once with no existing assets/tabc_master_database.json; the script bootstraps a fresh database from a live TABC crawl (starts from an empty list, everything found is added — takes longer than a normal incremental update since nothing is cached yet), then fills that data into assets/green-material-toolkit.template.html and writes the result to assets/green-material-toolkit.html. Both outputs are gitignored, regenerated locally on every run.
2. assets/exported_material_sets.json — not needed up front; it's created automatically the first time a Set is saved.

After this, normal use (steps 1–4 below) works entirely offline except for step 4's optional refresh crawl.

Execution Steps

1. Open the tool (only after the user confirms — see Trigger Confirmation Rule above)

python scripts/local_server.py

Starts a local server, bound to 127.0.0.1 only, at http://localhost:8888 serving assets/green-material-toolkit.html, and opens it in the browser. A plain file:// open of the HTML also works for browsing/searching, but the "Set" save/export/import buttons need this server running (they call POST /api/save-sets / GET /api/get-sets).

If port 8888 is already in use by another process (e.g. a different local tool on the same machine), tell the user to free it or check what's using it before starting a second server.

Sets are the user's project output, not skill content, so they are written outside this repository by default — to ~/.green-material-toolkit/exported_material_sets.json. Set the GREEN_MATERIAL_OUTPUT_DIR environment variable before running either local_server.py or generate_material_advisory.py to point both at a specific project folder instead (both must use the same value to see the same Set data).

2. Search and build a Set

The page lets the user filter by keyword/category, select materials, and save a named "Set" (a group of licnos with an optional purpose/use note). This is entirely client-side + the local API — no AI involvement needed for this step.

3. Ask the AI to draft a material-selection advisory

Once the user has a Set and clicks "🤖 回傳至 AGENT" (or asks in chat, e.g. "請為材料 Set 【某某 Set】撰寫建材選用說明書"), run:

python -c "
import sys
sys.path.insert(0, 'scripts')
import generate_material_advisory as g
advisory = g.generate_material_advisory('<set_name>', ['<licno1>', '<licno2>', ...], '<original request text>')
g.write_back_to_set_manager('<set_name>', advisory)
"

Run this from the green-material-search-toolkit/ directory (or adjust the scripts path). This:

• Matches each licno against assets/tabc_master_database.json (exact match first, then suffix-tolerant fallback for (續)/(增)/(變) certificates — see _normalize_licno in the script). Never truncate a matched licno's suffix in what you report to the user.
• Writes Material_Advisory_Report.md under the Set output directory ($GREEN_MATERIAL_OUTPUT_DIR, default ~/.green-material-toolkit/) — a full Markdown advisory document (material list with category, CNS basis, qualified items, test data, and a suggested application location per material — general building-assembly language, e.g. "牆面或天花板塗裝面材", not any specific software's category system).
• Updates the Set's entry in the same directory's exported_material_sets.json (purpose, plannedActions — now holding suggested-usage lines, not any software-specific execution steps — and planStatus: "已請 Agent 撰寫說明書").

Then report a concise summary to the user (do not paste the full report):

• Set name and matched material count (flag if fewer matched than requested — a licno wasn't found even after suffix-tolerant matching).
• For each matched material: licno (full, with suffix if any), title, category/subCategory, suggested application location.
• Remind the user that cnsSpec/testItems/qualifiedItems are inferred values per the Data Reality note above.
• Point them at the generated Material_Advisory_Report.md (in the Set output directory) for the full document.