{"owner":"juicedata","repo":"juicefs","hasSkills":true,"totalSkillsCount":2,"totalTokensCount":2616,"categories":["root-instruction","anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md",".agents/skills/review/SKILL.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nJuiceFS is a POSIX-compatible distributed file system written in Go\n(`module github.com/juicedata/juicefs`). A client coordinates a **metadata engine**\nand **object storage**, exposing POSIX (FUSE) and an S3 gateway, plus Java/Hadoop\n(`sdk/java/`) and Python (`sdk/python/`) SDKs.\n\nMetadata engine families under `pkg/meta/`:\n\n- **Redis** — `redisMeta` (`redis.go`); also KeyDB.\n- **SQL/DB** — `dbMeta` (`sql.go`): MySQL, PostgreSQL, SQLite.\n- **KV (TKV)** — `kvMeta` (`tkv.go`): TiKV, etcd, BadgerDB, FoundationDB.\n\n## Repository map\n\nEntry points: `main.go` (root) and `cmd/main.go` (CLI commands live in `cmd/`).\n\n| Path           | Responsibility                                                  |\n| -------------- | --------------------------------------------------------------- |\n| `cmd/`         | CLI subcommands (`mount`, `gateway`, `sync`, `format`, `gc`, …) |\n| `pkg/meta/`    | Metadata engine abstraction + per-engine implementations        |\n| `pkg/vfs/`     | Virtual filesystem layer (POSIX semantics)                      |\n| `pkg/fuse/`    | FUSE bindings (Linux/macOS); `pkg/winfsp/` for Windows          |\n| `pkg/fs/`      | High-level filesystem logic                                     |\n| `pkg/chunk/`   | Chunk / slice / block data management and caching               |\n| `pkg/object/`  | Object storage backend abstraction                              |\n| `pkg/gateway/` | S3-compatible gateway                                           |\n| `pkg/sync/`    | Data synchronization (`juicefs sync`)                           |\n| `pkg/acl/`     | POSIX ACL support                                               |\n| `docs/`        | Documentation: `docs/en/` (English), `docs/zh_cn/` (Chinese)    |\n\n## Build\n\n```sh\nmake juicefs                 # standard build -> ./juicefs\nSTATIC=1 make juicefs        # static binary (needs musl-gcc)\nmake BUILD=debug all         # debug build (-N -l)\nmake juicefs.lite            # minimal build, most backends disabled\nmake juicefs.ceph            # -tags ceph\nmake juicefs.fdb             # -tags fdb (FoundationDB)\n```\n\nLocal volume for manual testing (SQLite metadata):\n\n```sh\n./juicefs format sqlite3://test.db myjfs    # create a volume\n./juicefs mount  sqlite3://test.db /tmp/jfs # mount it\n```\n\n## Test\n\nUse the smallest target covering your change. Targets are in the `Makefile`\nand mirror CI (`.github/workflows/unittests.yml`).\n\n```sh\nmake test.meta.core          # ./pkg/meta/... core (no external services)\nmake test.meta.non-core      # Redis/PostgreSQL/etcd/KeyDB engine tests\nmake test.pkg                # all ./pkg/... except meta (-tags gluster)\nmake test.cmd                # ./cmd/... (needs MinIO env, runs under sudo)\nmake test.fdb                # FoundationDB tests (-tags fdb)\n```\n\n| Change scope       | Run                                                               |\n| ------------------ | ----------------------------------------------------------------- |\n| `pkg/meta/**`      | `make test.meta.core` (+ `test.meta.non-core` if engine-specific) |\n| `cmd/**`           | `make test.cmd`                                                   |\n| any other `pkg/**` | `make test.pkg`                                                   |\n\n- When fixing a bug, add a regression test that fails before the fix and passes after.\n- Group new test cases for the same module/category together; extend an existing test\n  rather than scattering new cases.\n\n## Lint & format\n\n- Run `go fmt` before committing.\n- Linting uses `golangci-lint` per `.golangci.yml`; pre-commit pins v1.52.2 and CI runs v2.6 (see `.github/workflows/verify.yml`).\n- Install hooks once with `pre-commit install` (config in `.pre-commit-config.yaml`).\n\n## Code style & license header\n\n- Follow [Effective Go](https://go.dev/doc/effective_go) and\n  [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments).\n- Prefer self-explanatory code over redundant comments; keep necessary comments concise.\n- Every new `.go` file MUST start with the Apache 2.0 header (see `main.go` for the canonical template).\n\n## Version compatibility\n\n- Persistent metadata or serialization changes in `pkg/meta/{interface,redis,sql,tkv}.go`\n  must remain readable by new clients, and old clients must not silently drop new\n  fields when rewriting records.\n- When metadata fields change, review `pkg/meta/{dump,backup}.go`, `pkg/meta/*_bak.go`,\n  and `pb/backup.proto`. Released dump/load formats must remain readable; tolerate\n  unknown fields where feasible, reject unsupported formats explicitly, and never\n  silently lose correctness-critical data.\n- Evaluate mixed-version behavior for metadata features or semantic changes. If\n  unsafe, raise (never lower) `MinClientVersion` and enable the feature only after\n  old clients have exited.\n- FUSE option changes must preserve existing names and defaults. Review graceful\n  restart, `FuseOptions`, `StripOptions`, and old-config normalization in\n  `cmd/mount_unix.go`, `pkg/vfs/vfs.go`, and `pkg/fuse/fuse.go`.\n- Add compatibility tests, or explicitly report missing coverage during review.\n\n## Agent boundaries\n\n- Correctness first: this is a distributed file system; small changes can affect data\n  integrity. Do not invent APIs, defaults, or behavior — verify against the code, and\n  don't bypass safety checks.\n- Metadata-engine parity: a semantic change in `pkg/meta/` must behave identically\n  across all three families (Redis, SQL/DB, KV) and be covered by their shared tests.\n- Behavior changes need matching unit tests; user-facing changes update the docs.\n- Keep issues and pr comments concise: state the problem clearly and avoid lengthy exposition.\n- Keep PRs minimal and focused on the current task; avoid unrelated features,\n  refactors, or formatting-only churn.\n- Do not hand-edit generated code or vendored dependencies.\n- Match existing conventions in the file you are editing.\n- Confirm before destructive or hard-to-reverse actions (deleting files, force pushes,\n  schema/data changes).\n",".agents/skills/review/SKILL.md":"---\nname: review\ndescription: \"Perform evidence-based reviews of PRs, commits, patches, files, issue fixes, designs, or implementation plans. Use for code review, risk and compatibility analysis, test coverage review, and verifying reported bugs or requirements before evaluating a change.\"\nargument-hint: \"[PR | diff | commit | issue | files]\"\nuser-invocable: true\n---\n\n# Review\n\nReview changes for correctness and actionable risk. Verify claims against primary evidence before judging the implementation. Use Chinese when communicating with users.\n\n## Principles\n\n1. **Verify the background**: establish the concrete problem, trigger conditions, affected behavior, and whether the problem is real.\n2. **Prefer primary evidence**: rely on code paths, tests, command output, specifications, official documentation, and first-party project documentation.\n3. **Separate facts from inferences**: label uncertainty and state what evidence is missing.\n4. **Report actionable issues**: explain concrete impact and a recommended action; skip automated formatting/lint concerns and personal preferences unless they expose real risk.\n5. **Respect project context**: follow applicable repository instructions and existing architecture, naming, error handling, logging, and test conventions. Do not request unrelated refactors.\n6. **Review by default**: do not modify code unless the user explicitly asks for fixes.\n\n## Workflow\n\n### 1. Establish Scope and Background\n\n- Identify the target: PR, branch diff, commit, issue, files, or code snippet. Clarify only material ambiguity; do not expand the scope without reason.\n- For remote PRs or issues, use available repository or GitHub tooling to inspect the description, comments, linked items, checks, history, and diff.\n- Unless a PR is small and self-explanatory, require the PR description or a linked issue to explain its background and motivation. If that context is missing, ask the author to add it rather than inferring the rationale solely from the diff.\n- Determine the claimed problem, trigger conditions, affected users, and visible behavior. Do not treat the PR or issue description as proof.\n- Verify the claim through code paths, tests, logs, existing behavior, history, or documentation. For external behavior, prefer official or first-party sources and cite the evidence. State anything that remains unverified.\n\n### 2. Review the Approach\n\nCheck whether the change:\n\n- Addresses the root cause rather than masking a symptom.\n- Covers main paths, boundary conditions, error paths, failure modes, compatibility, migration, and rollback where relevant.\n- Fits existing abstractions without bypassing helpers, validation, locking, transactions, permission checks, or safety mechanisms.\n- Avoids unnecessary behavior changes and documents intentional user-facing changes.\n\n### 3. Review Implementation and Tests\n\nEvaluate the relevant dimensions:\n\n- **Correctness and reliability**: logic, edge cases, error propagation, races, nil/bounds errors, resource leaks, transaction consistency, and recovery.\n- **Simplicity and consistency**: directness, duplication, hidden side effects, existing helpers and patterns, and language conventions.\n- **Performance**: avoidable I/O, lock contention, full scans, repeated network calls, memory amplification, and hot-path overhead.\n- **Security**: permissions, authentication, path and input handling, sensitive data, data integrity, and recoverability.\n- **Compatibility**: APIs, CLIs, configuration, serialized formats, cross-version behavior, and backend parity.\n- **Tests**: reproduction of the original problem, fixed behavior, boundaries, errors, concurrency, compatibility, and backend-specific paths. Check that tests are stable, minimal, readable, and use the smallest relevant commands. If tests were not run, explain why and recommend them.\n- **JuiceFS**: apply `AGENTS.md`, especially its requirements for POSIX semantics, data integrity, metadata-engine parity, dump/load and mixed-version compatibility, object-storage behavior, concurrency, and failure recovery.\n\n### 4. Report the Review\n\nUse the following three top-level sections, in this order. This gives the reader enough context to understand the review before presenting defects and risks.\n\n```markdown\n## Summary\n\n## Solution\n\n## Findings\n```\n\nIn **Summary**:\n\n- Summarize the reported problem, relevant background, trigger conditions, affected users or behavior, and expected behavior.\n- State the verified root cause when the evidence supports one. Clearly distinguish verified facts from claims, assumptions, and unknowns.\n- Keep this section concise and focused on the context needed to evaluate the change.\n\nIn **Solution**:\n\n- Explain the implemented or proposed solution, its key mechanism, and the main code paths or components it changes.\n- Describe why the approach addresses the problem, plus important compatibility, migration, performance, security, or design tradeoffs when relevant.\n- Summarize the approach rather than narrating the diff file by file. Do not present the solution as correct before completing the review.\n\nIn **Findings**:\n\n- List actionable findings ordered by severity. Each finding should use this structure:\n\n```markdown\n### [Severity] Title\n\n- Location: `path:line`\n- Problem: ...\n- Impact: ...\n- Evidence: ...\n- Recommendation: ...\n```\n\n- After the individual findings, include assumptions or unknowns, tests run or not run, remaining risks, and a verdict when supported by sufficient evidence: Approve, Request changes, Comment only, or Need more information. Keep this supporting review context within the **Findings** section instead of creating additional top-level sections.\n\n- If there are no findings, say so explicitly under **Findings**, then identify what was checked and what remains unverified.\n\n## Severity\n\n- **Critical**: likely data loss or corruption, permission bypass, security vulnerability, severe outage, or unrecoverable incompatibility.\n- **High**: likely real-world wrong behavior, crash, major performance regression, or key feature regression.\n- **Medium**: edge-case defect, compatibility risk, or test gap that may hide a real regression.\n- **Low**: minor, non-blocking risk or maintainability issue; do not report pure style preferences.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nJuiceFS is a POSIX-compatible distributed file system written in Go\n(`module github.com/juicedata/juicefs`). A client coordinates a **metadata engine**\nand **object storage**, exposing POSIX (FUSE) and an S3 gateway, plus Java/Hadoop\n(`sdk/java/`) and Python (`sdk/python/`) SDKs.\n\nMetadata engine families under `pkg/meta/`:\n\n- **Redis** — `redisMeta` (`redis.go`); also KeyDB.\n- **SQL/DB** — `dbMeta` (`sql.go`): MySQL, PostgreSQL, SQLite.\n- **KV (TKV)** — `kvMeta` (`tkv.go`): TiKV, etcd, BadgerDB, FoundationDB.\n\n## Repository map\n\nEntry points: `main.go` (root) and `cmd/main.go` (CLI commands live in `cmd/`).\n\n| Path           | Responsibility                                                  |\n| -------------- | --------------------------------------------------------------- |\n| `cmd/`         | CLI subcommands (`mount`, `gateway`, `sync`, `format`, `gc`, …) |\n| `pkg/meta/`    | Metadata engine abstraction + per-engine implementations        |\n| `pkg/vfs/`     | Virtual filesystem layer (POSIX semantics)                      |\n| `pkg/fuse/`    | FUSE bindings (Linux/macOS); `pkg/winfsp/` for Windows          |\n| `pkg/fs/`      | High-level filesystem logic                                     |\n| `pkg/chunk/`   | Chunk / slice / block data management and caching               |\n| `pkg/object/`  | Object storage backend abstraction                              |\n| `pkg/gateway/` | S3-compatible gateway                                           |\n| `pkg/sync/`    | Data synchronization (`juicefs sync`)                           |\n| `pkg/acl/`     | POSIX ACL support                                               |\n| `docs/`        | Documentation: `docs/en/` (English), `docs/zh_cn/` (Chinese)    |\n\n## Build\n\n```sh\nmake juicefs                 # standard build -> ./juicefs\nSTATIC=1 make juicefs        # static binary (needs musl-gcc)\nmake BUILD=debug all         # debug build (-N -l)\nmake juicefs.lite            # minimal build, most backends disabled\nmake juicefs.ceph            # -tags ceph\nmake juicefs.fdb             # -tags fdb (FoundationDB)\n```\n\nLocal volume for manual testing (SQLite metadata):\n\n```sh\n./juicefs format sqlite3://test.db myjfs    # create a volume\n./juicefs mount  sqlite3://test.db /tmp/jfs # mount it\n```\n\n## Test\n\nUse the smallest target covering your change. Targets are in the `Makefile`\nand mirror CI (`.github/workflows/unittests.yml`).\n\n```sh\nmake test.meta.core          # ./pkg/meta/... core (no external services)\nmake test.meta.non-core      # Redis/PostgreSQL/etcd/KeyDB engine tests\nmake test.pkg                # all ./pkg/... except meta (-tags gluster)\nmake test.cmd                # ./cmd/... (needs MinIO env, runs under sudo)\nmake test.fdb                # FoundationDB tests (-tags fdb)\n```\n\n| Change scope       | Run                                                               |\n| ------------------ | ----------------------------------------------------------------- |\n| `pkg/meta/**`      | `make test.meta.core` (+ `test.meta.non-core` if engine-specific) |\n| `cmd/**`           | `make test.cmd`                                                   |\n| any other `pkg/**` | `make test.pkg`                                                   |\n\n- When fixing a bug, add a regression test that fails before the fix and passes after.\n- Group new test cases for the same module/category together; extend an existing test\n  rather than scattering new cases.\n\n## Lint & format\n\n- Run `go fmt` before committing.\n- Linting uses `golangci-lint` per `.golangci.yml`; pre-commit pins v1.52.2 and CI runs v2.6 (see `.github/workflows/verify.yml`).\n- Install hooks once with `pre-commit install` (config in `.pre-commit-config.yaml`).\n\n## Code style & license header\n\n- Follow [Effective Go](https://go.dev/doc/effective_go) and\n  [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments).\n- Prefer self-explanatory code over redundant comments; keep necessary comments concise.\n- Every new `.go` file MUST start with the Apache 2.0 header (see `main.go` for the canonical template).\n\n## Version compatibility\n\n- Persistent metadata or serialization changes in `pkg/meta/{interface,redis,sql,tkv}.go`\n  must remain readable by new clients, and old clients must not silently drop new\n  fields when rewriting records.\n- When metadata fields change, review `pkg/meta/{dump,backup}.go`, `pkg/meta/*_bak.go`,\n  and `pb/backup.proto`. Released dump/load formats must remain readable; tolerate\n  unknown fields where feasible, reject unsupported formats explicitly, and never\n  silently lose correctness-critical data.\n- Evaluate mixed-version behavior for metadata features or semantic changes. If\n  unsafe, raise (never lower) `MinClientVersion` and enable the feature only after\n  old clients have exited.\n- FUSE option changes must preserve existing names and defaults. Review graceful\n  restart, `FuseOptions`, `StripOptions`, and old-config normalization in\n  `cmd/mount_unix.go`, `pkg/vfs/vfs.go`, and `pkg/fuse/fuse.go`.\n- Add compatibility tests, or explicitly report missing coverage during review.\n\n## Agent boundaries\n\n- Correctness first: this is a distributed file system; small changes can affect data\n  integrity. Do not invent APIs, defaults, or behavior — verify against the code, and\n  don't bypass safety checks.\n- Metadata-engine parity: a semantic change in `pkg/meta/` must behave identically\n  across all three families (Redis, SQL/DB, KV) and be covered by their shared tests.\n- Behavior changes need matching unit tests; user-facing changes update the docs.\n- Keep issues and pr comments concise: state the problem clearly and avoid lengthy exposition.\n- Keep PRs minimal and focused on the current task; avoid unrelated features,\n  refactors, or formatting-only churn.\n- Do not hand-edit generated code or vendored dependencies.\n- Match existing conventions in the file you are editing.\n- Confirm before destructive or hard-to-reverse actions (deleting files, force pushes,\n  schema/data changes).\n",".agents/skills/review/SKILL.md":"---\nname: review\ndescription: \"Perform evidence-based reviews of PRs, commits, patches, files, issue fixes, designs, or implementation plans. Use for code review, risk and compatibility analysis, test coverage review, and verifying reported bugs or requirements before evaluating a change.\"\nargument-hint: \"[PR | diff | commit | issue | files]\"\nuser-invocable: true\n---\n\n# Review\n\nReview changes for correctness and actionable risk. Verify claims against primary evidence before judging the implementation. Use Chinese when communicating with users.\n\n## Principles\n\n1. **Verify the background**: establish the concrete problem, trigger conditions, affected behavior, and whether the problem is real.\n2. **Prefer primary evidence**: rely on code paths, tests, command output, specifications, official documentation, and first-party project documentation.\n3. **Separate facts from inferences**: label uncertainty and state what evidence is missing.\n4. **Report actionable issues**: explain concrete impact and a recommended action; skip automated formatting/lint concerns and personal preferences unless they expose real risk.\n5. **Respect project context**: follow applicable repository instructions and existing architecture, naming, error handling, logging, and test conventions. Do not request unrelated refactors.\n6. **Review by default**: do not modify code unless the user explicitly asks for fixes.\n\n## Workflow\n\n### 1. Establish Scope and Background\n\n- Identify the target: PR, branch diff, commit, issue, files, or code snippet. Clarify only material ambiguity; do not expand the scope without reason.\n- For remote PRs or issues, use available repository or GitHub tooling to inspect the description, comments, linked items, checks, history, and diff.\n- Unless a PR is small and self-explanatory, require the PR description or a linked issue to explain its background and motivation. If that context is missing, ask the author to add it rather than inferring the rationale solely from the diff.\n- Determine the claimed problem, trigger conditions, affected users, and visible behavior. Do not treat the PR or issue description as proof.\n- Verify the claim through code paths, tests, logs, existing behavior, history, or documentation. For external behavior, prefer official or first-party sources and cite the evidence. State anything that remains unverified.\n\n### 2. Review the Approach\n\nCheck whether the change:\n\n- Addresses the root cause rather than masking a symptom.\n- Covers main paths, boundary conditions, error paths, failure modes, compatibility, migration, and rollback where relevant.\n- Fits existing abstractions without bypassing helpers, validation, locking, transactions, permission checks, or safety mechanisms.\n- Avoids unnecessary behavior changes and documents intentional user-facing changes.\n\n### 3. Review Implementation and Tests\n\nEvaluate the relevant dimensions:\n\n- **Correctness and reliability**: logic, edge cases, error propagation, races, nil/bounds errors, resource leaks, transaction consistency, and recovery.\n- **Simplicity and consistency**: directness, duplication, hidden side effects, existing helpers and patterns, and language conventions.\n- **Performance**: avoidable I/O, lock contention, full scans, repeated network calls, memory amplification, and hot-path overhead.\n- **Security**: permissions, authentication, path and input handling, sensitive data, data integrity, and recoverability.\n- **Compatibility**: APIs, CLIs, configuration, serialized formats, cross-version behavior, and backend parity.\n- **Tests**: reproduction of the original problem, fixed behavior, boundaries, errors, concurrency, compatibility, and backend-specific paths. Check that tests are stable, minimal, readable, and use the smallest relevant commands. If tests were not run, explain why and recommend them.\n- **JuiceFS**: apply `AGENTS.md`, especially its requirements for POSIX semantics, data integrity, metadata-engine parity, dump/load and mixed-version compatibility, object-storage behavior, concurrency, and failure recovery.\n\n### 4. Report the Review\n\nUse the following three top-level sections, in this order. This gives the reader enough context to understand the review before presenting defects and risks.\n\n```markdown\n## Summary\n\n## Solution\n\n## Findings\n```\n\nIn **Summary**:\n\n- Summarize the reported problem, relevant background, trigger conditions, affected users or behavior, and expected behavior.\n- State the verified root cause when the evidence supports one. Clearly distinguish verified facts from claims, assumptions, and unknowns.\n- Keep this section concise and focused on the context needed to evaluate the change.\n\nIn **Solution**:\n\n- Explain the implemented or proposed solution, its key mechanism, and the main code paths or components it changes.\n- Describe why the approach addresses the problem, plus important compatibility, migration, performance, security, or design tradeoffs when relevant.\n- Summarize the approach rather than narrating the diff file by file. Do not present the solution as correct before completing the review.\n\nIn **Findings**:\n\n- List actionable findings ordered by severity. Each finding should use this structure:\n\n```markdown\n### [Severity] Title\n\n- Location: `path:line`\n- Problem: ...\n- Impact: ...\n- Evidence: ...\n- Recommendation: ...\n```\n\n- After the individual findings, include assumptions or unknowns, tests run or not run, remaining risks, and a verdict when supported by sufficient evidence: Approve, Request changes, Comment only, or Need more information. Keep this supporting review context within the **Findings** section instead of creating additional top-level sections.\n\n- If there are no findings, say so explicitly under **Findings**, then identify what was checked and what remains unverified.\n\n## Severity\n\n- **Critical**: likely data loss or corruption, permission bypass, security vulnerability, severe outage, or unrecoverable incompatibility.\n- **High**: likely real-world wrong behavior, crash, major performance regression, or key feature regression.\n- **Medium**: edge-case defect, compatibility risk, or test gap that may hide a real regression.\n- **Low**: minor, non-blocking risk or maintainability issue; do not report pure style preferences.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/juicedata/juicefs/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# AGENTS.md\n\nJuiceFS is a POSIX-compatible distributed file system written in Go\n(`module github.com/juicedata/juicefs`). A client coordinates a **metadata engine**\nand **object storage**, exposing POSIX (FUSE) and an S3 gateway, plus Java/Hadoop\n(`sdk/java/`) and Python (`sdk/python/`) SDKs.\n\nMetadata engine families under `pkg/meta/`:\n\n- **Redis** — `redisMeta` (`redis.go`); also KeyDB.\n- **SQL/DB** — `dbMeta` (`sql.go`): MySQL, PostgreSQL, SQLite.\n- **KV (TKV)** — `kvMeta` (`tkv.go`): TiKV, etcd, BadgerDB, FoundationDB.\n\n## Repository map\n\nEntry points: `main.go` (root) and `cmd/main.go` (CLI commands live in `cmd/`).\n\n| Path           | Responsibility                                                  |\n| -------------- | --------------------------------------------------------------- |\n| `cmd/`         | CLI subcommands (`mount`, `gateway`, `sync`, `format`, `gc`, …) |\n| `pkg/meta/`    | Metadata engine abstraction + per-engine implementations        |\n| `pkg/vfs/`     | Virtual filesystem layer (POSIX semantics)                      |\n| `pkg/fuse/`    | FUSE bindings (Linux/macOS); `pkg/winfsp/` for Windows          |\n| `pkg/fs/`      | High-level filesystem logic                                     |\n| `pkg/chunk/`   | Chunk / slice / block data management and caching               |\n| `pkg/object/`  | Object storage backend abstraction                              |\n| `pkg/gateway/` | S3-compatible gateway                                           |\n| `pkg/sync/`    | Data synchronization (`juicefs sync`)                           |\n| `pkg/acl/`     | POSIX ACL support                                               |\n| `docs/`        | Documentation: `docs/en/` (English), `docs/zh_cn/` (Chinese)    |\n\n## Build\n\n```sh\nmake juicefs                 # standard build -> ./juicefs\nSTATIC=1 make juicefs        # static binary (needs musl-gcc)\nmake BUILD=debug all         # debug build (-N -l)\nmake juicefs.lite            # minimal build, most backends disabled\nmake juicefs.ceph            # -tags ceph\nmake juicefs.fdb             # -tags fdb (FoundationDB)\n```\n\nLocal volume for manual testing (SQLite metadata):\n\n```sh\n./juicefs format sqlite3://test.db myjfs    # create a volume\n./juicefs mount  sqlite3://test.db /tmp/jfs # mount it\n```\n\n## Test\n\nUse the smallest target covering your change. Targets are in the `Makefile`\nand mirror CI (`.github/workflows/unittests.yml`).\n\n```sh\nmake test.meta.core          # ./pkg/meta/... core (no external services)\nmake test.meta.non-core      # Redis/PostgreSQL/etcd/KeyDB engine tests\nmake test.pkg                # all ./pkg/... except meta (-tags gluster)\nmake test.cmd                # ./cmd/... (needs MinIO env, runs under sudo)\nmake test.fdb                # FoundationDB tests (-tags fdb)\n```\n\n| Change scope       | Run                                                               |\n| ------------------ | ----------------------------------------------------------------- |\n| `pkg/meta/**`      | `make test.meta.core` (+ `test.meta.non-core` if engine-specific) |\n| `cmd/**`           | `make test.cmd`                                                   |\n| any other `pkg/**` | `make test.pkg`                                                   |\n\n- When fixing a bug, add a regression test that fails before the fix and passes after.\n- Group new test cases for the same module/category together; extend an existing test\n  rather than scattering new cases.\n\n## Lint & format\n\n- Run `go fmt` before committing.\n- Linting uses `golangci-lint` per `.golangci.yml`; pre-commit pins v1.52.2 and CI runs v2.6 (see `.github/workflows/verify.yml`).\n- Install hooks once with `pre-commit install` (config in `.pre-commit-config.yaml`).\n\n## Code style & license header\n\n- Follow [Effective Go](https://go.dev/doc/effective_go) and\n  [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments).\n- Prefer self-explanatory code over redundant comments; keep necessary comments concise.\n- Every new `.go` file MUST start with the Apache 2.0 header (see `main.go` for the canonical template).\n\n## Version compatibility\n\n- Persistent metadata or serialization changes in `pkg/meta/{interface,redis,sql,tkv}.go`\n  must remain readable by new clients, and old clients must not silently drop new\n  fields when rewriting records.\n- When metadata fields change, review `pkg/meta/{dump,backup}.go`, `pkg/meta/*_bak.go`,\n  and `pb/backup.proto`. Released dump/load formats must remain readable; tolerate\n  unknown fields where feasible, reject unsupported formats explicitly, and never\n  silently lose correctness-critical data.\n- Evaluate mixed-version behavior for metadata features or semantic changes. If\n  unsafe, raise (never lower) `MinClientVersion` and enable the feature only after\n  old clients have exited.\n- FUSE option changes must preserve existing names and defaults. Review graceful\n  restart, `FuseOptions`, `StripOptions`, and old-config normalization in\n  `cmd/mount_unix.go`, `pkg/vfs/vfs.go`, and `pkg/fuse/fuse.go`.\n- Add compatibility tests, or explicitly report missing coverage during review.\n\n## Agent boundaries\n\n- Correctness first: this is a distributed file system; small changes can affect data\n  integrity. Do not invent APIs, defaults, or behavior — verify against the code, and\n  don't bypass safety checks.\n- Metadata-engine parity: a semantic change in `pkg/meta/` must behave identically\n  across all three families (Redis, SQL/DB, KV) and be covered by their shared tests.\n- Behavior changes need matching unit tests; user-facing changes update the docs.\n- Keep issues and pr comments concise: state the problem clearly and avoid lengthy exposition.\n- Keep PRs minimal and focused on the current task; avoid unrelated features,\n  refactors, or formatting-only churn.\n- Do not hand-edit generated code or vendored dependencies.\n- Match existing conventions in the file you are editing.\n- Confirm before destructive or hard-to-reverse actions (deleting files, force pushes,\n  schema/data changes).\n","isInternal":false,"tokens":1388,"sizeBytes":6031},{"name":"SKILL.md","path":".agents/skills/review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/juicedata/juicefs/HEAD/.agents/skills/review/SKILL.md","title":"review","category":"anthropic-skill","format":"markdown","content":"---\nname: review\ndescription: \"Perform evidence-based reviews of PRs, commits, patches, files, issue fixes, designs, or implementation plans. Use for code review, risk and compatibility analysis, test coverage review, and verifying reported bugs or requirements before evaluating a change.\"\nargument-hint: \"[PR | diff | commit | issue | files]\"\nuser-invocable: true\n---\n\n# Review\n\nReview changes for correctness and actionable risk. Verify claims against primary evidence before judging the implementation. Use Chinese when communicating with users.\n\n## Principles\n\n1. **Verify the background**: establish the concrete problem, trigger conditions, affected behavior, and whether the problem is real.\n2. **Prefer primary evidence**: rely on code paths, tests, command output, specifications, official documentation, and first-party project documentation.\n3. **Separate facts from inferences**: label uncertainty and state what evidence is missing.\n4. **Report actionable issues**: explain concrete impact and a recommended action; skip automated formatting/lint concerns and personal preferences unless they expose real risk.\n5. **Respect project context**: follow applicable repository instructions and existing architecture, naming, error handling, logging, and test conventions. Do not request unrelated refactors.\n6. **Review by default**: do not modify code unless the user explicitly asks for fixes.\n\n## Workflow\n\n### 1. Establish Scope and Background\n\n- Identify the target: PR, branch diff, commit, issue, files, or code snippet. Clarify only material ambiguity; do not expand the scope without reason.\n- For remote PRs or issues, use available repository or GitHub tooling to inspect the description, comments, linked items, checks, history, and diff.\n- Unless a PR is small and self-explanatory, require the PR description or a linked issue to explain its background and motivation. If that context is missing, ask the author to add it rather than inferring the rationale solely from the diff.\n- Determine the claimed problem, trigger conditions, affected users, and visible behavior. Do not treat the PR or issue description as proof.\n- Verify the claim through code paths, tests, logs, existing behavior, history, or documentation. For external behavior, prefer official or first-party sources and cite the evidence. State anything that remains unverified.\n\n### 2. Review the Approach\n\nCheck whether the change:\n\n- Addresses the root cause rather than masking a symptom.\n- Covers main paths, boundary conditions, error paths, failure modes, compatibility, migration, and rollback where relevant.\n- Fits existing abstractions without bypassing helpers, validation, locking, transactions, permission checks, or safety mechanisms.\n- Avoids unnecessary behavior changes and documents intentional user-facing changes.\n\n### 3. Review Implementation and Tests\n\nEvaluate the relevant dimensions:\n\n- **Correctness and reliability**: logic, edge cases, error propagation, races, nil/bounds errors, resource leaks, transaction consistency, and recovery.\n- **Simplicity and consistency**: directness, duplication, hidden side effects, existing helpers and patterns, and language conventions.\n- **Performance**: avoidable I/O, lock contention, full scans, repeated network calls, memory amplification, and hot-path overhead.\n- **Security**: permissions, authentication, path and input handling, sensitive data, data integrity, and recoverability.\n- **Compatibility**: APIs, CLIs, configuration, serialized formats, cross-version behavior, and backend parity.\n- **Tests**: reproduction of the original problem, fixed behavior, boundaries, errors, concurrency, compatibility, and backend-specific paths. Check that tests are stable, minimal, readable, and use the smallest relevant commands. If tests were not run, explain why and recommend them.\n- **JuiceFS**: apply `AGENTS.md`, especially its requirements for POSIX semantics, data integrity, metadata-engine parity, dump/load and mixed-version compatibility, object-storage behavior, concurrency, and failure recovery.\n\n### 4. Report the Review\n\nUse the following three top-level sections, in this order. This gives the reader enough context to understand the review before presenting defects and risks.\n\n```markdown\n## Summary\n\n## Solution\n\n## Findings\n```\n\nIn **Summary**:\n\n- Summarize the reported problem, relevant background, trigger conditions, affected users or behavior, and expected behavior.\n- State the verified root cause when the evidence supports one. Clearly distinguish verified facts from claims, assumptions, and unknowns.\n- Keep this section concise and focused on the context needed to evaluate the change.\n\nIn **Solution**:\n\n- Explain the implemented or proposed solution, its key mechanism, and the main code paths or components it changes.\n- Describe why the approach addresses the problem, plus important compatibility, migration, performance, security, or design tradeoffs when relevant.\n- Summarize the approach rather than narrating the diff file by file. Do not present the solution as correct before completing the review.\n\nIn **Findings**:\n\n- List actionable findings ordered by severity. Each finding should use this structure:\n\n```markdown\n### [Severity] Title\n\n- Location: `path:line`\n- Problem: ...\n- Impact: ...\n- Evidence: ...\n- Recommendation: ...\n```\n\n- After the individual findings, include assumptions or unknowns, tests run or not run, remaining risks, and a verdict when supported by sufficient evidence: Approve, Request changes, Comment only, or Need more information. Keep this supporting review context within the **Findings** section instead of creating additional top-level sections.\n\n- If there are no findings, say so explicitly under **Findings**, then identify what was checked and what remains unverified.\n\n## Severity\n\n- **Critical**: likely data loss or corruption, permission bypass, security vulnerability, severe outage, or unrecoverable incompatibility.\n- **High**: likely real-world wrong behavior, crash, major performance regression, or key feature regression.\n- **Medium**: edge-case defect, compatibility risk, or test gap that may hide a real regression.\n- **Low**: minor, non-blocking risk or maintainability issue; do not report pure style preferences.\n","frontmatter":{"name":"review","description":"Perform evidence-based reviews of PRs, commits, patches, files, issue fixes, designs, or implementation plans. Use for code review, risk and compatibility analysis, test coverage review, and verifying reported bugs or requirements before evaluating a change.","argument-hint":"[PR | diff | commit | issue | files]","user-invocable":true},"isInternal":false,"tokens":1228,"sizeBytes":6271}],"systemPromptSnippet":"<yakaai_skills repo=\"juicedata/juicefs\">\n<!-- File: AGENTS.md (Tokens: ~1388 | Category: root-instruction) -->\n# AGENTS.md\n\nJuiceFS is a POSIX-compatible distributed file system written in Go\n(`module github.com/juicedata/juicefs`). A client coordinates a **metadata engine**\nand **object storage**, exposing POSIX (FUSE) and an S3 gateway, plus Java/Hadoop\n(`sdk/java/`) and Python (`sdk/python/`) SDKs.\n\nMetadata engine families under `pkg/meta/`:\n\n- **Redis** — `redisMeta` (`redis.go`); also KeyDB.\n- **SQL/DB** — `dbMeta` (`sql.go`): MySQL, PostgreSQL, SQLite.\n- **KV (TKV)** — `kvMeta` (`tkv.go`): TiKV, etcd, BadgerDB, FoundationDB.\n\n## Repository map\n\nEntry points: `main.go` (root) and `cmd/main.go` (CLI commands live in `cmd/`).\n\n| Path           | Responsibility                                                  |\n| -------------- | --------------------------------------------------------------- |\n| `cmd/`         | CLI subcommands (`mount`, `gateway`, `sync`, `format`, `gc`, …) |\n| `pkg/meta/`    | Metadata engine abstraction + per-engine implementations        |\n| `pkg/vfs/`     | Virtual filesystem layer (POSIX semantics)                      |\n| `pkg/fuse/`    | FUSE bindings (Linux/macOS); `pkg/winfsp/` for Windows          |\n| `pkg/fs/`      | High-level filesystem logic                                     |\n| `pkg/chunk/`   | Chunk / slice / block data management and caching               |\n| `pkg/object/`  | Object storage backend abstraction                              |\n| `pkg/gateway/` | S3-compatible gateway                                           |\n| `pkg/sync/`    | Data synchronization (`juicefs sync`)                           |\n| `pkg/acl/`     | POSIX ACL support                                               |\n| `docs/`        | Documentation: `docs/en/` (English), `docs/zh_cn/` (Chinese)    |\n\n## Build\n\n```sh\nmake juicefs                 # standard build -> ./juicefs\nSTATIC=1 make juicefs        # static binary (needs musl-gcc)\nmake BUILD=debug all         # debug build (-N -l)\nmake juicefs.lite            # minimal build, most backends disabled\nmake juicefs.ceph            # -tags ceph\nmake juicefs.fdb             # -tags fdb (FoundationDB)\n```\n\nLocal volume for manual testing (SQLite metadata):\n\n```sh\n./juicefs format sqlite3://test.db myjfs    # create a volume\n./juicefs mount  sqlite3://test.db /tmp/jfs # mount it\n```\n\n## Test\n\nUse the smallest target covering your change. Targets are in the `Makefile`\nand mirror CI (`.github/workflows/unittests.yml`).\n\n```sh\nmake test.meta.core          # ./pkg/meta/... core (no external services)\nmake test.meta.non-core      # Redis/PostgreSQL/etcd/KeyDB engine tests\nmake test.pkg                # all ./pkg/... except meta (-tags gluster)\nmake test.cmd                # ./cmd/... (needs MinIO env, runs under sudo)\nmake test.fdb                # FoundationDB tests (-tags fdb)\n```\n\n| Change scope       | Run                                                               |\n| ------------------ | ----------------------------------------------------------------- |\n| `pkg/meta/**`      | `make test.meta.core` (+ `test.meta.non-core` if engine-specific) |\n| `cmd/**`           | `make test.cmd`                                                   |\n| any other `pkg/**` | `make test.pkg`                                                   |\n\n- When fixing a bug, add a regression test that fails before the fix and passes after.\n- Group new test cases for the same module/category together; extend an existing test\n  rather than scattering new cases.\n\n## Lint & format\n\n- Run `go fmt` before committing.\n- Linting uses `golangci-lint` per `.golangci.yml`; pre-commit pins v1.52.2 and CI runs v2.6 (see `.github/workflows/verify.yml`).\n- Install hooks once with `pre-commit install` (config in `.pre-commit-config.yaml`).\n\n## Code style & license header\n\n- Follow [Effective Go](https://go.dev/doc/effective_go) and\n  [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments).\n- Prefer self-explanatory code over redundant comments; keep necessary comments concise.\n- Every new `.go` file MUST start with the Apache 2.0 header (see `main.go` for the canonical template).\n\n## Version compatibility\n\n- Persistent metadata or serialization changes in `pkg/meta/{interface,redis,sql,tkv}.go`\n  must remain readable by new clients, and old clients must not silently drop new\n  fields when rewriting records.\n- When metadata fields change, review `pkg/meta/{dump,backup}.go`, `pkg/meta/*_bak.go`,\n  and `pb/backup.proto`. Released dump/load formats must remain readable; tolerate\n  unknown fields where feasible, reject unsupported formats explicitly, and never\n  silently lose correctness-critical data.\n- Evaluate mixed-version behavior for metadata features or semantic changes. If\n  unsafe, raise (never lower) `MinClientVersion` and enable the feature only after\n  old clients have exited.\n- FUSE option changes must preserve existing names and defaults. Review graceful\n  restart, `FuseOptions`, `StripOptions`, and old-config normalization in\n  `cmd/mount_unix.go`, `pkg/vfs/vfs.go`, and `pkg/fuse/fuse.go`.\n- Add compatibility tests, or explicitly report missing coverage during review.\n\n## Agent boundaries\n\n- Correctness first: this is a distributed file system; small changes can affect data\n  integrity. Do not invent APIs, defaults, or behavior — verify against the code, and\n  don't bypass safety checks.\n- Metadata-engine parity: a semantic change in `pkg/meta/` must behave identically\n  across all three families (Redis, SQL/DB, KV) and be covered by their shared tests.\n- Behavior changes need matching unit tests; user-facing changes update the docs.\n- Keep issues and pr comments concise: state the problem clearly and avoid lengthy exposition.\n- Keep PRs minimal and focused on the current task; avoid unrelated features,\n  refactors, or formatting-only churn.\n- Do not hand-edit generated code or vendored dependencies.\n- Match existing conventions in the file you are editing.\n- Confirm before destructive or hard-to-reverse actions (deleting files, force pushes,\n  schema/data changes).\n\n<!-- File: .agents/skills/review/SKILL.md (Tokens: ~1228 | Category: anthropic-skill) -->\n---\nname: review\ndescription: \"Perform evidence-based reviews of PRs, commits, patches, files, issue fixes, designs, or implementation plans. Use for code review, risk and compatibility analysis, test coverage review, and verifying reported bugs or requirements before evaluating a change.\"\nargument-hint: \"[PR | diff | commit | issue | files]\"\nuser-invocable: true\n---\n\n# Review\n\nReview changes for correctness and actionable risk. Verify claims against primary evidence before judging the implementation. Use Chinese when communicating with users.\n\n## Principles\n\n1. **Verify the background**: establish the concrete problem, trigger conditions, affected behavior, and whether the problem is real.\n2. **Prefer primary evidence**: rely on code paths, tests, command output, specifications, official documentation, and first-party project documentation.\n3. **Separate facts from inferences**: label uncertainty and state what evidence is missing.\n4. **Report actionable issues**: explain concrete impact and a recommended action; skip automated formatting/lint concerns and personal preferences unless they expose real risk.\n5. **Respect project context**: follow applicable repository instructions and existing architecture, naming, error handling, logging, and test conventions. Do not request unrelated refactors.\n6. **Review by default**: do not modify code unless the user explicitly asks for fixes.\n\n## Workflow\n\n### 1. Establish Scope and Background\n\n- Identify the target: PR, branch diff, commit, issue, files, or code snippet. Clarify only material ambiguity; do not expand the scope without reason.\n- For remote PRs or issues, use available repository or GitHub tooling to inspect the description, comments, linked items, checks, history, and diff.\n- Unless a PR is small and self-explanatory, require the PR description or a linked issue to explain its background and motivation. If that context is missing, ask the author to add it rather than inferring the rationale solely from the diff.\n- Determine the claimed problem, trigger conditions, affected users, and visible behavior. Do not treat the PR or issue description as proof.\n- Verify the claim through code paths, tests, logs, existing behavior, history, or documentation. For external behavior, prefer official or first-party sources and cite the evidence. State anything that remains unverified.\n\n### 2. Review the Approach\n\nCheck whether the change:\n\n- Addresses the root cause rather than masking a symptom.\n- Covers main paths, boundary conditions, error paths, failure modes, compatibility, migration, and rollback where relevant.\n- Fits existing abstractions without bypassing helpers, validation, locking, transactions, permission checks, or safety mechanisms.\n- Avoids unnecessary behavior changes and documents intentional user-facing changes.\n\n### 3. Review Implementation and Tests\n\nEvaluate the relevant dimensions:\n\n- **Correctness and reliability**: logic, edge cases, error propagation, races, nil/bounds errors, resource leaks, transaction consistency, and recovery.\n- **Simplicity and consistency**: directness, duplication, hidden side effects, existing helpers and patterns, and language conventions.\n- **Performance**: avoidable I/O, lock contention, full scans, repeated network calls, memory amplification, and hot-path overhead.\n- **Security**: permissions, authentication, path and input handling, sensitive data, data integrity, and recoverability.\n- **Compatibility**: APIs, CLIs, configuration, serialized formats, cross-version behavior, and backend parity.\n- **Tests**: reproduction of the original problem, fixed behavior, boundaries, errors, concurrency, compatibility, and backend-specific paths. Check that tests are stable, minimal, readable, and use the smallest relevant commands. If tests were not run, explain why and recommend them.\n- **JuiceFS**: apply `AGENTS.md`, especially its requirements for POSIX semantics, data integrity, metadata-engine parity, dump/load and mixed-version compatibility, object-storage behavior, concurrency, and failure recovery.\n\n### 4. Report the Review\n\nUse the following three top-level sections, in this order. This gives the reader enough context to understand the review before presenting defects and risks.\n\n```markdown\n## Summary\n\n## Solution\n\n## Findings\n```\n\nIn **Summary**:\n\n- Summarize the reported problem, relevant background, trigger conditions, affected users or behavior, and expected behavior.\n- State the verified root cause when the evidence supports one. Clearly distinguish verified facts from claims, assumptions, and unknowns.\n- Keep this section concise and focused on the context needed to evaluate the change.\n\nIn **Solution**:\n\n- Explain the implemented or proposed solution, its key mechanism, and the main code paths or components it changes.\n- Describe why the approach addresses the problem, plus important compatibility, migration, performance, security, or design tradeoffs when relevant.\n- Summarize the approach rather than narrating the diff file by file. Do not present the solution as correct before completing the review.\n\nIn **Findings**:\n\n- List actionable findings ordered by severity. Each finding should use this structure:\n\n```markdown\n### [Severity] Title\n\n- Location: `path:line`\n- Problem: ...\n- Impact: ...\n- Evidence: ...\n- Recommendation: ...\n```\n\n- After the individual findings, include assumptions or unknowns, tests run or not run, remaining risks, and a verdict when supported by sufficient evidence: Approve, Request changes, Comment only, or Need more information. Keep this supporting review context within the **Findings** section instead of creating additional top-level sections.\n\n- If there are no findings, say so explicitly under **Findings**, then identify what was checked and what remains unverified.\n\n## Severity\n\n- **Critical**: likely data loss or corruption, permission bypass, security vulnerability, severe outage, or unrecoverable incompatibility.\n- **High**: likely real-world wrong behavior, crash, major performance regression, or key feature regression.\n- **Medium**: edge-case defect, compatibility risk, or test gap that may hide a real regression.\n- **Low**: minor, non-blocking risk or maintainability issue; do not report pure style preferences.\n</yakaai_skills>"}