Skip to content

feat: add tsfile skills - #907

Open
Alchuang22-dev wants to merge 6 commits into
apache:developfrom
Alchuang22-dev:feat/skills
Open

feat: add tsfile skills#907
Alchuang22-dev wants to merge 6 commits into
apache:developfrom
Alchuang22-dev:feat/skills

Conversation

@Alchuang22-dev

Copy link
Copy Markdown
Contributor

No description provided.

@Alchuang22-dev

Copy link
Copy Markdown
Contributor Author

Summary

This PR reorganizes the TsFile skills under agentlib/tsfile/skills and makes them more concise, version-aware, and usable both with and without a TsFile source checkout.

It separates SDK-oriented guidance from command-line workflows, reduces duplication with the official documentation, and introduces deterministic scripts for version resolution and template validation.

Changes

Split SDK and CLI responsibilities

  • Keep tsfile focused on Java, Python, C++, and C SDK usage, data models, schema design, compatibility, and performance.
  • Move shell-oriented inspection, preview, export, sampling, and CSV/TSV conversion guidance into the sibling tsfile-cli skill.
  • Remove duplicated tsfile-cli content from the main tsfile skill.

Introduce progressive offline references

  • Reduce the size of SKILL.md by moving Quick Start content, general concepts, and performance guidance into focused references.
  • Retain concise offline knowledge for environments without network access.
  • Avoid maintaining a full copy of the official TsFile documentation.
  • Load only the language or topic reference required by the current task.

Define source authority and official documentation routing

  • Add source-policy.md to define source precedence, version selection, conflict handling, and offline/online behavior.
  • Add docs-map.yaml as a registry of official documentation, release, download, and repository URLs.
  • Treat mutable latest documentation URLs as navigation aliases rather than release identifiers.
  • Prefer source code, tests, and maintained examples from the same commit for checkout-specific API behavior.

Add version resolution with degraded standalone semantics

  • Add scripts/resolve-version.sh to obtain Maven/Java, C++, Python, and Git metadata from a TsFile checkout.
  • Remove hard-coded TsFile versions from SKILL.md and output templates.
  • Support two execution modes:
    • checkout: resolve version metadata from the source repository.
    • standalone: return a successful degraded result with version fields marked as unavailable.
  • Keep an explicitly invalid --root path as an error.
  • Report the offline reference scope and validation date separately from the resolved source version.

Review and validate output templates

  • Review all files under assets/ against upstream examples.
  • Retain the existing assets because they are standalone user-output templates rather than direct copies of upstream examples.
  • Prefer maintained examples from the same commit when a TsFile checkout is available.
  • Use bundled assets only when a standalone starter project is requested.
  • Remove the default TsFile dependency version from the Java Maven template.
  • Require the target Java version through -Dtsfile.version=<version>.

Add dual-mode asset validation

Add scripts/validate-assets.sh with separate behavior for both supported environments:

  • With TsFile source:
    • Compile the Java template against the checkout artifact.
    • Compile the C++ template against checkout headers.
    • Run the Python write/read template against the local binding.
  • With a standalone skill:
    • Validate the Maven XML and Python syntax without dependencies.
    • Optionally validate against explicitly supplied dependencies using:
      • --tsfile-version
      • --java-jar
      • --cpp-include
      • --python-runtime

The validation is also available through:

scripts/build_tsfile.sh validate-assets

@Alchuang22-dev
Alchuang22-dev marked this pull request as ready for review August 17, 2026 12:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant