[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6ACEREFZKDPGZERTKCKMTCS":3,"skill-same:01M6ACEREFZKDPGZERTKCKMTCS":96},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":49,"commitSha":50,"skillDirectory":51,"forksCount":52,"repositoryHtmlUrl":53,"repositoryHomepageUrl":54,"ownerHtmlUrl":55,"ownerBlogUrl":56,"ownerDescription":6,"updatedAt":57,"install":58,"resources":71},"01M6ACEREFZKDPGZERTKCKMTCS","development",null,"Ground rules for working in the Tika codebase — git policy, Maven wrapper\u002Frepo conventions, building and testing specific modules, code and test conventions, pre-commit checks. Load at session start for any Tika development task.","apache\u002Ftika","apache","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F47359?v=4","01M6AC83E6K4FDKK7HZ8WNMQKE","The Apache Software Foundation","01M6ACEMPJD6J74AGZBFFEGEYV",4145,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fapache\u002Ftika\u002Fblob\u002Fmain\u002F.skills\u002Fdevs\u002Fdevelopment\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",[5,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"Rules","for","Test Conventions","at","load","session start","task","modules","Wrapper","session","repo","testing","pre-commit","maven","start","git","code","commit","test","policy","2026-11-10 10:12:30",false,"---\nname: development\ndescription: >\n  Ground rules for working in the Tika codebase — git policy, Maven\n  wrapper\u002Frepo conventions, building and testing specific modules, code and\n  test conventions, pre-commit checks. Load at session start for any Tika\n  development task.\n---\n\n\u003C!--\nLicensed to the Apache Software Foundation (ASF) under one or more\ncontributor license agreements.  See the NOTICE file distributed with\nthis work for additional information regarding copyright ownership.\nThe ASF licenses this file to You under the Apache License, Version 2.0\n(the \"License\"); you may not use this file except in compliance with\nthe License.  You may obtain a copy of the License at\n\n    http:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n-->\n\nLocal override: `$TIKA_SKILLS_LOCAL\u002Fdevelopment\u002FLOCAL.md` (default `~\u002F.tika-skills`),\nread after this file, wins on conflict.\n\n# Tika Development Skill\n\nGuidelines and checklist for developing against the Apache Tika codebase.\n\n## Question the direction, not just the code\n\nBefore optimizing a change — yours or a PR's — ask whether it should exist:\ndoes it belong in Tika, is the complexity proportional to the need, would\nconfig, an existing mechanism, a plugin, or documentation serve the use case\nmore cheaply?  Every merged feature is surface the project maintains for\ndecades.  Steelman the use case first and question the vehicle, not the goal;\npushback must name a concrete cost or a simpler path — never taste alone, and\nnever no for the sake of no.  \"The direction is right\" is a valid conclusion.\n\nFeature whose shape isn't known yet: spike first, cut PRs after\n(`.skills\u002Fdevs\u002Ffeature-workflow\u002FSKILL.md`).\n\n## Git Policy (default — personally overridable)\n\nNever run `git commit` or `git push` — no commits of any kind, including\nmerge commits.  If a merge is needed, use `git merge --no-commit --no-ff`\nand hand back.  Stage files and provide the suggested commit message for\nthe user to run.\n\nNever write to GitHub (PR comments, reviews, issues, labels, merges).\nRead-only `gh` is fine.\n\n**Precedence**: these are conservative defaults for *workflow* — actions on\nthe contributor's own machine and accounts.  A contributor's personal agent\nconfiguration (their own skills, CLAUDE.md\u002FAGENTS.md, settings, or a\n`LOCAL.md` overlay — see `AGENTS.md`) may override them.  Everything else in\nthis file — code and comment conventions, test discipline, hygiene,\npre-commit checks — governs what lands in the repo and is project policy:\npersonal configuration does not override it.\n\n## Session Start Checklist\n\n1. **Local Maven repo** — Default to an in-repo `.local_m2_repo`\n   (via `-Dmaven.repo.local=$(pwd)\u002F.local_m2_repo`) unless the user says\n   otherwise.  This isolates builds from the shared `~\u002F.m2\u002Frepository` and\n   avoids polluting or being affected by other projects.\n\n2. **Maven wrapper** — Use `.\u002Fmvnw`; fall back to a system Maven (3.9+)\n   only if the wrapper is absent.\n\n3. **Merge conflicts** — Check `git status` for `UU` files and resolve\n   before building.\n\n## Maven Rules\n\n- **Always include `clean`** in every `.\u002Fmvnw` invocation.\n  Stale classes in `target\u002F` cause hard-to-debug failures.\n  ```bash\n  .\u002Fmvnw clean compile -pl \u003Cmodule> ...   # not just: mvnw compile\n  .\u002Fmvnw clean test -pl \u003Cmodule> ...      # not just: mvnw test\n  .\u002Fmvnw clean install -pl \u003Cmodule> ...   # not just: mvnw install\n  ```\n\n- **Always use absolute path for local repo**:\n  ```bash\n  -Dmaven.repo.local=$(pwd)\u002F.local_m2_repo\n  ```\n\n- **Fast builds with `-Pfast`** — use the `fast` profile to skip\n  tests, checkstyle, spotless, and rat in one flag.  Prefer this over\n  individual `-D` skip flags when you want a quick build (e.g.,\n  installing for downstream consumers or eval runs):\n  ```bash\n  .\u002Fmvnw clean install -pl \u003Cmodule> -am -Pfast \\\n    -Dmaven.repo.local=$(pwd)\u002F.local_m2_repo\n  ```\n  Run **without** `-Pfast` before final commit to catch formatting\n  and style issues.  License (rat) checks run only under `-Ppedantic`\n  (or explicit `apache-rat:check`), not in default builds.\n\n  **`-Pfast` skips test *execution*** (by design): a green `-Pfast`\n  build — including `-Pfast test` — has run zero tests, and stale\n  `target\u002Fsurefire-reports\u002F*` will look current. Verify with a plain\n  (non-`-Pfast`) `test` run.\n\n- **Plugin zips resolve only after `package`** — a reactor `clean test`\n  fails on modules that depend on pipes plugin zips (`tika-server-core`,\n  `tika-app`, ...) unless the zips are already in the local repo.  Use\n  `clean install` (or `-Pfast install` first).\n\n- **Forked JVM tests** — Integration tests in `tika-pipes` fork new\n  JVMs that load classes from the local Maven repo, not from\n  `target\u002Fclasses`.  You must `.\u002Fmvnw clean install -Pfast` the\n  changed modules before running integration tests that fork.\n\n## Building Specific Modules\n\n```bash\n# Single module (with dependencies)\n.\u002Fmvnw clean compile -pl \u003Cmodule> -am \\\n  -Dmaven.repo.local=$(pwd)\u002F.local_m2_repo\n\n# Run a single test class\n.\u002Fmvnw clean test -pl \u003Cmodule> -Dtest=\u003CTestClass> \\\n  -Dmaven.repo.local=$(pwd)\u002F.local_m2_repo -Dcheckstyle.skip=true\n\n# Install for downstream consumers (tika-app, integration tests)\n.\u002Fmvnw clean install -pl \u003Cmodule> -am -Pfast \\\n  -Dmaven.repo.local=$(pwd)\u002F.local_m2_repo\n```\n\n## Building the Docs\n\n`docs\u002F` is not in the default reactor; build it from its own pom. Antora\nrenders the checked-out branch from the worktree, so uncommitted `.adoc`\nedits are included.\n\n```bash\n.\u002Fmvnw -f docs\u002Fpom.xml clean package     # site in docs\u002Ftarget\u002Fsite\u002Ftika\u002F\u003Cversion>\u002F\n```\n\n- **Broken links don't fail the build** (`--log-failure-level=fatal`). Check\n  the log for `ERROR (asciidoctor)` lines such as `target of xref not found`.\n- **Parent-directory npm leaks in.** The Antora plugin runs `npx` in `docs\u002F`,\n  which has no `package.json` or `node_modules`, so npm and Node search\n  upward. A `package.json` or `node_modules` in any parent directory, often\n  `$HOME` after an `npm install` run there, becomes the npm project root and\n  supplies packages. The plugin warns `Detected the existence of\n  $HOME\u002Fnode_modules`. `npm prefix` in `docs\u002F` should print `docs\u002F`; if it\n  prints a parent, move that install elsewhere (e.g. `npm install -g`).\n- For a release build, use `update-site-for-release`.\n\n## Common Module Paths\n\n| Module | Path |\n|--------|------|\n| tika-core | `tika-core` |\n| tika-app | `tika-app` |\n| tika-server | `tika-server\u002Ftika-server-core` |\n| tika-eval | `tika-eval\u002Ftika-eval-app` |\n| Pipes core | `tika-pipes\u002Ftika-pipes-core` |\n| Pipes API | `tika-pipes\u002Ftika-pipes-api` |\n| Async CLI | `tika-pipes\u002Ftika-async-cli` |\n\n## Code Conventions\n\n- ASF License 2.0 header on all Java files\n- Spotless formatter runs during build — don't fight it\n- Tests use `@TempDir Path tmp` for temp directories\n- No emojis in code or comments\n- **Comments**: every comment must earn its place — one short line by\n  default; multi-line only for a genuinely non-obvious WHY (subtle\n  invariant, workaround, spec quirk).  Never restate the code, narrate the\n  next line, justify the change to a reviewer, or describe past states of\n  the code.\n- **A `JsonConfig` is read only through `ConfigDeserializer` or `PluginJson.read(JsonConfig, Class)`**,\n  which apply request restrictions and `@OperatorOnly`; forbidden-apis rejects\n  `JsonConfig.json()` in main code outside tika-serialization. Per-request plugin config is\n  read into a class holding only what a request may set.\n- **XML is parsed only through `XMLReaderUtils.parseSAX` \u002F `buildDOM`** (forbidden-apis\n  rejects the JAXP and Commons Secure XML factories and the raw `getSAXParser` \u002F\n  `getXMLReader` \u002F `getDocumentBuilder` in main code). Never install an `EntityResolver`;\n  a resolver that returns null or a stream-less `InputSource` makes the parser fetch the\n  id itself (CVE-2025-66516). A new XML-bearing format gets a fixture in `TestXXEInXML`;\n  a third-party library that parses XML with its own parser gets its own oracle test\n  (see `GeographicInformationXxeTest`) before it ships.\n- **Input files are hostile**: bound anything derived from document content\n  (loop counts, allocations, timeouts); release external processes, temp\n  files, and pool slots on every failure path.\n- **No local\u002Fmachine-specific paths** in committed code, tests, docs, or\n  config — never `\u002Fhome\u002F\u003Cuser>`, `\u002FUsers\u002F\u003Cuser>`, `C:\\Users\\\u003Cuser>`, or a\n  personal `~\u002Fdata\u002F...`.  Use a placeholder (`\u003Cworkdir>\u002F`, `\u003Ccorpus>`),\n  `@TempDir`, or an in-repo `src\u002Ftest\u002Fresources` fixture instead.  *Only*\n  legitimate exception: a path that is the data under test (e.g. an expected\n  metadata value extracted from a test document) — leave those untouched.\n\n## NEVER: two mistakes that ship as vulnerabilities\n\n**Never trust a length that came from user input or from inside a file.** `Content-Length`\non a request, a zip or 7z entry's declared size, an OLE\u002FOOXML part size, a PDF embedded\nfile's `\u002FSize`, an ISO box length, a count line in a mail file: every one of them is an\nuntrusted number. Never allocate, reserve, `mark()`, `skip()` or bound a loop by it as if it\nwere true. A lie small truncates content silently; a lie large lets one document allocate the\nheap or a budget, or spin a reader waiting for bytes that never come. Use a declared length\nonly to *decline* work (a size the budget cannot cover is not attempted) or as a hint that the\nactual read corrects; grow from a floor and reserve what was actually read; treat the measured\nend of the stream as the only ground truth (`hasReliableLength()`), and overwrite the claim\nwith it. See TIKA-4908 and the 2026-09-19 stream audit for what this cost.\n\n**Never call `InputStream.skip()` on a stream that could be a `FileInputStream` (or a\n`BufferedInputStream` over one) and trust the answer.** `FileInputStream.skip(n)` seeks past\nEOF and returns `n` even when no bytes exist, so a reader that skips a payload and then reads\nthe next header believes it is somewhere it is not, and loops or mis-parses forever;\n`BufferedInputStream.skip` can return 0 before EOF, which spins any `while (remaining > 0)\nremaining -= skip(remaining)` loop. Skip by reading (`IOUtils.skip` \u002F `IOUtils.skipFully`) or\nseek on a channel or an in-memory buffer whose size you own; `TikaInputStream.skip`,\n`BoundedInputStream.skip` and every source's `seekTo` read for this reason. Do not \"optimize\"\nthem back. Anything hot enough to need a real seek gets a channel from\n`getSeekableByteChannel()`, never a raw `skip`.\n\n## Test Discipline\n\n- A behavioral change gets a regression test that fails without it.  Where\n  impractical (timing, native binaries, external services, kill paths), say\n  so explicitly and name the next-best check.\n- Prove a negative by reverting the fix: an \"X does not happen\" test that\n  still passes is not a test.  Assert on what the consumer is handed, not an\n  ambient side effect (a `@TempDir` watch misses `TemporaryResources` not\n  bound to it).\n- Cover error paths and the configuration\u002Fmode matrix — a behavior verified\n  in only one parse mode or config shape is a gap (RMETA-only tests miss\n  CONCATENATE-only bugs).\n- Keep tests non-duplicative: don't add a test whose failure another test\n  already guarantees.\n- `-Dtika.test.locale=random` runs every test JVM under a random default locale\n  (`RandomLocaleListener` in `tika-test-support`, wired through tika-parent); run it\n  before touching anything that formats or parses text. The PR jobs leave it off\n  until `nightly-locale-build` (one full build per priority locale, plus a random\n  draw) has been green several nights running (TIKA-4920). A plain build keeps the\n  JVM's own locale. A failure's stack trace and the fork's stderr name the locale;\n  reproduce with `-Dtika.test.locale=\u003Ctag>`.  A test that fails only\n  in some locales is a bug in the code under test (use `Locale.ROOT`), not a\n  reason to pin `Locale.US` in the test.\n- Where there's bang for the buck, prefer parameterized tests over\n  copy-pasted cases, randomized inputs over hand-picked ones (log the seed\n  so failures reproduce), and fuzzing for parsers and format\u002Fboundary\n  arithmetic.  Don't force it on code a couple of fixed cases fully cover.\n\n## Metadata Keys & Schema Registry\n\nAdding\u002Frenaming a metadata key touches the committed, build-gated registry in\n`tika-metadata-schema` — regeneration has real traps. See\n`.skills\u002Fdevs\u002Fmetadata-schema\u002FSKILL.md`.\n\n## Testing an End-to-End Change\n\nWhen a change affects parsing output (e.g., new parser behavior,\nencoding fix), run a before\u002Fafter comparison using tika-eval.\nSee `.skills\u002Fdevs\u002Ftika-eval-compare\u002FSKILL.md` for the full procedure.\n\n## Pre-Commit Checks\n\n```bash\n# Full compile with checkstyle (catches formatting issues)\n.\u002Fmvnw clean compile -pl \u003Cmodule> -am \\\n  -Dmaven.repo.local=$(pwd)\u002F.local_m2_repo\n\n# Run module tests\n.\u002Fmvnw clean test -pl \u003Cmodule> \\\n  -Dmaven.repo.local=$(pwd)\u002F.local_m2_repo\n```\n\nAlso before commit:\n\n- Commit message \u002F PR title references a JIRA ticket (`TIKA-XXXX`).\n- CHANGES entry for user-visible changes.\n- New dependencies: ASF-compatible license; LICENSE\u002FNOTICE updated.\n\nScan the staged diff for machine-specific local paths before committing\n(see Code Conventions). Added lines only; review any hit by hand — a test\nfixture's expected value is allowed, a real config\u002Fdoc\u002Fcode path is not:\n\n```bash\ngit diff --cached -U0 | grep -E '^\\+' \\\n  | grep -nE '\u002Fhome\u002F[A-Za-z0-9._-]+|\u002FUsers\u002F[A-Za-z0-9._-]+|[A-Za-z]:\\\\+Users|~\u002Fdata\u002F' \\\n  && echo \"^ local path in staged diff — replace with a placeholder\u002Ffixture\"\n```\n","\u003C!--\nLicensed to the Apache Software Foundation (ASF) under one or more\ncontributor license agreements.  See the NOTICE file distributed with\nthis work for additional information regarding copyright ownership.\nThe ASF licenses this file to You under the Apache License, Version 2.0\n(the \"License\"); you may not use this file except in compliance with\nthe License.  You may obtain a copy of the License at\n\n    http:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n-->\n\nLocal override: `$TIKA_SKILLS_LOCAL\u002Fdevelopment\u002FLOCAL.md` (default `~\u002F.tika-skills`),\nread after this file, wins on conflict.\n\n# Tika Development Skill\n\nGuidelines and checklist for developing against the Apache Tika codebase.\n\n## Question the direction, not just the code\n\nBefore optimizing a change — yours or a PR's — ask whether it should exist:\ndoes it belong in Tika, is the complexity proportional to the need, would\nconfig, an existing mechanism, a plugin, or documentation serve the use case\nmore cheaply?  Every merged feature is surface the project maintains for\ndecades.  Steelman the use case first and question the vehicle, not the goal;\npushback must name a concrete cost or a simpler path — never taste alone, and\nnever no for the sake of no.  \"The direction is right\" is a valid conclusion.\n\nFeature whose shape isn't known yet: spike first, cut PRs after\n(`.skills\u002Fdevs\u002Ffeature-workflow\u002FSKILL.md`).\n\n## Git Policy (default — personally overridable)\n\nNever run `git commit` or `git push` — no commits of any kind, including\nmerge commits.  If a merge is needed, use `git merge --no-commit --no-ff`\nand hand back.  Stage files and provide the suggested commit message for\nthe user to run.\n\nNever write to GitHub (PR comments, reviews, issues, labels, merges).\nRead-only `gh` is fine.\n\n**Precedence**: these are conservative defaults for *workflow* — actions on\nthe contributor's own machine and accounts.  A contributor's personal agent\nconfiguration (their own skills, CLAUDE.md\u002FAGENTS.md, settings, or a\n`LOCAL.md` overlay — see `AGENTS.md`) may override them.  Everything else in\nthis file — code and comment conventions, test discipline, hygiene,\npre-commit checks — governs what lands in the repo and is project policy:\npersonal configuration does not override it.\n\n## Session Start Checklist\n\n1. **Local Maven repo** — Default to an in-repo `.local_m2_repo`\n   (via `-Dmaven.repo.local=$(pwd)\u002F.local_m2_repo`) unless the user says\n   otherwise.  This isolates builds from the shared `~\u002F.m2\u002Frepository` and\n   avoids polluting or being affected by other projects.\n\n2. **Maven wrapper** — Use `.\u002Fmvnw`; fall back to a system Maven (3.9+)\n   only if the wrapper is absent.\n\n3. **Merge conflicts** — Check `git status` for `UU` files and resolve\n   before building.\n\n## Maven Rules\n\n- **Always include `clean`** in every `.\u002Fmvnw` invocation.\n  Stale classes in `target\u002F` cause hard-to-debug failures.\n  ```bash\n  .\u002Fmvnw clean compile -pl \u003Cmodule> ...   # not just: mvnw compile\n  .\u002Fmvnw clean test -pl \u003Cmodule> ...      # not just: mvnw test\n  .\u002Fmvnw clean install -pl \u003Cmodule> ...   # not just: mvnw install\n  ```\n\n- **Always use absolute path for local repo**:\n  ```bash\n  -Dmaven.repo.local=$(pwd)\u002F.local_m2_repo\n  ```\n\n- **Fast builds with `-Pfast`** — use the `fast` profile to skip\n  tests, checkstyle, spotless, and rat in one flag.  Prefer this over\n  individual `-D` skip flags when you want a quick build (e.g.,\n  installing for downstream consumers or eval runs):\n  ```bash\n  .\u002Fmvnw clean install -pl \u003Cmodule> -am -Pfast \\\n    -Dmaven.repo.local=$(pwd)\u002F.local_m2_repo\n  ```\n  Run **without** `-Pfast` before final commit to catch formatting\n  and style issues.  License (rat) checks run only under `-Ppedantic`\n  (or explicit `apache-rat:check`), not in default builds.\n\n  **`-Pfast` skips test *execution*** (by design): a green `-Pfast`\n  build — including `-Pfast test` — has run zero tests, and stale\n  `target\u002Fsurefire-reports\u002F*` will look current. Verify with a plain\n  (non-`-Pfast`) `test` run.\n\n- **Plugin zips resolve only after `package`** — a reactor `clean test`\n  fails on modules that depend on pipes plugin zips (`tika-server-core`,\n  `tika-app`, ...) unless the zips are already in the local repo.  Use\n  `clean install` (or `-Pfast install` first).\n\n- **Forked JVM tests** — Integration tests in `tika-pipes` fork new\n  JVMs that load classes from the local Maven repo, not from\n  `target\u002Fclasses`.  You must `.\u002Fmvnw clean install -Pfast` the\n  changed modules before running integration tests that fork.\n\n## Building Specific Modules\n\n```bash\n# Single module (with dependencies)\n.\u002Fmvnw clean compile -pl \u003Cmodule> -am \\\n  -Dmaven.repo.local=$(pwd)\u002F.local_m2_repo\n\n# Run a single test class\n.\u002Fmvnw clean test -pl \u003Cmodule> -Dtest=\u003CTestClass> \\\n  -Dmaven.repo.local=$(pwd)\u002F.local_m2_repo -Dcheckstyle.skip=true\n\n# Install for downstream consumers (tika-app, integration tests)\n.\u002Fmvnw clean install -pl \u003Cmodule> -am -Pfast \\\n  -Dmaven.repo.local=$(pwd)\u002F.local_m2_repo\n```\n\n## Building the Docs\n\n`docs\u002F` is not in the default reactor; build it from its own pom. Antora\nrenders the checked-out branch from the worktree, so uncommitted `.adoc`\nedits are included.\n\n```bash\n.\u002Fmvnw -f docs\u002Fpom.xml clean package     # site in docs\u002Ftarget\u002Fsite\u002Ftika\u002F\u003Cversion>\u002F\n```\n\n- **Broken links don't fail the build** (`--log-failure-level=fatal`). Check\n  the log for `ERROR (asciidoctor)` lines such as `target of xref not found`.\n- **Parent-directory npm leaks in.** The Antora plugin runs `npx` in `docs\u002F`,\n  which has no `package.json` or `node_modules`, so npm and Node search\n  upward. A `package.json` or `node_modules` in any parent directory, often\n  `$HOME` after an `npm install` run there, becomes the npm project root and\n  supplies packages. The plugin warns `Detected the existence of\n  $HOME\u002Fnode_modules`. `npm prefix` in `docs\u002F` should print `docs\u002F`; if it\n  prints a parent, move that install elsewhere (e.g. `npm install -g`).\n- For a release build, use `update-site-for-release`.\n\n## Common Module Paths\n\n| Module | Path |\n|--------|------|\n| tika-core | `tika-core` |\n| tika-app | `tika-app` |\n| tika-server | `tika-server\u002Ftika-server-core` |\n| tika-eval | `tika-eval\u002Ftika-eval-app` |\n| Pipes core | `tika-pipes\u002Ftika-pipes-core` |\n| Pipes API | `tika-pipes\u002Ftika-pipes-api` |\n| Async CLI | `tika-pipes\u002Ftika-async-cli` |\n\n## Code Conventions\n\n- ASF License 2.0 header on all Java files\n- Spotless formatter runs during build — don't fight it\n- Tests use `@TempDir Path tmp` for temp directories\n- No emojis in code or comments\n- **Comments**: every comment must earn its place — one short line by\n  default; multi-line only for a genuinely non-obvious WHY (subtle\n  invariant, workaround, spec quirk).  Never restate the code, narrate the\n  next line, justify the change to a reviewer, or describe past states of\n  the code.\n- **A `JsonConfig` is read only through `ConfigDeserializer` or `PluginJson.read(JsonConfig, Class)`**,\n  which apply request restrictions and `@OperatorOnly`; forbidden-apis rejects\n  `JsonConfig.json()` in main code outside tika-serialization. Per-request plugin config is\n  read into a class holding only what a request may set.\n- **XML is parsed only through `XMLReaderUtils.parseSAX` \u002F `buildDOM`** (forbidden-apis\n  rejects the JAXP and Commons Secure XML factories and the raw `getSAXParser` \u002F\n  `getXMLReader` \u002F `getDocumentBuilder` in main code). Never install an `EntityResolver`;\n  a resolver that returns null or a stream-less `InputSource` makes the parser fetch the\n  id itself (CVE-2025-66516). A new XML-bearing format gets a fixture in `TestXXEInXML`;\n  a third-party library that parses XML with its own parser gets its own oracle test\n  (see `GeographicInformationXxeTest`) before it ships.\n- **Input files are hostile**: bound anything derived from document content\n  (loop counts, allocations, timeouts); release external processes, temp\n  files, and pool slots on every failure path.\n- **No local\u002Fmachine-specific paths** in committed code, tests, docs, or\n  config — never `\u002Fhome\u002F\u003Cuser>`, `\u002FUsers\u002F\u003Cuser>`, `C:\\Users\\\u003Cuser>`, or a\n  personal `~\u002Fdata\u002F...`.  Use a placeholder (`\u003Cworkdir>\u002F`, `\u003Ccorpus>`),\n  `@TempDir`, or an in-repo `src\u002Ftest\u002Fresources` fixture instead.  *Only*\n  legitimate exception: a path that is the data under test (e.g. an expected\n  metadata value extracted from a test document) — leave those untouched.\n\n## NEVER: two mistakes that ship as vulnerabilities\n\n**Never trust a length that came from user input or from inside a file.** `Content-Length`\non a request, a zip or 7z entry's declared size, an OLE\u002FOOXML part size, a PDF embedded\nfile's `\u002FSize`, an ISO box length, a count line in a mail file: every one of them is an\nuntrusted number. Never allocate, reserve, `mark()`, `skip()` or bound a loop by it as if it\nwere true. A lie small truncates content silently; a lie large lets one document allocate the\nheap or a budget, or spin a reader waiting for bytes that never come. Use a declared length\nonly to *decline* work (a size the budget cannot cover is not attempted) or as a hint that the\nactual read corrects; grow from a floor and reserve what was actually read; treat the measured\nend of the stream as the only ground truth (`hasReliableLength()`), and overwrite the claim\nwith it. See TIKA-4908 and the 2026-09-19 stream audit for what this cost.\n\n**Never call `InputStream.skip()` on a stream that could be a `FileInputStream` (or a\n`BufferedInputStream` over one) and trust the answer.** `FileInputStream.skip(n)` seeks past\nEOF and returns `n` even when no bytes exist, so a reader that skips a payload and then reads\nthe next header believes it is somewhere it is not, and loops or mis-parses forever;\n`BufferedInputStream.skip` can return 0 before EOF, which spins any `while (remaining > 0)\nremaining -= skip(remaining)` loop. Skip by reading (`IOUtils.skip` \u002F `IOUtils.skipFully`) or\nseek on a channel or an in-memory buffer whose size you own; `TikaInputStream.skip`,\n`BoundedInputStream.skip` and every source's `seekTo` read for this reason. Do not \"optimize\"\nthem back. Anything hot enough to need a real seek gets a channel from\n`getSeekableByteChannel()`, never a raw `skip`.\n\n## Test Discipline\n\n- A behavioral change gets a regression test that fails without it.  Where\n  impractical (timing, native binaries, external services, kill paths), say\n  so explicitly and name the next-best check.\n- Prove a negative by reverting the fix: an \"X does not happen\" test that\n  still passes is not a test.  Assert on what the consumer is handed, not an\n  ambient side effect (a `@TempDir` watch misses `TemporaryResources` not\n  bound to it).\n- Cover error paths and the configuration\u002Fmode matrix — a behavior verified\n  in only one parse mode or config shape is a gap (RMETA-only tests miss\n  CONCATENATE-only bugs).\n- Keep tests non-duplicative: don't add a test whose failure another test\n  already guarantees.\n- `-Dtika.test.locale=random` runs every test JVM under a random default locale\n  (`RandomLocaleListener` in `tika-test-support`, wired through tika-parent); run it\n  before touching anything that formats or parses text. The PR jobs leave it off\n  until `nightly-locale-build` (one full build per priority locale, plus a random\n  draw) has been green several nights running (TIKA-4920). A plain build keeps the\n  JVM's own locale. A failure's stack trace and the fork's stderr name the locale;\n  reproduce with `-Dtika.test.locale=\u003Ctag>`.  A test that fails only\n  in some locales is a bug in the code under test (use `Locale.ROOT`), not a\n  reason to pin `Locale.US` in the test.\n- Where there's bang for the buck, prefer parameterized tests over\n  copy-pasted cases, randomized inputs over hand-picked ones (log the seed\n  so failures reproduce), and fuzzing for parsers and format\u002Fboundary\n  arithmetic.  Don't force it on code a couple of fixed cases fully cover.\n\n## Metadata Keys & Schema Registry\n\nAdding\u002Frenaming a metadata key touches the committed, build-gated registry in\n`tika-metadata-schema` — regeneration has real traps. See\n`.skills\u002Fdevs\u002Fmetadata-schema\u002FSKILL.md`.\n\n## Testing an End-to-End Change\n\nWhen a change affects parsing output (e.g., new parser behavior,\nencoding fix), run a before\u002Fafter comparison using tika-eval.\nSee `.skills\u002Fdevs\u002Ftika-eval-compare\u002FSKILL.md` for the full procedure.\n\n## Pre-Commit Checks\n\n```bash\n# Full compile with checkstyle (catches formatting issues)\n.\u002Fmvnw clean compile -pl \u003Cmodule> -am \\\n  -Dmaven.repo.local=$(pwd)\u002F.local_m2_repo\n\n# Run module tests\n.\u002Fmvnw clean test -pl \u003Cmodule> \\\n  -Dmaven.repo.local=$(pwd)\u002F.local_m2_repo\n```\n\nAlso before commit:\n\n- Commit message \u002F PR title references a JIRA ticket (`TIKA-XXXX`).\n- CHANGES entry for user-visible changes.\n- New dependencies: ASF-compatible license; LICENSE\u002FNOTICE updated.\n\nScan the staged diff for machine-specific local paths before committing\n(see Code Conventions). Added lines only; review any hit by hand — a test\nfixture's expected value is allowed, a real config\u002Fdoc\u002Fcode path is not:\n\n```bash\ngit diff --cached -U0 | grep -E '^\\+' \\\n  | grep -nE '\u002Fhome\u002F[A-Za-z0-9._-]+|\u002FUsers\u002F[A-Za-z0-9._-]+|[A-Za-z]:\\\\+Users|~\u002Fdata\u002F' \\\n  && echo \"^ local path in staged diff — replace with a placeholder\u002Ffixture\"\n```\n",{"name":5,"description":7},"main","9f8b48425fea3630020924f6ae96e98eabb9ce12",".skills\u002Fdevs\u002Fdevelopment",1039,"https:\u002F\u002Fgithub.com\u002Fapache\u002Ftika","https:\u002F\u002Ftika.apache.org\u002F","https:\u002F\u002Fgithub.com\u002Fapache","https:\u002F\u002Fwww.apache.org\u002F","2026-11-13 08:35:47",{"source":8,"skillName":5,"commands":59,"prompt":69,"zipAvailable":70},[60,63,66],{"tool":61,"command":62},"npx","npx skills add apache\u002Ftika --skill development",{"tool":64,"command":65},"bunx","bunx skills add apache\u002Ftika --skill development",{"tool":67,"command":68},"pnpm","pnpm dlx skills add apache\u002Ftika --skill development","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fapache\u002Ftika\u002Fblob\u002Fmain\u002F.skills\u002Fdevs\u002Fdevelopment\u002FSKILL.md",true,[72,78,82,86,90],{"path":73,"resourceType":74,"resourceTypeDesc":75,"sizeBytes":76,"sourceHtmlUrl":77},"references\u002Fhazard-catalog.md","REFERENCE","参考文档",20837,"https:\u002F\u002Fgithub.com\u002Fgithub\u002Fawesome-copilot\u002Fblob\u002Fmain\u002Fskills\u002Fpoka-yoke\u002Freferences\u002Fhazard-catalog.md",{"path":79,"resourceType":74,"resourceTypeDesc":75,"sizeBytes":80,"sourceHtmlUrl":81},"references\u002Flang-python.md",6872,"https:\u002F\u002Fgithub.com\u002Fgithub\u002Fawesome-copilot\u002Fblob\u002Fmain\u002Fskills\u002Fpoka-yoke\u002Freferences\u002Flang-python.md",{"path":83,"resourceType":74,"resourceTypeDesc":75,"sizeBytes":84,"sourceHtmlUrl":85},"references\u002Flang-rust-go.md",7773,"https:\u002F\u002Fgithub.com\u002Fgithub\u002Fawesome-copilot\u002Fblob\u002Fmain\u002Fskills\u002Fpoka-yoke\u002Freferences\u002Flang-rust-go.md",{"path":87,"resourceType":74,"resourceTypeDesc":75,"sizeBytes":88,"sourceHtmlUrl":89},"references\u002Flang-typescript.md",6045,"https:\u002F\u002Fgithub.com\u002Fgithub\u002Fawesome-copilot\u002Fblob\u002Fmain\u002Fskills\u002Fpoka-yoke\u002Freferences\u002Flang-typescript.md",{"path":91,"resourceType":92,"resourceTypeDesc":93,"sizeBytes":94,"sourceHtmlUrl":95},"scripts\u002Fdetect_hazards.py","SCRIPT","脚本",26794,"https:\u002F\u002Fgithub.com\u002Fgithub\u002Fawesome-copilot\u002Fblob\u002Fmain\u002Fskills\u002Fpoka-yoke\u002Fscripts\u002Fdetect_hazards.py",[97,137,163,190,215,240],{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":112,"publishedAt":44},"01M6ACFKZR081Z7QX5XB1ZA2R2","file-to-markdown","Turn almost any file into Markdown plus metadata — PDF, Office, HTML, email, archives, images, audio\u002Fvideo, 1000+ formats — powered by Apache Tika, either via the tika-app CLI (zero setup, one file) or a running tika-server (curl, warm process, many calls). Leads with rmeta (structured, embedded-item-aware output) as the default operation rather than flat concatenated text, since you can't tell whether a file has embedded content from its extension. Covers metadata-only triage, type and language detection, OCR, and output-size discipline for agent context. Use whenever a task involves reading the content of a file whose format you don't want to hand-parse.","https:\u002F\u002Fgithub.com\u002Fapache\u002Ftika\u002Fblob\u002Fmain\u002F.skills\u002Fusers\u002Ffile-to-markdown\u002FSKILL.md",[103,106,109],{"categoryNo":104,"categoryName":105,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000002","文档处理",{"categoryNo":107,"categoryName":108,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000016","图像与多媒体",{"categoryNo":110,"categoryName":111,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[113,114,115,116,117,9,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136],"file to markdown","markdown","file","PDF","cli","triage","setup","content","metadata","tika","images","Video","app","ocr","Audio","parse","default","only","either","you","hand","text","server","discipline",{"skillNo":138,"name":139,"nameZh":6,"description":140,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":141,"categories":142,"keywords":147,"publishedAt":44},"01M6ACFHJR3612ZE6RNX1P5WG9","file-to-markdown-docker","Run Apache Tika as a Docker container when you need guaranteed OCR (scanned PDFs, images) or geospatial raster support with zero local install — `apache\u002Ftika:\u003Cversion>-full` bundles Tesseract, GDAL, ImageMagick, and fonts. Also covers the minimal image, port\u002Fvolume\u002Fmemory conventions, the path-identity mount gotcha, and how to confirm OCR actually ran rather than silently returning no text. Powered by Apache Tika. Use when a local `tika-app`\u002F`tika-server` doesn't have Tesseract installed, or you want a disposable, self-contained parsing environment. Companion to the `file-to-markdown` skill, which covers the parsing calls themselves once a server is up.","https:\u002F\u002Fgithub.com\u002Fapache\u002Ftika\u002Fblob\u002Fmain\u002F.skills\u002Fusers\u002Ffile-to-markdown-docker\u002FSKILL.md",[143,144],{"categoryNo":104,"categoryName":105,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":145,"categoryName":146,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000011","运维与部署",[148,149,113,114,115,9,150,151,152,153,154,122,123,125,126,155,156,157,158,159,160,132,161,134,162],"file to markdown docker","docker","support","memory","image","run","identity","which","volume","up","local","how to","when","fonts","self",{"skillNo":164,"name":165,"nameZh":6,"description":166,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":167,"categories":168,"keywords":170,"publishedAt":44},"01M6ACFE1684DE184VE0D7PQVY","file-forensics","Examine what a file claims about itself and what it actually contains — powered by Apache Tika. True content-based type detection (extensions lie), provenance claims (authors, dates, creating application), revision and tamper signals (PDF incremental updates, tracked changes, hidden slides, zip integrity), hidden and embedded content (attachments, macros), risk indicators (PDF JavaScript actions, encryption), and content digests. Evidence gathering, not verdicts: Tika reports what the file asserts and what parsing observed; it does not attribute authorship or validate signatures. Use for triaging suspicious files, provenance questions, e-discovery-style review, or \"is this file what it claims to be.\"","https:\u002F\u002Fgithub.com\u002Fapache\u002Ftika\u002Fblob\u002Fmain\u002F.skills\u002Fusers\u002Ffile-forensics\u002FSKILL.md",[169],{"categoryNo":104,"categoryName":105,"taxonomyType":21,"taxonomyTypeDesc":22},[171,115,172,173,174,116,9,175,120,176,122,177,178,179,180,181,182,183,184,185,186,187,188,189],"file forensics","forensics","javascript","suspicious","validate","review","actions","signatures","files","updates","encryption","reports","claims","signals","revision","integrity","zip","evidence","risk",{"skillNo":191,"name":192,"nameZh":6,"description":193,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":194,"categories":195,"keywords":196,"publishedAt":44},"01M6ACFB92SPADF0FY4490B847","update-site-for-release","Update\u002Fpublish the Apache Tika website (tika-site SVN repo) for a release — step 17 of the Release Process. Handles the 4.x track (Changes page + aggregate javadoc + Antora docs branch) vs the 3.x maintenance track (full per-version apt docs + javadoc). Use for \"update the site\", \"publish the site for X.Y.Z\", \"the website part of the release\".","https:\u002F\u002Fgithub.com\u002Fapache\u002Ftika\u002Fblob\u002Fmain\u002F.skills\u002Fdevs\u002Fupdate-site-for-release\u002FSKILL.md",[],[197,198,199,25,200,9,201,202,122,203,204,205,206,207,208,209,210,34,211,212,213,214],"update","release","update site for release","site","release process","docs","branch","publish","track","website","svn","full","apt","page","use","version","changes","maintenance",{"skillNo":216,"name":217,"nameZh":6,"description":218,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":219,"categories":220,"keywords":227,"publishedAt":44},"01M6ACF9G52NYHXQ0BVSJ3VH6E","tika-eval-h2-query","Query the tika-eval H2 database directly for counts and joins the canned reports do not compute — connection gotchas, key tables, example queries. Use when the xlsx\u002Fsummary.md reports are not enough.","https:\u002F\u002Fgithub.com\u002Fapache\u002Ftika\u002Fblob\u002Fmain\u002F.skills\u002Fdevs\u002Ftika-eval-h2-query\u002FSKILL.md",[221,224],{"categoryNo":222,"categoryName":223,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000004","电子表格",{"categoryNo":225,"categoryName":226,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口",[228,122,229,230,231,232,233,25,234,211,160,235,182,236,237,238,239],"tika eval h2 query","eval","query","database","xlsx","do","example","compute","queries","summary","connection","tables",{"skillNo":241,"name":242,"nameZh":6,"description":243,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":244,"categories":245,"keywords":246,"publishedAt":44},"01M6ACF7V56CCWHNVR614VBNX5","tika-eval-encoding-regression","Condensed tika-eval pattern for charset-detector regression hunts (\"A picks encoding X, B picks Y\") using one build and two configs — encoding-pair flip queries, OOV\u002Flanguageness\u002FFFFD signals, per-file detector attribution.","https:\u002F\u002Fgithub.com\u002Fapache\u002Ftika\u002Fblob\u002Fmain\u002F.skills\u002Fdevs\u002Ftika-eval-encoding-regression\u002FSKILL.md",[],[247,122,248,229,249,25,250,115,236,184,251,252,253,254],"tika eval encoding regression","regression","encoding","attribution","build","detector","pattern","pair"]