[#119] Add AI agent guide and refresh user entry points#123
[#119] Add AI agent guide and refresh user entry points#123SkowronskiAndrew wants to merge 4 commits into
Conversation
- New Documentation/agent-guide.md: recommended workflow for AI agents analyzing a build (analyze -> query views -> drill down), the id vs object_id distinction, one-build-per-database, TypeTree requirements, the refs table, and a worked diagnose-a-bundle example. Linked from README, unitydatatool.md, AGENTS.md, and it replaces the pre-agent-era "Using AI tools" section of analyze-examples.md. - The --help documentation URL now pins to the release tag when the version has no pre-release suffix; main carries a -dev suffix and keeps linking to the docs on main. - README Downloads section points at GitHub Releases instead of the Actions tab.
We don't need to recommend binary2text --hexfloat now that it is available in the dump command directly.
There was a problem hiding this comment.
Pull request overview
This PR improves first-contact entry points for UnityDataTool users (including AI agents) by adding an agent-oriented workflow guide, refreshing discovery links, and making --help link to version-appropriate documentation.
Changes:
- Added
Documentation/agent-guide.mdand linked it from key entry points (README, unitydatatool.md, AGENTS.md, analyze-examples.md). - Updated README downloads guidance to point to GitHub Releases instead of Actions.
- Updated
--helpoutput to link docs toblob/vX.Y.Z/...for release builds andblob/main/...for dev builds, supported by a-devInformationalVersion convention.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| UnityDataTool/UnityDataTool.csproj | Adds -dev suffix guidance for InformationalVersion to support versioned doc links. |
| UnityDataTool/Program.cs | Builds documentation URL dynamically based on InformationalVersion (release tag vs main). |
| README.md | Adds link to the new agent guide; updates Downloads section to point to Releases. |
| Documentation/unitydatatool.md | Links to the new agent guide from the docs hub table. |
| Documentation/comparing-builds.md | Updates “Special cases” text; currently contains an invalid dump --hexfloat reference. |
| Documentation/analyze-examples.md | Replaces outdated “AI tools” section with a pointer to the new agent guide. |
| Documentation/agent-guide.md | New usage-oriented workflow guide for AI agents and scripting against the analyze DB. |
| AGENTS.md | Adds a short routing note pointing tool users to the agent guide. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * This can happen if the change happens in the header of the file, or in some padding bytes. Such cases are rare because the Serialized File format is quite stable, but is a possibility if comparing files produced by different versions of Unity. | ||
| * Sometimes float or double values might appear to be identical in the decimal text representation, but there could be a difference in the actual binary representation. Specify the `--hexfloat` argument to dump to address this issue. |
| Unity archive. | ||
|
|
||
| 5. **Trace why something is in the build** with [`find-refs`](command-find-refs.md), which walks the | ||
| reference graph recorded in the database. |
There was a problem hiding this comment.
Until #121 is addressed I think we should AVOID pointing at find-refs command. I think it would actually work better for tools to query objects + refs_view themselves and then use knowledge of the different build type to tie in other views.
content_layout_loadable_objects_viewfor Content Directory buildsassetbundle_assetsfor AssetBundle builds- for Player builds the naming convention of the serialized files (documented in playerbuild-format.md) helps interpret why something is in the build.
There is a section below talking about direct find-refs access, so removing the above might make sense and then extend that section a bit.
I also think we should mark find-refs as experimental again as part of this PR.
There was a problem hiding this comment.
Done in c474b0a: find-refs is out of the core loop; a new "Tracing why content is in the build" section walks refs_view directly and lists the per-build-type endpoints (assetbundle_assets, content_layout_loadable_objects_view, Player file naming per playerbuild-format.md). find-refs is now marked experimental in the CLI help, command-find-refs.md (pointing at #121), and the README.
| ``` | ||
| sqlite3 Analysis.db "SELECT object, property_path FROM refs_view WHERE referenced_object = 140;" | ||
| ``` | ||
|
|
There was a problem hiding this comment.
This above section is good, and re-enforces my idea of steering agents away from find-refs.
There was a problem hiding this comment.
Kept and extended — it is now its own section with the per-build-type guidance, and the find-refs mention steers to the direct queries.
|
|
||
| ``` | ||
| UnityDataTool dump /path/to/bundles/my.bundle -i <object_id> --stdout | ||
| ``` |
There was a problem hiding this comment.
As it stands this is misleading example.
It is valid to " Analyze just the one file into a throwaway database:"
BUT in that case you cannot get useful information out of view_potential_duplicates.
I believe the mesh example is true, but again i think examing the entire build of AssetBundles and finding all cases of this would be more realistic analyzing a single bundle.
This section could be changed to talking about doing a full analysis.
A second example could talk about analyzing a single AssetBundle for some case where that specific bundle can be analyzed in isolation, e.g. to interpret why a bundle is larger than expected.
There was a problem hiding this comment.
Reworked in c474b0a: the main worked example now analyzes the entire build (with a note that view_potential_duplicates only makes sense there), and a second example covers analyzing one AssetBundle in isolation for why-is-this-bundle-large questions.
…perimental - agent-guide.md: drop find-refs from the core loop; new 'Tracing why content is in the build' section walks refs_view directly with the per-build-type endpoints (assetbundle_assets, ContentLayout loadables, Player file naming). Split the worked example into a full-build diagnosis (where view_potential_duplicates is meaningful) and a single-bundle-in-isolation example. - Mark find-refs experimental in the CLI help, command-find-refs.md (with a pointer to #121), and the README library list.
Summary
Fixes #119.
A review of how well AI agents can use UnityDataTool unattended found that the tool itself and the documentation hold up well, but the entry points have gaps: the
--helpdocumentation link always points at main (wrong docs for old binaries), the README still directs downloads to the Actions tab even though Releases exist, the "Using AI tools" example predates AI agents, and there is no usage-oriented starting page — experiments with a mid-tier agent showed the same few facts (the two id columns, one build per database, TypeTree requirements, therefsschema) being re-derived by trial and error.Changes
Documentation
New
Documentation/agent-guide.md: the recommended workflow for AI agents (and scripts) analyzing a build — analyze into a database, start from the views, drill down withdump/serialized-file/archive, trace withfind-refs— plus the facts that cost the most discovery time (idvsobject_id, one build per database, TypeTrees, therefstable) and a worked "diagnose a bundle" example.Linked the guide from the README documentation table,
unitydatatool.md, and a short routing note at the top ofAGENTS.md(which stays contributor-focused). The pre-agent-era "Using AI tools to help write queries" section ofanalyze-examples.mdnow points to the guide.README "Downloads" section points at the Releases page instead of the Actions tab (which no longer publishes binaries).
Marked
find-refsas experimental (CLI help,command-find-refs.mdwith a pointer to find-refs: clarify reference semantics — docs, output/error behavior, and tests #121, README) and steered the agent guide to directrefs_viewqueries with per-build-type endpoints instead, until find-refs: clarify reference semantics — docs, output/error behavior, and tests #121 is addressed.The worked example analyzes the full build (where
view_potential_duplicatesis meaningful), with a second example for analyzing a single AssetBundle in isolation.Versioned documentation link in --help
--helpoutput now pins to the matchingvX.Y.Ztag when the version is a bare release number, and links to main otherwise.InformationalVersionon main now carries a-devsuffix (2.2.0-dev). Release flow gains one small step, documented next to the property in the csproj: drop the suffix before tagging, then bump to the next-devversion.Testing
dotnet build -c Releaseclean; fullUnityDataTool.Testssuite green (286 passed).Version: 2.2.0-devand links toblob/main/...; a build with-p:InformationalVersion=9.9.9links toblob/v9.9.9/....