fft-debug

Engineering Community

Repo stars 0
Author repo nano-core

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Diagnose and resolve FFT_nano runtime issues across container execution, provider credentials, Telegram/WhatsApp routing, schedu…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “When to use this skill”, “When not to use this skill”, “Guardrails”, “Fast Triage”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name fft-debug directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “When to use this skill / When not to use this skill / Guardrails” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

FFT Debug

Use this skill for incident triage and deterministic debugging of FFT_nano host and container paths.

When to use this skill

Use when runtime behavior is failing, degraded, or inconsistent.
Use when investigating provider wiring, routing, logs, or IPC state.
Use when producing reproducible triage output before any fix attempt.

When not to use this skill

Do not use as the default path for normal feature work.
Do not use when the request is purely product behavior, not incident/debug.
Do not use to justify destructive cleanup without explicit approval.

Guardrails

Never use destructive git commands unless explicitly requested.
Preserve unrelated worktree changes.
Keep admin/coder controls in main chat only; do not bypass main-chat restrictions.

Fast Triage

Confirm single instance lock:
- ls -la data/fft_nano.lock
Check startup/runtime logs:
- tail -n 200 logs/fft_nano.log
- tail -n 200 logs/fft_nano.error.log
Check per-group container logs:
- ls -la groups/<group>/logs
- tail -n 200 groups/<group>/logs/*
Inspect registration + IPC state:
- cat data/registered_groups.json
- find data/ipc -maxdepth 3 -type f

Common Failure Modes

Provider key missing: Pi reports no models available.
Wrong PI_API/PI_MODEL: model/provider not found.
Multiple bot instances: Telegram getUpdates conflict.
Docker daemon unavailable or runtime permission issues.

Recommended Debug Commands

Build/runtime checks:
- npm run typecheck
- npm test
Dry-run routing check (no live model call):
- FFT_NANO_DRY_RUN=1 ./scripts/start.sh dev telegram-only
Runtime detail logging:
- LOG_LEVEL=debug ./scripts/start.sh dev telegram-only

Telegram Debug Path

Verify bot token present at runtime.
In bot DM: /id, /status, /help.
Admin checks in main chat only: /tasks, /groups, /panel, /coder, /coder-plan.
If /main <secret> fails, verify TELEGRAM_ADMIN_SECRET and restart.

Container Runtime Debug

Docker runtime:
- docker info
- docker ps
Host runtime (unisolated):
- verify explicit flags: CONTAINER_RUNTIME=host, FFT_NANO_ALLOW_HOST_RUNTIME=1

Database/State Debug

SQLite file location: store/messages.db
Router state: data/router_state.json
Group registry: data/registered_groups.json
Per-group Pi state: data/pi/<group>/.pi/

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: Engineering
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 88 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @0-CYBERDYNE-SYSTEMS-0 · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Guided setup
External API key: No requirement detected
Detected OS requirements: Docker
Runtime requirements: Docker
Detected file/system behavior: Read-only
Write / modify
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview fft-debug.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

# FFT Debug

Use this skill for incident triage and deterministic debugging of FFT_nano host and container paths.

## When to use this skill

- Use when runtime behavior is failing, degraded, or inconsistent.
- Use when investigating provider wiring, routing, logs, or IPC state.
- Use when producing reproducible triage output before any fix attempt.

## When not to use this skill

- Do not use as the default path for normal feature work.
- Do not use when the request is purely product behavior, not incident/debug.
- Do not use to justify destructive cleanup without explicit approval.

## Guardrails

- Never use destructive git commands unless explicitly requested.
- Preserve unrelated worktree changes.
- Keep admin/coder controls in main chat only; do not bypass main-chat restrictions.

## Fast Triage

1. Confirm single instance lock:
   - `ls -la data/fft_nano.lock`
2. Check startup/runtime logs:
   - `tail -n 200 logs/fft_nano.log`
   - `tail -n 200 logs/fft_nano.error.log`
3. Check per-group container logs:
   - `ls -la groups/<group>/logs`
   - `tail -n 200 groups/<group>/logs/*`
4. Inspect registration + IPC state:
   - `cat data/registered_groups.json`
   - `find data/ipc -maxdepth 3 -type f`

## Common Failure Modes

- Provider key missing: Pi reports no models available.
- Wrong `PI_API`/`PI_MODEL`: model/provider not found.
- Multiple bot instances: Telegram getUpdates conflict.
- Docker daemon unavailable or runtime permission issues.

## Recommended Debug Commands

- Build/runtime checks:
  - `npm run typecheck`
  - `npm test`
- Dry-run routing check (no live model call):
  - `FFT_NANO_DRY_RUN=1 ./scripts/start.sh dev telegram-only`
- Runtime detail logging:
  - `LOG_LEVEL=debug ./scripts/start.sh dev telegram-only`

## Telegram Debug Path

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> When to use this skill → When not to use this skill → Guardrails → Fast Triage → Common Failure Modes → Recommended Debug Commands
terms    -> Use this skill for incident triage and deterministic debugging of FFTnano host and container paths. · - Use when runtime behavior is failing, degraded, or inconsistent. · - Do not use as the default path for normal feature work. · - Never use destructive git commands unless explicitly requested. · 1. Confirm single instance lock: - ls -la data/fftnano.lock 2. · - Provider key missing: Pi reports no models available. · - Verify bot token present at runtime.
files/cmd -> ls -la data/fftnano.lock · tail -n 200 logs/fftnano.log · tail -n 200 logs/fftnano.error.log · ls -la groups/<group>/logs · tail -n 200 groups/<group>/logs/ · cat data/registeredgroups.json · find data/ipc -maxdepth 3 -type f · PIAPI
body sha256 -> 1aefc08d3f0c