@turmind/halo 0.1.9

package/bundled-docs/plans/design-suggestions.md

@@ -0,0 +1,203 @@
+# Session persistence and orchestration — design suggestions
+
+Captured while debugging the "third message freeze" bug (`text content blocks must be non-empty`) — documents the structural issues found and proposes improvements over the current state. Everything revolves around **session message state**: multiple write paths, multiple sources of truth, and lossy backward inferences — the shared root of that bug.
+
+---
+
+## 1. Make message persistence one-way — `rawMessages` as the single source of truth
+
+### Current state
+
+Each session maintains two copies:
+
+- **`rawMessages`**: Strands Agent's internal `agent.messages`, Bedrock's native format including full `tool_use` / `tool_result` pairs. Persisted by `saveAgentState` at turn end.
+- **`messages`**: the UI display log, assembled by `event-processor` from streaming events (assistant text, tool_call cards, usage badges, etc.). Rendered directly on refresh.
+
+The two paths write independently; consistency relies on order-of-ops going right.
+
+### Problem
+
+This bug came from a third path — `handler.ts`'s `restoreHistory(sid, client.messageLog)` — that tried to reverse the UI log back into `rawMessages`. Tool-only assistant turns in the UI log have empty-string content (tool cards don't live in the content field), so the inverse maps them to `{type: 'text', text: ''}` and Bedrock rejects it.
+
+As long as the "UI log → rawMessages" direction exists, "restore agent state from UI" will keep producing bugs like this.
+
+### Suggestion
+
+- **`rawMessages` is the sole source of truth**; the UI log is derived.
+- **Never infer `rawMessages` from the UI log.**
+- On refresh / reconnect: UI log is loaded directly from disk (for rendering), `rawMessages` is lazily loaded by `ensureSession` (for the next Bedrock call). The two paths run **in parallel and don't rebuild each other.**
+- Compact should also operate on `rawMessages` — summarise, replace the old slice, then derive the new UI log from the event stream. Not "edit UI log then reverse-derive".
+
+---
+
+## 2. Run repair once before every Bedrock call
+
+### Current state
+
+`repairConversationMessages` currently runs:
+
+- At turn end (end of `runAgentTurn`)
+- After interrupt / stop
+- After compact
+
+But **not before `sendUserMessage` hands over to Bedrock**.
+
+### Problem
+
+On-disk `rawMessages` may be unhealthy due to older bugs, external edits, version upgrades, etc. Today, once `ensureSession` loads bad state from disk, it gets sent to Bedrock and triggers the same kind of crash we just hit.
+
+I've added "drop empty text blocks" as a safety net in `conversation-repair.ts`; still, moving the defensive step forward catches future unknown bad data.
+
+### Suggestion
+
+- In `sendUserMessage`, before hitting `handleUserTurn`, call `repairConversationMessages(session.agent.messages)`.
+- Repair becomes the "last gate into Bedrock", so wherever rawMessages came from (new / disk restore / older-version file), it's cleansed.
+- Performance is fine: repair is O(n) and n is not large.
+
+---
+
+## 3. Sub-session log persistence: move "merge-save" out of event-processor, into SessionManager
+
+### Current state
+
+`event-processor.ts`'s `saveSubSession`:
+
+```
+On every query_session / start_session
+  → subSessionLogs initialised in memory
+  → event stream writes into it
+  → on agent_done: read from disk → merge by message id → write back
+```
+
+`subSessionLogs` is client-connection-level (WebSocket), rebuilt per query and holding only this turn's events. Hence the merge.
+
+### Problem
+
+- **merge-by-id depends on "ids are consistent and unique"**. Any id jitter, reconnect-leftover state, or duplicate `initSubSessionLog` call produces lost or duplicate messages.
+- **Persistence is coupled to the network layer**. event-processor should just forward events to the WS; here it also takes on "cross-connection disk merge". Violates CLAUDE.md's "persistence must not depend on in-memory transient state" — `subSessionLogs` is in-memory transient state.
+- **Reconnect / refresh is error-prone**: a new connection creates a new `subSessionLogs`; unflushed events from the old one are lost; detach creates yet another independent copy in `backgroundHandler`, and reconciling both is a hazard.
+
+### Event loss risk (extended)
+
+This is a separate risk beyond the merge mechanism — an **eye-vs-disk** inconsistency where **events actually happened, but the log doesn't reflect them**. Scenarios:
+
+1. **Stream buffer not flushed before a crash**. `stream` events aggregate into in-memory `turnContentBlocks` / `streamBuffer`; only `usage` / `agent_done` / `complete` trigger `flushAssistantMessage` + `saveSubSession`. Crash beforehand (OOM, uncaught exception, kill) loses every piece of streaming text and tool_call for the turn — disk has no trace the agent said anything.
+
+2. **WS-disconnect brief window**. Between disconnect and `backgroundHandler` takeover is a window where `sendJson` fails and the event is silently dropped; grace expiry triggers a single `save()`, and a crash in between loses the whole stretch.
+
+3. **Merge id jitter losing messages**. `saveSubSession` dedupes by `m.id`, but `genId()`'s counter is process-scoped — process restart resets the counter. A restart between two flushes can produce same-id-different-message entries; merge overwrites them.
+
+4. **Event semantics vs disk state out of sync**. Frontend / logs already saw a `tool_call` fire (went through `sendJson`), but it's only in the in-memory `messageLog`; the next `saveSubSession` writes it. Checking disk in between makes it look like nothing happened. Fatal for audit-log use cases.
+
+### Suggestion
+
+**Short-term (bundle with the merge issue)**:
+- SessionManager **owns** the sub-session UI log (persisted alongside `rawMessages`), append-only, single-process concurrency-safe.
+- event-processor reverts to **pure forwarding**: receive event → push to WS; no persistence duty.
+- Tighten flush granularity from "key events" to "every tool_call / tool_result / every N seconds" to shrink the crash window.
+
+**Long-term (fully eliminate event loss)**:
+- Switch to an **append-only JSONL event log**: every agent event lands as a new line in `.halo/sessions/{agentId}/{sessionId}.jsonl` the moment it fires.
+- Renderers aggregate to `SessionMessage[]` on load (event-sourcing projection).
+- Cost: higher disk I/O (one-write-per-stream-delta is too much). Compromise: "every tool_call / tool_result / end-of-assistant-paragraph / every 500 ms batch append".
+- Benefit: crash window shrinks from "whole turn" to "last flush interval"; disk is a faithful log of events, no code-path skipping `save()` loses a whole stretch.
+
+---
+
+## 4. `query_session` to an IDLE target: `onComplete` vs `releaseSession` race
+
+### Current state
+
+```typescript
+// session-manager.ts :1166
+this.runSession(targetSessionId, prefix + message).then((result) => {
+  onComplete?.(result)
+})
+return `Message sent to session ${targetSessionId}...`
+```
+
+`runSession` is fire-and-forget with `onComplete` in `.then()`. But `runSession`'s own `finally` (:1030) immediately calls `releaseSession`.
+
+### Problem
+
+JavaScript microtask scheduling usually keeps `finally` before the `.then()` callback, but the race exists:
+
+- `finally`'s `releaseSession` drops the session from memory.
+- Immediately after, `.then(onComplete)` fires; `onComplete` itself calls `querySession(sessionId, childSessionId, result)` (auto-report to source), and that `querySession` does `ensureSession(childSessionId)` — which has to go through the disk restore path since memory is gone.
+- If the disk save hasn't fully flushed (`saveAgentState` is synchronous but can be interleaved by the Node event loop), or something else is writing concurrently, `ensureSession` might read stale state.
+
+Not guaranteed, but the window exists. E3 (query_session to an idle sub-agent) can likely reproduce under concurrency / repetition.
+
+### Suggestion
+
+- Chain `onComplete` onto `session.promise` itself, so "`runSession` fully finishes (including `releaseSession`) → `onComplete` → next `querySession`" runs strictly in sequence.
+- Or simpler: have `querySession` itself `await runSession` and call `onComplete` synchronously, avoiding `.then()` entirely.
+- Add a "just-released session stays in memory for N ms" cache window in `ensureSession` to damp rapid release/restore cycles.
+
+---
+
+## 5. Post-disconnect event replay needs a barrier on reconnect
+
+### Current state
+
+WS disconnects:
+- Session marked "detached", `backgroundHandler` registered
+- Events flow into `detached.pendingEvents`
+
+WS reconnects:
+- `handleSubscribe` detects the detached session → replays `pendingEvents` one by one via `sendJson`
+- Meanwhile switches the listener back to the new WS's live callback
+
+### Problem
+
+There's no barrier between listener switch and `pendingEvents` replay. If SessionManager is currently emitting a new event:
+
+- The new event (B) goes through the live listener to the new WS
+- Older `pendingEvents` (A) are still being sent one-by-one
+- Frontend sees B before A — out of order
+
+F2 ("disconnect → reconnect") + "steady events during disconnect + fresh events at the moment of reconnect" can reproduce it.
+
+### Suggestion
+
+- On reconnect, hold a lock: `pendingEvents` keeps accepting but doesn't **drain**; the listener is still on the background handler.
+- Atomic switchover: `listener replace + pendingEvents drain + subSessionLogs restore` is one transaction; new events during this keep flowing to `pendingEvents`.
+- After the transaction, flush `pendingEvents` and switch the listener to the new WS.
+- Add an integration test: F2 scenario + forced concurrent events; watch the sequence numbers arriving on the frontend are monotonically increasing.
+
+---
+
+## 6. Clean up the deprecated `destroySessions`
+
+### Current state
+
+`session-manager.ts` has a `@deprecated`-tagged `destroySessions` method with a doc saying "Use deleteSession + deleteSessionLogs in Phase 3".
+
+### Problem
+
+- It's debt — deprecated methods can still be called accidentally, and they raise eyebrows in review.
+- New readers get confused: which one do I use?
+- Keeping two deletion paths means every future change has to consider both.
+
+### Suggestion
+
+- Just delete `destroySessions`.
+- Grep-verify no callers (from `.halo/docs/` through `packages/`).
+- If stragglers exist, migrate them to `deleteSession` + `deleteSessionLogs`, then delete.
+
+---
+
+## Priority
+
+By fix-value vs change-footprint:
+
+| # | Suggestion | Priority | Scope |
+|---|---|---|---|
+| 2 | Repair before sendUserMessage | High | one line |
+| 6 | Delete destroySessions | High | one method |
+| 1 | One-way (forbid UI→raw inverse) | High | architectural principle |
+| 4 | Fix onComplete race | Medium | one callback |
+| 5 | Reconnect event barrier | Medium | one subsystem |
+| 3 | Sink sub-session persistence | Low, long-term | larger refactor |
+
+1, 2, 6 can be done right away; 4, 5 deserve integration tests first. 3 is the long-term direction — not urgent, but inevitable.

package/bundled-docs/plans/issue-session-deep-nesting.md

@@ -0,0 +1,208 @@
+# Deep Session Nesting — Investigation & Fixes
+
+## Current state of session tools
+
+### Tool list
+
+Agent-accessible session tools are defined in `session-manager.ts:437-673`, 9 in total:
+
+| Tool | Purpose |
+|---|---|
+| `start_session` | Create a child session, run asynchronously, auto-report on completion |
+| `query_session` | Send a message to an existing session — run immediately if idle, queue if busy |
+| `stop_session` | Stop a session, set `stoppedAt`; recoverable via `query_session` or a user message |
+| `archive_session` | Cascade soft-delete a subtree, set `archivedAt`; not recoverable |
+| `interrupt_session` | Interrupt and immediately re-run with a new message |
+| `session_list` | List the current session's children and their status |
+| `get_session_output` | Read a child session's output text |
+| `list_agents` | List delegatable agents |
+| `query_agent` | Inspect an agent's config and AGENT.md |
+
+### start_session flow
+
+`session-manager.ts:440-485`
+
+1. Validate `agent_id` exists and isn't default
+2. `createSession(agentId, parentId=currentSessionId)` → write SQLite + memory map + emit `context`
+3. Emit `agent_start` (frontend shows sub-agent starting)
+4. **Async** `runSession(childId, message)` — the tool returns immediately without blocking the parent turn
+5. Attach a one-shot `.then()`: when the child session's first runSession resolves:
+   - emit `agent_done`
+   - `querySession(parentId, childId, result.slice(0, 2000))` forwards the result to the parent
+
+### query_session flow
+
+`session-manager.ts:497-529` (tool) + `1401-1452` (core method)
+
+1. Emit `agent_start` (frontend initialises the sub-session log)
+2. `sm.querySession(targetId, sourceId, message, onComplete)`:
+   - target idle → `runSession` runs immediately
+   - target busy → message goes to `target.messageQueue`, drained by `drainQueue`
+3. `onComplete`: after the target finishes → emit `agent_done` + `querySession` back to source
+
+### stop_session flow
+
+`session-manager.ts:571-588` (tool) + `1377-1399` (core method)
+
+1. `abortController.abort('stop')` cancels the LLM call
+2. Await promise completion
+3. Clear `messageQueue` + `pendingUserMessages`
+4. `repairConversationMessages`
+5. `releaseSession` (persist + drop from memory)
+6. DB write `stoppedAt = Date.now()`
+
+Stop is recoverable: `query_session` or a user message clears `stoppedAt` and returns the session to idle. `listSessions` shows `status: 'stopped'`.
+
+### archive_session flow
+
+`session-manager.ts` (tool) + core method `archiveSessionTree`
+
+1. Recursively walk DB to find every descendant session
+2. For each: DB write `archivedAt`; `archiveSession` (abort → await promise → clear queues → drop from map)
+3. Return count archived
+
+Difference vs stop: archive cascades the whole subtree + sets `archivedAt` (not recoverable); stop only stops one and sets `stoppedAt` (recoverable).
+
+### Event routing
+
+`session-manager.ts:214-222` `emitEvent` does three things:
+1. Append to `.events.jsonl` (persistent audit log)
+2. `reduceIntoUIState` (update in-memory UIState + save `.json`)
+3. Push via `eventListeners` to the frontend (WS)
+
+Event routing uses `findRootSessionId` (`session-manager.ts:178-196`): walk up the parentId chain to the root, then use the root's listener to send.
+
+### Session lifecycle
+
+- **idle**: `promise === null`, waiting for input
+- **running**: `promise !== null`, inside an LLM or tool call
+- **stopped**: `stoppedAt` is set, recoverable via `query_session` or a user message
+- **archived**: `archivedAt` is set, not recoverable
+
+Transitions:
+- idle → running: `sendUserMessage` / `runSession` / `querySession`
+- running → idle: turn finishes + empty queue → finally sets `promise = null`
+- idle → stopped: `stopSession` or `tryReportToParent` (auto-report marks done)
+- stopped → idle: `querySession` / `sendUserMessage` clears `stoppedAt`
+- any → archived: `archiveSessionTree`
+
+---
+
+## Deep nesting problems (16-layer scenario)
+
+### Problem 1 (fatal): auto-report chain breaks beyond 2 levels
+
+`start_session`'s `.then()` is bound to the **first** runSession promise of the child — it's one-shot.
+
+Three-layer example:
+```
+L1 start_session → L2    .then() bound to L2's runSession promise
+L2's agent decides to delegate → start_session → L3
+L2's first turn completes → runSession resolves → L1's .then() fires
+  → result = "I have delegated to L3" (garbage intermediate info)
+  → querySession to L1 (user receives useless report)
+
+L3 completes → auto-report to L2 → L2 handles result
+  → but L2 → L1's .then() has already fired
+  → L2's new result has nowhere to go
+```
+
+Result: **the real work result only propagates one level; it never reaches the user.**
+
+### Problem 2: sub-agents can't find their parent
+
+The session tools don't expose the parent session ID. An agent can't proactively `query_session` its parent. System auto-report is the only upward channel — and it fires only once.
+
+### Problem 3: `findRootSessionId` is O(depth) DB lookup
+
+Every `emitEvent` walks the parentId chain up to the root. When intermediate layers have been released from memory by `releaseSession`, each level hits SQLite.
+
+At layer 16, each event (stream, tool_call, tool_result, …) walks 16 levels. Dozens of events per turn × 16 = hundreds of DB lookups.
+
+### Problem 4: stale session references
+
+`start_session` at line 467 captures the parent session object:
+```typescript
+const session = sm.sessions.get(sessionId)
+```
+When the parent session's turn completes, `releaseSession → sessions.delete()`. The new object built by `ensureSession` is a different instance. `.then()`'s `session?.interruptedSessionIds` operates on the now-dead old object.
+
+### Problem 5: no depth limit
+
+No nesting check — pathological agent behaviour can nest infinitely until OOM or rate-limit blowout.
+
+### Problem 6: concurrent rate limits
+
+During the report phase, multiple layers wake up simultaneously via `querySession`, hit Bedrock concurrently, trigger ThrottlingException. Linear backoff + many sessions retrying simultaneously → cascading failure.
+
+---
+
+## Fix plan (implemented)
+
+### Hierarchical session_id + level-by-level bubbling
+
+**session_id format**: hierarchy encoded with `>` separators. `createSession` appends a new segment for child ids: `{parentId}>{new_segment}`.
+
+```
+root:    sid_abc
+child:   sid_abc>sid_def
+grand:   sid_abc>sid_def>sid_ghi
+```
+
+- Depth = `id.split('>').length`; exceeding `config.session.maxNestingDepth` (default 16) rejects `start_session`
+- `findRootSessionId` = `id.split('>')[0]`, O(1)
+
+**Auto-report mechanism**: `tryReportToParent(session)` method, called inside `runSession`'s finally after `promise = null`.
+
+Report conditions:
+1. `parentId !== null` (not root)
+2. DB query `WHERE parent_id = session.id AND stopped_at IS NULL AND archived_at IS NULL` finds no active children
+3. `!session.skipRelease` (not in an interrupt flow)
+
+All three → set `stoppedAt` + emit `agent_done` + `querySession(parentId, id, result)`.
+
+**Removed**:
+- Manual `.then()` reports in `start_session` / `interrupt_session` / `query_session`
+- The `interruptedSessionIds` field
+- `onComplete` callbacks (`runSession`, `querySession`, `QueuedMessage`)
+
+### Rate-limit retry (done)
+
+Exponential backoff + jitter: 2s → 4s → 8s → 16s… capped at 60s. `maxRetries` defaults to 5.
+
+### Duplicate child guard (done, mitigation)
+
+In `start_session`'s callback, before `createSession` we query DB: if a non-stopped-non-archived child session with the same parentId + same agentId already exists, reject with a hint.
+
+Mitigates the case where conversation repair makes the LLM re-delegate the same agent. Not a full fix.
+
+---
+
+## Still open: conversation repair erases delegation history (likely root cause)
+
+**Status**: suspected issue, needs more verification
+
+**Symptom**: in 16-layer depth tests, some layers branch — one parent session creates multiple same-agent children.
+
+**Analysis**:
+
+`conversation-repair.ts` Phase 2 and Phase 2b can't distinguish "structural damage" from "valid tool-call history" when repairing a damaged message array.
+
+Flow:
+1. `runAgentTurn` hits a Bedrock error (e.g. `unexpected tool_use_id found in tool_result`)
+2. Calls `repairConversationMessages`
+3. Phase 2 (lines 72-119): scan assistant→user pairs, drop entries where tool_use ID and tool_result ID don't match
+4. Phase 2b (lines 122-151): drop user tool_result with no corresponding assistant tool_use
+5. `start_session`'s record (tool_use + tool_result) gets treated as "damage" and swept up
+6. On LLM retry the conversation history has no delegation trace → a new `start_session` call creates a duplicate child
+
+**Impact chain**:
+- Direct: branching child sessions at the same level, abnormal tree structure
+- Indirect: `session_list` shows multiple running same-agent children; `get_session_output` reading different children confuses the LLM
+- Orphaned branches can't complete their lifecycle, stuck in running/idle forever
+
+**Fix direction**: make conversation repair protect session management tool calls (`start_session`, `query_session`, …) from being deleted.
+
+**To verify**:
+- Does this also happen at shallower depths (2-3), or only at deep nesting with high retry rates?
+- Is the duplicate-child guard enough of a mitigation in practice?

