开源项目模板

问题报告

github/ISSUE_TEMPLATE/bug_report.md

---
name: Bug Report
about: Report something that is broken or behaving incorrectly
title: '[Bug] '
labels: ['bug', 'triage']
assignees: []
---

## Summary

A clear, one-sentence description of what is broken.

## Environment

- Project version: (e.g. `v0.1.1`, commit hash, or `main` branch)
- Operating system:
- Runtime version (Node.js / Rust):
- Installation method (`npm ci` / `cargo install` / release archive):

## Steps to Reproduce

1. …
2. …
3. …

## Expected Behavior

What you expected to happen.

## Actual Behavior

What actually happened, including any error messages.

```
<paste full error output here>
```

## Isolation

- [ ] I can reproduce this with a minimal example
- [ ] I checked the existing issues for duplicates
- [ ] I checked the FAQ / troubleshooting guide (if available)

## Impact

How severe is this issue? Check one:

- [ ] Blocker — I cannot use the tool at all
- [ ] Major — A core feature is broken
- [ ] Minor — A workaround exists
- [ ] Cosmetic — Only affects output appearance

## Acceptance Criteria

What change would resolve this issue for you?

## Additional Context

Screenshots, logs, links to related issues, or any other helpful context.

Pull Request

github/PULL_REQUEST_TEMPLATE.md

## Summary

<!-- One or two sentences describing what this PR changes and why. -->

## Linked Issues

<!-- Link any related issues: "Fixes #123" or "Relates to #456". -->

Fixes #

## Type of Change

<!-- Check all that apply. -->

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [ ] Documentation update
- [ ] Refactor (no functional change)
- [ ] Performance improvement
- [ ] Test addition or improvement
- [ ] Build / CI / tooling change

## Design

<!-- If the change is non-trivial, briefly explain the design. -->
<!-- For larger changes, link to an ADR or design document. -->

## Compatibility

- [ ] Backwards compatible — Existing users need no action
- [ ] Breaking change — Migration notes added below

### Migration Notes (if breaking)

<!-- What users must do to upgrade. -->

## Testing

<!-- Check all that apply. -->

- [ ] I added unit tests that prove my fix / feature works
- [ ] I added integration tests for cross-module behavior
- [ ] I ran the existing test suite locally — all tests pass
- [ ] I added a fixture or example under `fixtures/` / `examples/`

### Test Commands

```bash
npm test
npm run verify
```

## Checklist

- [ ] I read [`CONTRIBUTING.md`](../../CONTRIBUTING.md)
- [ ] I followed the project's code style (lint / format)
- [ ] I updated relevant documentation
- [ ] I considered adding an ADR for non-trivial design decisions
- [ ] I considered updating `CHANGELOG.md`

## Screenshots / Recordings

<!-- Optional: visual changes, terminal output, or before/after comparisons. -->

## Additional Context

Anything else reviewers should know.

持续集成

github/workflows/ci.yml

name: CI

