agentleFS
7xuanlu7xuanlu/wenlan/.claude/skills/run-wenlan/SKILL.md

run-wenlan

Skill358 starsChanged 4 months agoApache-2.0View on GitHub

Build, launch, and stop the wenlan daemon (wenlan-server) for local dev and verification. Use when asked to run or restart the daemon, or before driving any surface (HTTP, CLI, MCP) against a live instance.

  • Deletes or force-pushes

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never verify against the shared prod daemon on :7878 — dev and prod share the platform data dir by default.

    line 28
  2. Distinctive:

    NOT a substitute. It has two states where the question has three, and the state it cannot express is the dangerous one:

    line 85

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Run wenlan-server (dev)

Build: cargo build -p wenlan-server -p wenlan (add -p wenlan-mcp for the MCP bridge).

Ports — one allocation, no guessing

Three ports exist and they are not interchangeable. Stopping "the isolated daemon" on the wrong one leaves a live daemon behind and reports success.

PortOwnerNotes
7878the user's real daemonnever kill casually, never verify against
17878manual isolated instance (this skill)the recipes below
17881scripts/smoke-cli.shPORT= overrides
17882scripts/smoke-mcp.shPORT= overrides; runs alongside the CLI smoke

The smokes own their own ports so both can run at once. Do not repoint them at 17878 — a manual daemon and a smoke would then fight over one listener, and the smoke's ownership assertion would fail on a daemon it did not start.

Isolated instance (default for verification)

Never verify against the shared prod daemon on :7878 — dev and prod share the platform data dir by default. When WENLAN_DATA_DIR names any root other than the installed app's own, the default pages folder is $WENLAN_DATA_DIR/pages, and the daemon refuses to start if a knowledge_path points into the real ~/.wenlan/pages (or a custom pages folder in the real config). Builds older than that fix used the real ~/.wenlan/pages by default, so the recipe below still writes knowledge_path explicitly BEFORE the daemon starts. Then read the live value back from /api/knowledge/path and the Wenlan pages folder: startup log line. Use one absolute data dir for every command: on macOS the sandboxed and unsandboxed shells see different TMPDIRs, so a path derived from TMPDIR in one shell is a different folder in the other.

WENLAN_NO_AUTOSTART=1 belongs on every harness command: without it a failed connect starts the user's registered background service.

DATA_DIR="$(mktemp -d "${TMPDIR:-/tmp}/run.XXXXXX")"
mkdir -p "$DATA_DIR/pages"
printf '{"knowledge_path":"%s"}' "$DATA_DIR/pages" >"$DATA_DIR/config.json.tmp"
mv "$DATA_DIR/config.json.tmp" "$DATA_DIR/config.json"   # atomic, before spawn
WENLAN_NO_AUTOSTART=1 WENLAN_PORT=17878 WENLAN_DATA_DIR="$DATA_DIR" \
  ./target/debug/wenlan-server &
# ready:  curl -sf --max-time 2 http://127.0.0.1:17878/api/health  (poll up to ~120s)
# check:  curl -sf http://127.0.0.1:17878/api/knowledge/path   → must be $DATA_DIR/pages
# stop:   lsof -ti :17878 | xargs kill -9

Sandbox gotcha: always give mktemp a template ("${TMPDIR:-/tmp}/x.XXXXXX"); bare mktemp -d lands in a denied dir on macOS.

Windows (Git Bash) — the same instance, four differences

TMPDIR is unset, lsof is absent, $! is not the pid the OS knows the daemon by, and an MSYS path is not a path the native daemon can open. Each one fails quietly in a different way, so none of them is optional.

# 1. mktemp has no TMPDIR to fall back on: give it an explicit template.
DATA_DIR="$(mktemp -d "${TMPDIR:-/tmp}/run.XXXXXX")"
mkdir -p "$DATA_DIR/pages"

# 2. TWO variables, not one rewritten one. The shell keeps the MSYS spelling for
#    its own `rm -rf`; the daemon is handed the native spelling. `cygpath -m`
#    converts at the daemon boundary ONLY: /tmp/run.EiVYlp →
#    C:/Users/<you>/AppData/Local/Temp/run.EiVYlp
NATIVE_DATA_DIR="$(cygpath -m "$DATA_DIR")"
NATIVE_PAGES_DIR="$(cygpath -m "$DATA_DIR/pages")"
printf '{"knowledge_path":"%s"}' "$NATIVE_PAGES_DIR" >"$DATA_DIR/config.json.tmp"
mv "$DATA_DIR/config.json.tmp" "$DATA_DIR/config.json"

WENLAN_NO_AUTOSTART=1 WENLAN_PORT=17878 WENLAN_DATA_DIR="$NATIVE_DATA_DIR" \
  /c/wl-target/debug/wenlan-server.exe &
JOB_PID=$!   # an MSYS job pid — NOT the pid netstat and tasklist report

Listener check — source the library; do not hand-roll netstat. There is no lsof, and the obvious netstat -ano | awk ... $4=="LISTENING" one-liner is NOT a substitute. It has two states where the question has three, and the state it cannot express is the dangerous one:

  • netstat missing, killed, or exiting non-zero → no matching row → reads as free.
  • a non-English Windows → the State column says ABHOEREN, not LISTENING → no matching row → reads as free, with the port genuinely busy.
  • an unexpected or truncated table → no matching row → reads as free.