package/bundled-docs/plans/launch-plan.md

@@ -0,0 +1,111 @@
+# Halo 对外推广计划 (Go-to-Market)
+
+> 起草人:halo仔 · 状态:草案,待咚咚总拍板方向
+> 一句话:**先把"门面 + 弹药"修好,再开渠道。子弹没上膛之前别扣扳机。**
+
+---
+
+## 0. 先认清现状 —— 你的底气比你以为的足
+
+**底气(别人砸钱都买不到的):**
+- 作者自用一个半月**无暗伤**,另有 2-3 人**持续留存几个月** → 这是 PMF(产品-市场契合)的雏形,已被真实验证了一小块。多少项目 Show HN 几百 star、三天 DAU 归零,你刚好反过来:没声量,但有留存。
+- **独门视觉牌**:粒子脸(Express Self)+ 像素城市(Halo City)。绝大多数 agent 工具就是个丑终端,你有天生适合短视频传播的东西。像素城市那张图质量已经够发。
+
+**短板(要么修、要么坦诚):**
+- 无声量、单人维护、无自动化测试 → README 的 "Status & Limitations" 已经很诚实,**保留**,这反而是加分项(海外开发者吃这套)。
+- **门面有空截图硬伤**(见第 3 节 P0)。
+
+---
+
+## 1. 定位:先解决"一句话"
+
+2025 年 agent 工具卷到飞起(Cursor / Claude Code / Devin / Manus…),路人第一反应一定是"又一个?凭啥用你"。必须一句话把差异点砸进去。
+
+**Halo 真正的差异点(按稀缺度排序):**
+1. **多渠道指挥** —— 微信/TG/飞书/Slack 都能直接指挥,不绑死在 IDE 里。**这个位几乎没人占。**
+2. **自托管 + 多模型 + 自己的密钥边界** —— 数据不出你的机器。
+3. **一切皆文件、无隐藏记忆** —— 对控制欲强的开发者是真卖点。
+4. **视觉化的 agent 运行时** —— 看得见每个 agent 在干啥。
+
+**英文定位候选(待选):**
+- A. *"Your AI dev team — command it from any chat app, running entirely on your own machine."*
+- B. *"A self-hosted AI agent team you command from Slack, Telegram, or WeChat — not locked inside an IDE."*
+- C. *"The multi-agent dev workspace that lives in your terminal and your chat apps — not someone else's cloud."*
+
+> ⚠️ 最终选哪句,**取决于那 2-3 个留存用户最离不开的功能**。他们用脚投票留下的那个点,大概率就是对外该喊的话。所以这句先别急着定死。
+
+---
+
+## 2. 公用弹药库 —— 所有渠道都要用,先做这个
+
+不管最后走哪条渠道,这三样是公用子弹,先做绝不亏:
+
+| 弹药 | 说明 | 负责 |
+|---|---|---|
+| **① 一句话定位** | 见上,等留存用户反馈后敲定 | 咚咚总拍板 |
+| **② 60 秒 demo 视频/GIF** | 押视觉牌:粒子脸说话 + 像素城市里 agent 跑动 + 多渠道手机指挥。**这是 Show HN / PH 的钩子,比任何文字都强** | halo仔出脚本,咚咚总录 |
+| **③ README 改版** | 换掉空截图 hero(见 P0),把"多渠道 + 视觉"提到最前 | halo仔 |
+| ④ landing page(可选) | 一个能在线瞄一眼的页面,降低门槛 | 二期 |
+
+---
+
+## 3. 门面急救清单
+
+### 🔴 P0 —— 推广前必须修
+
+- **README 首图(`assets/workspace.jpg`)是一个空工作区!** Canvas 写着 "Open a file to start editing",Chat 写着 "Start a conversation" —— 整个项目最重要的第一张图,却展示了一个**什么都没发生的空壳**。这是第一印象的致命伤。
+  - **改法**:换成"火力全开"的截图 —— agent 正在思考、sub-agent 在跑、文件树有改动标记、代码在 Canvas 里、对话有来有回。让人一眼看到"这玩意儿在干活"。
+
+### 🟡 P1 —— 强烈建议
+- 体检报告(deep-executor 正在跑)回来后补充。
+
+---
+
+## 4. 渠道排期 —— 别贪多,挑水塘蹲
+
+### 主线:海外开发者(自托管多 agent 的人群密度最高)
+
+| 顺序 | 渠道 | 说明 | 你要做的 |
+|---|---|---|---|
+| 首发 | **Show HN**(Hacker News) | 全球科技圈最猛的水塘。"Show HN: 给大家看看我做了个啥"。一旦上首页,几小时几万开发者刷到,免费 | 发帖后头 1-2 小时回评论 |
+| 跟进 | **Reddit** r/LocalLLaMA · r/selfhosted | 自托管 AI 的高浓度人群,正好是你的目标用户 | 同上 |
+| 持续 | **Twitter/X** build-in-public | 持续发 demo 短视频,养长期关注 | 每周 1-2 条 |
+| 拿牌 | **Product Hunt** | 等有点声量后冲,拿个 badge | 单独排期 |
+
+### 第二梯队:AWS(不是拉用户,是背书 + 省钱)
+
+> 咚咚总的直觉对一半:**写软文夸 Halo 发 AWS 博客确实戆居**(读者来学技术不是来找产品,转化≈0)。但 AWS 渠道的真实价值在别处:
+
+- **`AWS Activate` / startup credits** —— 跟推广无关,纯省钱。**今天就该申请,顺手的事,无脑做。**
+- **`community.aws` 技术稿**(自助发布、门槛低)—— 写"如何解决一个通用难题",Halo 只当案例出场。你真有干货:Bedrock 上做 prompt caching、用 Nova grounding 取代传统 web search、多 provider 的 agent runtime 抽象、自托管多 agent 协作系统怎么搭。立技术口碑 + SEO 长尾 + 以后见客户/投资人的背书。
+- ⚠️ 注意:你的产品命脉之一**就是 Bedrock**(默认引擎 Claude on Bedrock、GPT 走 bedrock-mantle、联网搜索用 Nova)。所以"我做的东西不用 AWS"这个前提不成立 —— AWS 内容有得写,只是别放第一发。
+
+### 可选:国内
+即刻 · V2EX · 掘金(长文讲架构)· 小红书/B站(发视觉 demo)· 公众号。
+
+---
+
+## 5. 两周执行排期(建议)
+
+**第一周 —— 上膛**
+- [ ] 敲定一句话定位(等留存用户反馈)
+- [ ] 修 P0:换 README hero 图
+- [ ] 录 60 秒 demo 视频(halo仔出脚本)
+- [ ] README 改版(多渠道 + 视觉提前)
+- [ ] 顺手申请 AWS Activate credits
+- [ ] 处理体检报告里的 P0/P1
+
+**第二周 —— 开火**
+- [ ] Show HN 首发(配 demo 视频)
+- [ ] 同步 Reddit r/LocalLLaMA + r/selfhosted
+- [ ] 启动 Twitter build-in-public
+- [ ] community.aws 技术稿(可延后)
+
+---
+
+## 6. 待咚咚总拍板
+
+1. **主线方向**:开源涨 star(build in public)还是商业化接客户?→ 建议先走开源,默认采纳。
+2. **主战场**:海外为主?→ 建议海外(人群密度),国内顺带。
+3. **那 2-3 个留存用户是啥人、最离不开哪个功能?** → 这个直接决定定位语怎么写。
+4. demo 视频你想自己录,还是要 halo仔先把素材/分镜全做好?