on:
  push:
    branches: [main, release/*]
  pull_request:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  static-analysis:
    name: Static Analysis
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        if: hashFiles('package-lock.json') != ''
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Setup Rust
        if: hashFiles('Cargo.lock') != ''
        uses: dtolnay/rust-toolchain@stable

      - name: Install dependencies (Node)
        if: hashFiles('package-lock.json') != ''
        run: npm ci

      - name: Install dependencies (Rust)
        if: hashFiles('Cargo.lock') != ''
        run: cargo fetch --locked

      - name: Format check
        run: |
          if [ -f package.json ]; then npm run format:check; fi
          if [ -f Cargo.toml ]; then cargo fmt --all -- --check; fi

      - name: Lint
        run: |
          if [ -f package.json ]; then npm run lint; fi
          if [ -f Cargo.toml ]; then cargo clippy --all-targets --all-features -- -D warnings; fi

      - name: Type check
        if: hashFiles('package.json') != ''
        run: npm run typecheck

  unit-tests:
    name: Unit Tests
    runs-on: ${{ matrix.os }}
    timeout-minutes: 20
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        if: hashFiles('package-lock.json') != ''
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Setup Rust
        if: hashFiles('Cargo.lock') != ''
        uses: dtolnay/rust-toolchain@stable

      - name: Install dependencies (Node)
        if: hashFiles('package-lock.json') != ''
        run: npm ci

      - name: Run Node tests
        if: hashFiles('package.json') != ''
        run: npm test

      - name: Run Rust tests
        if: hashFiles('Cargo.toml') != ''
        run: cargo test --locked --all-features

      - name: Upload coverage (Node)
        if: hashFiles('package.json') != ''
        uses: actions/upload-artifact@v4
        with:
          name: coverage-node-${{ matrix.os }}
          path: coverage/
          if-no-files-found: ignore

  integration-tests:
    name: Integration Tests
    runs-on: ubuntu-latest
    timeout-minutes: 20
    needs: unit-tests
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Run integration / e2e tests
        run: npm run test:e2e || echo "No e2e tests configured"

  audit:
    name: Dependency Audit
    runs-on: ubuntu-latest
    timeout-minutes: 10
    continue-on-error: true
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        if: hashFiles('package-lock.json') != ''
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Audit Node dependencies
        if: hashFiles('package-lock.json') != ''
        run: npm audit --audit-level=high

      - name: Setup Rust
        if: hashFiles('Cargo.lock') != ''
        uses: dtolnay/rust-toolchain@stable

      - name: Audit Rust dependencies
        if: hashFiles('Cargo.lock') != ''
        uses: rustsec/audit-check@v2
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

项目路线图

docs/ROADMAP.md

# Roadmap

<!--
  This roadmap is a living document. It reflects current intentions, not
  commitments. Dates are estimates and may shift as we learn more.

  Status legend:
    🔵 exploring  — We're still investigating the approach
    🟡 designing  — We have a clear shape but the API may change
    🟢 building   — Implementation is in progress
    ✅ shipped    — Available in a tagged release
    ⏸️ paused    — Deferred to a later milestone
-->

> Last updated: YYYY-MM-DD

## Current Milestone: v0.2 — Production Readiness

Goal: Make the tool safe and convenient for everyday use by early adopters.

### Governance & CI

- [ ] 🔵 Migrate CI to GitHub Actions matrix (Linux + macOS)
- [ ] 🔵 Add Dependabot for npm + cargo
- [ ] 🔵 Add Issue + PR templates
- [ ] 🔵 First ADR series — record key design decisions
- [ ] 🔵 Public coverage badges in README

### Stability

- [ ] 🟡 Reproducible release artifacts with checksums
- [ ] 🟡 Optional GPG signing for releases
- [ ] 🟡 Recovery story — what to do when something fails mid-run

### Documentation

- [ ] 🟡 Platform compatibility matrix (Linux distros, macOS versions)
- [ ] 🟡 Troubleshooting playbook for common errors
- [ ] 🟡 Migration guide skeleton (for future v1.0 breaking changes)

## Next Milestone: v0.3 — Ecosystem

Goal: Make the tool fit naturally into other Agent Skill workflows.

### Integrations

- [ ] 🔵 Plugin protocol for custom exports (SkillTape)
- [ ] 🔵 Compatibility profile authoring guide (SkillSync)
- [ ] 🔵 Bidirectional integration story (SkillSync → SkillTape)

### Tooling

- [ ] 🔵 Editor integrations (LSP-style hints)
- [ ] 🔵 Optional remote Skill registry (read-only mirror)

## Future Milestone: v1.0 — Stable API

Goal: Promise a stable API surface, on-disk formats, and CLI grammar.

### Stability Promise

- [ ] 🔵 Lock public CLI grammar with snapshot tests
- [ ] 🔵 Version on-disk formats (Skill bundle, Receipt JSON)
- [ ] 🔵 SemVer policy published in `docs/semver.md`

### Community

- [ ] 🔵 Discussions categories for Q&A, ideas, show-and-tell
- [ ] 🔵 Public maintainer rotation policy
- [ ] 🔵 First contributor recognition batch

## Out of Scope (Won't Do)

These were considered and explicitly excluded:

- Becoming a general-purpose agent runtime
- A cloud-hosted verification service (we stay local-first)
- Auto-approving Skill execution under any circumstance
- Replacing Cargo / npm (we build on top, not parallel to)

## How to Influence This Roadmap

The fastest way to move an item up is one of:

1. Open an issue describing a real use case you're blocked on
2. Submit a PR with the implementation
3. Share an integration story (even if it didn't quite work)

We weigh "what unblocks real users" higher than "what would be cool."

故障排查

docs/TROUBLESHOOTING.md

# Troubleshooting Playbook

<!--
  This is the canonical "what to do when things go wrong" document.
  Keep entries short. Each one should let a user self-diagnose in under 5 minutes.
-->

> Last updated: YYYY-MM-DD

## "Permission denied" during Replay/Verify (Linux)

**Symptom:**

```
ERROR: bwrap failed: Permission denied
```

**Cause:** Your Linux distribution has user namespaces disabled.

**Fix:**

```bash
# Check current setting
sysctl kernel.unprivileged_userns_clone

# Enable it (Ubuntu 23.10+ / Fedora)
sudo sysctl -w kernel.unprivileged_userns_clone=1

# Make it persistent
echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-userns.conf
```

If your distribution doesn't support user namespaces at all (some container hosts, hardened servers), Replay/Verify cannot work. The other commands (Capture, Compile, Lint, Export) still work.

## "sandbox-exec not found" (macOS)

**Symptom:**

```
ERROR: /usr/bin/sandbox-exec: No such file or directory
```

**Cause:** You've installed a non-standard macOS that excludes `sandbox-exec`.

**Fix:** Reinstall from the official macOS installer, or use a different machine. SkillTape will not fall back to running without isolation.

## "SkillTape stops at the verify step with no error"

**Symptom:** The verify command exits with no output and the Receipt is never written.

**Cause:** Usually the `--receipt` path is on a network volume that doesn't support atomic writes.

**Fix:** Use a local path:

```bash
skilltape verify "$workspace/skill" --receipt "$workspace/receipt.json"
```

## "SkillSync reports 'fail' on a Skill that worked yesterday"

**Symptom:** Same Skill, same target, different result.

**Cause:** Either the Skill changed (even a whitespace change shifts the digest) or a new capability was added to the target Profile.

**Fix:**

```bash
# See what actually changed
skillsync diff --path ./skill --against ./skill-prev

# Re-read the target profile
skillsync compat --target codex --path ./skill --verbose
```

If the diff is intentional, regenerate the Receipt.

## "npm install fails on Windows"

**Symptom:** Native module rebuild fails with `gyp ERR! find Python`.

**Cause:** SkillSync has no native dependencies, but you may have a global install that does.

**Fix:**

```bash
npm config set msvs_version 2022
npm install --global @chumaniac/skillsync
```

## "Receipt hash doesn't match what I recorded"

**Symptom:** Re-running verify produces a different hash than the Receipt.

**Cause:** This is by design — the Receipt hash includes the Skill content hash plus the run environment. If either changes, the hash changes.

**Fix:** Treat Receipt as ephemeral evidence of a specific run. Don't compare Receipts across machines or after Skill edits.

## Getting More Help

- Search [existing issues](https://github.com/.../issues) first
- Run `skilltape doctor` or `skillsync check --env` and include the output
- Mention your OS version, runtime version, and the exact command

架构决策记录

adr/0000-template.md

# ADR-NNNN: Title

<!--
  Status: proposed | accepted | superseded | deprecated
  Date: YYYY-MM-DD
  Deciders: list of people involved in the decision
  Supersedes: ADR-NNNN (if this replaces a previous decision)
  Superseded by: ADR-NNNN (if a later decision supersedes this one)
-->

- **Status:** proposed
- **Date:** YYYY-MM-DD
- **Deciders:** @maintainer-handle

## Context and Problem Statement

<!--
  Describe the context and the problem statement in 2-3 sentences.
  What forces are at play? What constraints exist?
  Avoid describing the solution here.
-->

## Decision Drivers

<!--
  List the forces that influenced the decision:
  - Technical constraints
  - Project goals
  - User experience
  - Maintenance burden
  - Security implications
-->

- Driver 1
- Driver 2
- Driver 3

## Considered Options

<!--
  List the options considered. Each option should have a short description
  and a list of pros/cons. Include at least 2-3 options.
-->

### Option 1: Name

Description of the option.

**Pros:**

- Pro 1
- Pro 2

**Cons:**

- Con 1
- Con 2

### Option 2: Name

Description of the option.

**Pros:**

- Pro 1

**Cons:**

- Con 1
- Con 2

### Option 3: Name

Description of the option.

**Pros:**

- Pro 1

**Cons:**

- Con 1

## Decision Outcome

<!--
  State the chosen option and explain why. Include the consequences
  and trade-offs accepted by this decision.
-->

Chosen option: **Option X — Name**, because [reasoning].

### Consequences

**Positive:**

- Consequence 1
- Consequence 2

**Negative:**

- Consequence 1 (mitigation: ...)
- Consequence 2 (mitigation: ...)

**Neutral:**

- Consequence 1

### Confirmation

<!--
  How will we know that this decision was implemented correctly?
  Examples: code review, tests, metrics, runtime checks.
-->

- [ ] Implementation follows the agreed design
- [ ] Tests cover the new behavior
- [ ] Documentation reflects the decision
- [ ] No regressions in adjacent functionality

## Pros and Cons of the Options

<!--
  Optional: deeper analysis that doesn't fit in the table above.
  This section can grow over time as we learn from the decision.
-->

## More Information

<!--
  Links to related issues, PRs, design documents, or external references.
-->

- Related issue: #123
- Related PR: #456
- External reference: https://example.com/article

## Notes

<!--
  Free-form notes, observations, or follow-up actions.
-->