dgf1988/codewhale
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: trim internal lighthouse setup notes

Browse Source
This commit is contained in:
Hunter Bown
2026-05-14 15:31:05 -05:00
parent a21d34181b
commit 63ab0a46a0
6 changed files with 17 additions and 234 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+7
View File
@@ -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
deploy/tencent-lighthouse/examples/whalebro.AGENTS.md
-21
View File
@@ -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.
docs/FEISHU_LIGHTHOUSE_V0_8_37_PLAN.md
-81
View File
@@ -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`
docs/TENCENT_LIGHTHOUSE_HANDOFF_PROMPT.md
-102
View File
@@ -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.
```
docs/TENCENT_LIGHTHOUSE_HK.md
+10 -24
View File
@@ -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.
scripts/tencent-lighthouse/bootstrap-ubuntu.sh
-6
View File
@@ -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