Starting a second daemon on a port nobody measured is how two daemons end up sharing one data directory. scripts/lib/host-process.sh already answers this in three states, keys on the structural shape of a listening row rather than on the localised word, and validates that what it parsed really is the table. Use it, on Windows and POSIX alike:

. scripts/lib/host-process.sh

probe_listener_port 17878
case "$LISTENER_PROBE_STATE" in
  found)      echo "busy: pid $LISTENER_PROBE_PID"; exit 1 ;;
  none)       echo "measured free" ;;
  unmeasured) echo "COULD NOT MEASURE port 17878 — refusing to start"; exit 2 ;;
esac

Underneath is listener_pid_for_port (0 = found, 1 = measured free, 2 = could not measure); probe_listener_port is the wrapper that turns those into LISTENER_PROBE_STATE, because out="$(f)"; rc=$? aborts under set -e and if out="$(f)"; then …; fi; rc=$? reads the compound's status, which is 0. Branch on all three states every time. There is no fourth branch to add and no default that is safe to leave off.

Resolve the real pid before killing anything. $! is the MSYS job pid; the Windows pid is the WINPID column of ps -W, and the image is the COMMAND column read from the header's own offset — STIME is one token (10:23:45) or two (Aug 27), so a field-index parse shifts on every row for a process that outlived midnight. That parse also has to reject a table it cannot read instead of reporting the process absent. All of it lives in ps_w_row_for, the single validated ps -W parse in the repository:

. scripts/lib/host-process.sh

rc=0
row="$(ps_w_row_for PID "$JOB_PID")" || rc=$?
case "$rc" in
  0) WIN_PID="${row%% *}"; IMAGE="${row#* }" ;;
  1) echo "no such job in the process table"; exit 1 ;;
  *) echo "COULD NOT READ the process table — refusing to kill anything"; exit 2 ;;
esac

windows_pid_for_job "$JOB_PID" "$PROGRAM" is the better entry point when the daemon was just spawned: it polls until the row names the program actually launched, because bash's $! first maps to the WINPID of the env that is about to be replaced. Do not write a second ps -W parse — there have been three copies of it in this repository and each time the hardening landed on one of them while the others went on counting words.

Kill by identity, never by pid alone. Windows recycles pids fast, and the pid in a stale state file may now be something else entirely. Compare the image path first; Handle is read to pin the pid so the process cannot exit and be replaced between the lookup and the kill:

MSYS2_ARG_CONV_EXCL='*' powershell.exe -NoProfile -NonInteractive -Command '
  $want = "C:/wl-target/debug/wenlan-server.exe" -replace "/", "\"
  try { $p = [System.Diagnostics.Process]::GetProcessById('"$WIN_PID"') } catch { exit 3 }
  try { $null = $p.Handle; $got = $p.MainModule.FileName } catch { exit 6 }
  if ($got -ine $want) { exit 4 }   # someone else owns this pid — do NOT kill
  $p.Kill(); exit 0'

Exit 3 = already gone, 4 = a different image (refuse), 6 = could not read the image (refuse). Only 0 means "we killed the process we meant to kill".

Then assert the teardown. Confirm the process is gone AND the port released before printing anything that looks like a pass; scripts/smoke-cli.sh and scripts/smoke-mcp.sh do exactly this and hold their PASS line until cleanup succeeds.

Prod daemon (the user's real instance on :7878)

Managed service: wenlan background on / wenlan background off / wenlan restart (launchd on macOS, systemd-user on Linux, schtasks on Windows). Other agents and the desktop app share it — never kill it casually.

Lifecycle checklist

  • Which binary owns :7878 — launchd, the main checkout, a stale worktree, or a previous session can all own it. lsof -i :7878 for the PID, then lsof -p <PID> | grep "txt.*wenlan-server" for the binary path and size. Kill and restart from the current working tree when in doubt.
  • Stale binary after merge/pull — cargo build -p wenlan-server may report "Finished" without recompiling after a fast-forward (source timestamps unchanged). Force it: touch crates/wenlan-server/src/router.rs && cargo build -p wenlan-server, then confirm the timestamp: ls -la target/debug/wenlan-server.
  • kill vs kill -9 — plain kill <PID> may not terminate the daemon cleanly. Use kill -9 <PID> and verify with lsof -ti :7878; if the port is still busy, another process took over.
  • Worktree target dirs are per-worktree — a binary built inside .worktrees/<name> lands in that worktree's target/, not the main repo's. Verify a running binary's source with lsof -p <PID> | grep wenlan-server.
  • Upgrading requires a restart — installing a new binary never replaces a running daemon: the new process detects the healthy incumbent on :7878 and exits (crates/wenlan-server/src/main.rs). wenlan background on stops the running service before reinstalling; wenlan restart (stop then start) reloads it explicitly. The MCP version handshake surfaces a stale daemon (VersionStatus::DaemonOutdated) and points users at wenlan restart.
  • Reranker startup — enabling the cross-encoder (WENLAN_RERANKER_ENABLED=1) blocks startup on a one-time ~1.1GB model download and, on failure, serves with no rerank; /api/status reports reranker as disabled / active / failed so the degraded state is visible.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.