diff --git a/.gitignore b/.gitignore index bb019b13..f81c444e 100644 --- a/.gitignore +++ b/.gitignore @@ -93,6 +93,13 @@ apps/ # Maintainer-internal design notes (trade-secret material, never published) .private/ +# Agent handoffs and version-specific setup plans are working-state notes, not +# public docs. Keep durable setup guidance in docs/runbooks instead. +docs/*HANDOFF*.md +docs/*handoff*.md +docs/*_PLAN.md +!docs/archive/** + # direnv .envrc .direnv diff --git a/deploy/tencent-lighthouse/examples/whalebro.AGENTS.md b/deploy/tencent-lighthouse/examples/whalebro.AGENTS.md deleted file mode 100644 index db167943..00000000 --- a/deploy/tencent-lighthouse/examples/whalebro.AGENTS.md +++ /dev/null @@ -1,21 +0,0 @@ -# AGENTS.md - -This directory is a remote travel workspace, not a single project. - -Expected layout: - -- `deepseek-tui/` - canonical runtime/bridge checkout. The supported CLI is - `deepseek`; install both `crates/cli` and `crates/tui`. -- `whalescale/` - product repo. Active surface is `whalescale-desktop/`. -- `worktrees/` - remote worktrees created on this VPS. - -Operational rules: - -- Treat `/opt/whalebro` as the workspace root for phone-controlled work. -- Keep `deepseek serve --http` bound to `127.0.0.1`. -- Use SSH keys for Git remotes and never paste secrets into prompts, logs, or - committed files. -- Mac-only release tasks such as iOS simulator runs, `.app` packaging, DMG - verification, notarization, and Apple signing still need the local Mac. -- If a project has its own `AGENTS.md`, read it before editing inside that - project. diff --git a/docs/FEISHU_LIGHTHOUSE_V0_8_37_PLAN.md b/docs/FEISHU_LIGHTHOUSE_V0_8_37_PLAN.md deleted file mode 100644 index 42057d0a..00000000 --- a/docs/FEISHU_LIGHTHOUSE_V0_8_37_PLAN.md +++ /dev/null @@ -1,81 +0,0 @@ -# Feishu Lighthouse v0.8.37 Plan - -Goal: make Feishu/Lark on Tencent Lighthouse a supported remote-control path -for `deepseek serve --http`. - -## Release Shape - -- The public teaching path is Tencent-native: CNB source/build/deploy, - Lighthouse runtime, Feishu/Lark phone control, and optional EdgeOne for a - deliberate public HTTPS edge. -- `deepseek serve --http` runs as a localhost systemd service on the VPS. -- `integrations/feishu-bridge` receives Feishu/Lark messages over long - connection mode and calls the runtime API with a bearer token. -- `/opt/whalebro` is the remote workspace root. -- `/opt/whalebro/deepseek-tui` is required. -- `/opt/whalebro/whalescale` is available when product work is needed. -- Direct-message control is the default phone workflow. - -## Current Foundation - -- Bridge source: `integrations/feishu-bridge/` -- Tencent deploy assets: `deploy/tencent-lighthouse/` -- VPS scripts: `scripts/tencent-lighthouse/` -- Config validator: `integrations/feishu-bridge/scripts/validate-config.mjs` -- VPS doctor: `scripts/tencent-lighthouse/doctor.sh` -- Remote-first tutorial: `docs/TENCENT_CLOUD_REMOTE_FIRST.md` -- CNB deploy templates: `deploy/tencent-lighthouse/cnb/` -- Runbook: `docs/TENCENT_LIGHTHOUSE_HK.md` -- Computer Use handoff: `docs/TENCENT_LIGHTHOUSE_HANDOFF_PROMPT.md` - -## v0.8.37 Work - -1. Create a release branch for this lane, then update the runbook branch value - once it is pushed. -2. Add a Lighthouse doctor script that checks Ubuntu packages, Node version, - installed `deepseek` binaries, systemd unit files, env files, runtime health, - bridge process status, and localhost bind. -3. Add a bridge config validator that checks required env vars, token presence - on both services, domain selection, allowlist state, group-mode settings, and - writable thread-map path. -4. Add bridge tests for event dedupe, allowlist pairing, command dispatch, - group prefix handling, active-turn protection, and approval command parsing. -5. Add a manual end-to-end checklist for a fresh Lighthouse VM: - `/status`, prompt, `/interrupt`, approval allow/deny, `/threads`, `/resume`, - service restart, reboot persistence. -6. Tighten setup docs around the exact Feishu/Lark console fields: - bot capability, message permissions, `im.message.receive_v1`, long - connection mode, app release, bot DM pairing, and chat allowlist capture. -7. Add bridge logging that is useful in `journalctl`: startup config summary, - connection status, received message id, chosen thread id, turn id, approval - id, and compact runtime errors. -8. Add a release-note entry describing the Lighthouse + Feishu/Lark remote - control path and the supported first setup flow. -9. Add the CNB + Lighthouse + EdgeOne teaching shape without activating a live - CNB deployment pipeline before secrets, deploy key, and quota policy are - explicit. - -## Acceptance - -- A clean Tencent Lighthouse Ubuntu instance can be bootstrapped from the - documented branch. -- The Tencent-native onboarding doc explains when to use CNB, when to use - Lighthouse, and when EdgeOne is optional rather than required. -- CNB deploy examples are present but non-active until copied into `.cnb.yml` - and `.cnb/tag_deploy.yml`. -- `deepseek-runtime.service` starts and `/health` responds locally. -- `deepseek-feishu-bridge.service` connects through long connection mode. -- A Feishu/Lark phone DM can create a thread, run a prompt, interrupt a turn, - list threads, resume a thread, and answer a tool approval. -- `/status` reports runtime version, bind host, auth state, workspace, git repo, - branch, and dirty counts. -- After reboot, both services return to the same working state. - -## References - -- Tencent Lighthouse firewall docs: - `https://intl.cloud.tencent.com/document/product/1103/41393` -- Tencent Lighthouse SSH key docs: - `https://intl.cloud.tencent.com/ind/document/product/1103/41392` -- Lark/Feishu Node SDK: - `https://github.com/larksuite/node-sdk` diff --git a/docs/TENCENT_LIGHTHOUSE_HANDOFF_PROMPT.md b/docs/TENCENT_LIGHTHOUSE_HANDOFF_PROMPT.md deleted file mode 100644 index 5dba2538..00000000 --- a/docs/TENCENT_LIGHTHOUSE_HANDOFF_PROMPT.md +++ /dev/null @@ -1,102 +0,0 @@ -# Tencent Lighthouse + Lark Setup Handoff Prompt - -Use this prompt with a Computer Use capable agent when you are ready to create -the Tencent Lighthouse instance and Lark/Feishu app. - -```text -You are taking over a live setup task on my Mac. Use Computer Use/browser UI for the Tencent Cloud and Feishu/Lark consoles. Require explicit confirmation before purchases, external submissions, sending bot messages to other people, deleting files, or entering secrets. - -Goal: -Set up a Tencent Cloud Lighthouse Hong Kong VPS and a Feishu/Lark self-built bot so I can control a remote /opt/whalebro workspace from my phone while traveling in China. - -Repo/workspace: -- Canonical repo: /Volumes/VIXinSSD/whalebro/deepseek-tui -- Product repo to include on the VPS when requested: /Volumes/VIXinSSD/whalebro/whalescale -- Read /Volumes/VIXinSSD/whalebro/AGENTS.md and /Volumes/VIXinSSD/whalebro/deepseek-tui/AGENTS.md before editing. -- The repo now has a first-pass deployment/runbook under: - - docs/TENCENT_LIGHTHOUSE_HK.md - - docs/FEISHU_LIGHTHOUSE_V0_8_37_PLAN.md - - integrations/feishu-bridge/ - - deploy/tencent-lighthouse/ - - scripts/tencent-lighthouse/ -- Current working branch with this setup: work/v0.8.37-feishu-lighthouse. Verify it is pushed before relying on a VPS git clone. -- Current CNB mirror for this branch: https://cnb.cool/deepseek-tui.com/DeepSeek-TUI.git refs/heads/work/v0.8.37-feishu-lighthouse. -- Remote-first overview: docs/TENCENT_CLOUD_REMOTE_FIRST.md. -- CNB deploy templates are non-active examples under deploy/tencent-lighthouse/cnb/. - -Important architecture: -- Use plain Ubuntu 24.04 LTS on Tencent Lighthouse Hong Kong. -- Buy the HK Linux 2 vCPU / 4 GB / 70 GB / 30M / 2 TB per month plan first, preferably 1 month. -- The runtime must stay bound to 127.0.0.1:7878 on the VPS. -- The phone-facing channel is the Feishu/Lark bot long connection service. -- CNB is the preferred source/deploy lane once the branch exists there. -- EdgeOne is optional and should only front a deliberate public HTTPS service; do not expose /v1 runtime endpoints through it. -- Direct message control is the MVP. Keep FEISHU_ALLOW_GROUPS=false initially. -- The VPS workspace root is /opt/whalebro. -- Required checkout: /opt/whalebro/deepseek-tui. -- Optional checkout if I want the full active workspace: /opt/whalebro/whalescale. -- Use /opt/whalebro/worktrees for worktrees intentionally created on the VPS. -- If these deployment files are not pushed to Git yet, either help me push the branch first or copy the current local checkout to the VPS. A fresh VPS clone cannot see uncommitted local files. - -Secrets to collect from me interactively: -- Tencent Cloud login/session if not already logged in. -- SSH public key to add to Lighthouse. -- DeepSeek API key for /etc/deepseek/runtime.env. -- Runtime bearer token: generate with openssl rand -hex 32. -- Feishu/Lark App ID and App Secret from the self-built app. - -Tencent Cloud steps: -1. Open Tencent Cloud Lighthouse purchase page. -2. Select Hong Kong, China region. -3. Select plain Ubuntu 24.04 LTS or latest Ubuntu LTS. -4. Select the HK 2c/4G/70G monthly plan first. -5. Use SSH key login, not password login. -6. Confirm firewall/security group keeps SSH open. -7. Ask me before clicking final purchase/checkout. -8. After purchase, record the public IP and SSH command. - -Feishu/Lark steps: -1. Open Feishu China or Lark international developer console, whichever matches my account. -2. Create an enterprise self-built app. -3. Enable bot capability. -4. Add message receive/send permissions required for text DMs. -5. Add event subscription for im.message.receive_v1. -6. Use long connection/WebSocket mode. -7. Publish/release the app as required by the console. -8. Add the bot to my own DM chat first. - -VPS setup steps: -1. SSH into the instance. -2. Clone the repo from CNB when available and run docs/TENCENT_LIGHTHOUSE_HK.md exactly, adapting only branch/repo URL if needed. -3. Run: - sudo DEEPSEEK_REPO_URL=https://cnb.cool/deepseek-tui.com/DeepSeek-TUI.git DEEPSEEK_REPO_BRANCH=work/v0.8.37-feishu-lighthouse bash scripts/tencent-lighthouse/bootstrap-ubuntu.sh - If I confirm I want whalescale on the VPS immediately, use: - sudo DEEPSEEK_REPO_URL=https://cnb.cool/deepseek-tui.com/DeepSeek-TUI.git DEEPSEEK_REPO_BRANCH=work/v0.8.37-feishu-lighthouse WHALEBRO_EXTRA_REPOS='whalescale=https://github.com/Hmbown/whalescale.git' bash scripts/tencent-lighthouse/bootstrap-ubuntu.sh - Use SSH remotes instead if the repo is private or I need push access from the VPS. -4. Install Rust 1.88+ for the deepseek user via rustup minimal profile. -5. Build/install both binaries: - cargo install --path crates/cli --locked --force - cargo install --path crates/tui --locked --force -6. Run: - sudo bash scripts/tencent-lighthouse/install-services.sh -7. Edit /etc/deepseek/runtime.env and /etc/deepseek/feishu-bridge.env. -8. Validate bridge/runtime config: - sudo -u deepseek node /opt/deepseek/bridge/scripts/validate-config.mjs --env /etc/deepseek/feishu-bridge.env --runtime-env /etc/deepseek/runtime.env --workspace-root /opt/whalebro --check-filesystem -9. Start deepseek-runtime and verify: - curl -s http://127.0.0.1:7878/health -10. Start deepseek-feishu-bridge and tail logs. -11. Run: - sudo bash /opt/whalebro/deepseek-tui/scripts/tencent-lighthouse/doctor.sh -12. Pair by temporarily setting DEEPSEEK_ALLOW_UNLISTED=true if needed, DM the bot, copy the returned chat_id, set DEEPSEEK_CHAT_ALLOWLIST to that chat_id, then turn DEEPSEEK_ALLOW_UNLISTED=false. - -Validation: -- From phone DM, send /status. -- Confirm the bot reports runtime, version, bind host, and workspace status. -- Send a harmless prompt: "summarize git status". -- Confirm the runtime bind host is 127.0.0.1. -- Validate /interrupt, /threads, /resume, /allow, and /deny from the phone DM. -- Run systemctl status for both services. -- Restart both services and confirm /status still works. -- Reboot the instance and confirm both services return active. -- Capture final IP, SSH command, service status, and any remaining blockers. -``` diff --git a/docs/TENCENT_LIGHTHOUSE_HK.md b/docs/TENCENT_LIGHTHOUSE_HK.md index aa8e6b85..37ea08cc 100644 --- a/docs/TENCENT_LIGHTHOUSE_HK.md +++ b/docs/TENCENT_LIGHTHOUSE_HK.md @@ -19,7 +19,6 @@ Feishu/Lark mobile app -> http://127.0.0.1:7878 deepseek serve --http -> /opt/whalebro -> deepseek-tui/ - -> whalescale/ when product work is needed Optional public edge: EdgeOne -> Caddy/Nginx public site on Lighthouse @@ -32,18 +31,16 @@ HTTP service, not the runtime API. ## Remote Whalebro Workspace Use `/opt/whalebro` as the VPS workspace root. The first-class checkout is -`/opt/whalebro/deepseek-tui`; add `/opt/whalebro/whalescale` if you want the -desktop product repo available from the phone too. +`/opt/whalebro/deepseek-tui`. Create these paths first: - `/opt/whalebro/deepseek-tui` -- `/opt/whalebro/whalescale` - `/opt/whalebro/worktrees` -Linux is enough for Rust, Node, service work, and most `whalescale-desktop` -web/Tauri development. Mac-only release work such as iOS simulator runs, -`.app`/DMG checks, notarization, and Apple signing still belongs on the Mac. +Linux is enough for Rust, Node, and service work. Mac-only release work such +as iOS simulator runs, `.app`/DMG checks, notarization, and Apple signing +still belongs on the Mac. ## Lighthouse Instance @@ -89,7 +86,7 @@ SSH into the Lighthouse instance and run: ```bash sudo apt-get update sudo apt-get install -y git -export DEEPSEEK_BRANCH=work/v0.8.37-feishu-lighthouse +export DEEPSEEK_BRANCH=main export DEEPSEEK_REPO_URL=https://cnb.cool/deepseek-tui.com/DeepSeek-TUI.git git clone --branch "$DEEPSEEK_BRANCH" "$DEEPSEEK_REPO_URL" /tmp/deepseek-tui cd /tmp/deepseek-tui @@ -98,17 +95,8 @@ sudo DEEPSEEK_REPO_URL="$DEEPSEEK_REPO_URL" \ bash scripts/tencent-lighthouse/bootstrap-ubuntu.sh ``` -If you also want `whalescale` cloned during bootstrap, pass it explicitly: - -```bash -sudo DEEPSEEK_REPO_URL="$DEEPSEEK_REPO_URL" \ - DEEPSEEK_REPO_BRANCH="$DEEPSEEK_BRANCH" \ - WHALEBRO_EXTRA_REPOS='whalescale=https://github.com/Hmbown/whalescale.git' \ - bash scripts/tencent-lighthouse/bootstrap-ubuntu.sh -``` - -Use SSH repo URLs instead if either repo is private or you want push access -from the VPS. If the CNB mirror is unavailable, fall back to: +Use an SSH repo URL instead if you want push access from the VPS. If the CNB +mirror is unavailable, fall back to: ```bash export DEEPSEEK_REPO_URL=https://github.com/Hmbown/DeepSeek-TUI.git @@ -120,13 +108,12 @@ using it: ```bash export DEEPSEEK_REPO_URL=https://cnb.cool/deepseek-tui.com/DeepSeek-TUI.git git ls-remote "$DEEPSEEK_REPO_URL" \ - refs/heads/work/v0.8.37-feishu-lighthouse \ + refs/heads/main \ refs/tags/v0.8.37 ``` -The CNB mirror receives `main`, release tags, and Tencent setup branches that -match `work/v*-feishu-*` or `work/v*-lighthouse*`. CNB is the default source -for this Lighthouse path; GitHub is the fallback only when the CNB workflow or +The CNB mirror receives `main` and release tags. CNB is the default source for +this Lighthouse path; GitHub is the fallback only when the CNB workflow or credentials are unhealthy. If this deployment setup has not been pushed to Git yet, either push the branch @@ -304,4 +291,3 @@ From a phone DM to the bot: - Use `tmux` for emergency terminal work from Blink/Termius. - Keep `/opt/whalebro/deepseek-tui` on a personal branch while working from the phone. -- Keep `/opt/whalebro/whalescale` on its own branch when doing product work. diff --git a/scripts/tencent-lighthouse/bootstrap-ubuntu.sh b/scripts/tencent-lighthouse/bootstrap-ubuntu.sh index 07bb31fb..02e41a4e 100755 --- a/scripts/tencent-lighthouse/bootstrap-ubuntu.sh +++ b/scripts/tencent-lighthouse/bootstrap-ubuntu.sh @@ -67,12 +67,6 @@ for repo_spec in ${WHALEBRO_EXTRA_REPOS}; do fi done -if [[ ! -f "${WHALEBRO_ROOT}/AGENTS.md" && -f "${SOURCE_ROOT}/deploy/tencent-lighthouse/examples/whalebro.AGENTS.md" ]]; then - install -m 0644 -o "${DEEPSEEK_USER}" -g "${DEEPSEEK_USER}" \ - "${SOURCE_ROOT}/deploy/tencent-lighthouse/examples/whalebro.AGENTS.md" \ - "${WHALEBRO_ROOT}/AGENTS.md" -fi - if [[ ! -f /etc/deepseek/runtime.env ]]; then cat >/etc/deepseek/runtime.env <<'EOF' DEEPSEEK_RUNTIME_TOKEN=replace-with-long-random-token