diff --git a/.agents/skills/discrawl/SKILL.md b/.agents/skills/discrawl/SKILL.md index b59ab3af65b..52855babcf8 100644 --- a/.agents/skills/discrawl/SKILL.md +++ b/.agents/skills/discrawl/SKILL.md @@ -1,6 +1,6 @@ --- name: discrawl -description: "Discord archive: search, sync freshness, DMs, channel slices, SQL counts, and Discrawl repo work." +description: "Discord archive: search, sync freshness, DMs, summaries, TUI, repo/release work." metadata: openclaw: homepage: https://github.com/openclaw/discrawl @@ -16,29 +16,154 @@ metadata: # Discrawl -Use local Discord archive data before live Discord APIs. Check freshness for recent/current questions: +Use local Discord archive data first for Discord questions. Hit Discord APIs +only when the archive is stale, missing the requested scope, or the user asks +for current external context. + +## Sources + +- DB: platform-native XDG data dir, usually + `${XDG_DATA_HOME:-~/.local/share}/discrawl/discrawl.db` on Linux or + `~/Library/Application Support/discrawl/discrawl.db` on macOS +- Config: platform-native XDG config dir, with legacy fallback to + `~/.discrawl/config.toml` +- Cache: platform-native XDG cache dir +- Logs: platform-native XDG state dir +- Git share repo: platform-native XDG data dir +- Repo: `openclaw/discrawl`; use `~/GIT/_Perso/discrawl` only after verifying + its remote targets `openclaw/discrawl`, otherwise use a fresh checkout +- Preferred CLI: `discrawl`; fallback to `go run ./cmd/discrawl` from the repo + if the installed binary is stale + +## Freshness + +For recent/current questions, check freshness before analysis: ```bash discrawl status --json +``` + +For precise freshness from the default database: + +```bash +# Discrawl uses macOS ~/Library defaults unless XDG_DATA_HOME is explicitly set. +case "$(uname -s)" in + Darwin) + db="$HOME/Library/Application Support/discrawl/discrawl.db" + ;; + *) + db="${XDG_DATA_HOME:-$HOME/.local/share}/discrawl/discrawl.db" + ;; +esac +sqlite3 "$db" \ + "select coalesce(max(updated_at),'') from sync_state where scope like 'channel:%';" +``` + +Routine diagnostics: + +```bash discrawl doctor ``` -Refresh only when stale or asked: +Desktop-local refresh: ```bash discrawl sync --source wiretap +``` + +Bot API latest refresh, when credentials are available: + +```bash discrawl sync ``` -Query with bounded slices: +Use `--full` only for deliberate historical backfills: + +```bash +discrawl sync --full +``` + +If SQLite reports busy/locked, check for stray `discrawl` processes before retrying. + +## Query Workflow + +1. Resolve scope: guild, channel, DM, author, keyword, date range. +2. Check freshness for recent/current requests. +3. Prefer CLI search/messages for slices; use read-only SQL for exact counts. +4. Report absolute date spans, counts, channel/DM names, and known gaps. + +Use root or subcommand help for syntax: `discrawl --help`, +`discrawl help search`, `discrawl search --help`. Use +`DISCRAWL_NO_AUTO_UPDATE=1` for read smokes when you do not want git-share +updates. + +Common commands: ```bash DISCRAWL_NO_AUTO_UPDATE=1 discrawl search --limit 20 "query" discrawl messages --channel '#maintainers' --days 7 --all discrawl dms --last 20 +discrawl tui --dm DISCRAWL_NO_AUTO_UPDATE=1 discrawl --json sql "select count(*) from messages;" ``` -Report absolute date spans, channel/DM names, counts, and known gaps. Use read-only SQL for exact counts/rankings. Never use `--unsafe --confirm` unless the user explicitly requests a reviewed DB mutation. +## SQL -Boundaries: bot sync needs configured Discord bot credentials. Wiretap reads local Discord Desktop artifacts only; do not extract user tokens, call Discord as the user, or write to Discord storage. Git-share snapshots must not include secrets or `@me` DM rows. +Use `discrawl sql` for exact counts, joins, and ranking queries when normal +CLI reads are too coarse. The command is read-only by default, accepts SQL as +args or stdin, and supports `--json` for agent parsing. + +Useful examples: + +```bash +DISCRAWL_NO_AUTO_UPDATE=1 discrawl --json sql "select count(*) as messages from messages;" +DISCRAWL_NO_AUTO_UPDATE=1 discrawl --json sql "select coalesce(nullif(c.name, ''), m.channel_id) as channel, count(*) as messages from messages m left join channels c on c.id = m.channel_id group by m.channel_id order by messages desc limit 20;" +DISCRAWL_NO_AUTO_UPDATE=1 discrawl --json sql "select coalesce(nullif(mm.display_name, ''), nullif(mm.global_name, ''), nullif(mm.username, ''), m.author_id) as author, count(*) as messages from messages m left join members mm on mm.guild_id = m.guild_id and mm.user_id = m.author_id group by m.guild_id, m.author_id order by messages desc limit 20;" +``` + +Never use `--unsafe --confirm` unless the user explicitly asks for a database +mutation and the write has been reviewed. + +When the installed CLI lacks a new feature, build or run from a verified +`openclaw/discrawl` checkout before concluding the feature is missing. + +## Discord Boundaries + +Bot API sync requires configured Discord bot credentials; do not invent token +availability. Desktop wiretap mode reads local Discord Desktop artifacts and +must not extract credentials, use user tokens, call Discord as the user, or +write to Discord application storage. Wiretap/Desktop cache DMs are local-only +and must not be described as part of the published Git snapshot. Git-share +snapshots must not include secrets or `@me` DM rows. + +## Verification + +For repo edits, prefer existing Go gates: + +```bash +GOWORK=off go test ./... +``` + +Then run targeted CLI smoke for the touched surface, for example: + +```bash +discrawl doctor +discrawl status --json +DISCRAWL_NO_AUTO_UPDATE=1 discrawl search --limit 5 "test" +``` + +## ClawSweeper Sandbox + +Use the sandbox reader only: + +```bash +discrawl-sandbox search --limit 20 "query" +discrawl-sandbox messages --channel clawtributors --days 7 --all +discrawl-sandbox status --json +``` + +This reader imports `https://github.com/openclaw/discord-store.git` into +`/root/clawsweeper-sandbox-workspace/.discrawl/discrawl.db` with +`discord.token_source = "none"`. The published Git snapshot is public-channel +filtered; do not use `/root/.discrawl/config.toml` or the rich writer DB from +sandboxed public Discord sessions.