refactor(tui): migrate app into core and bootstrap wiring

AGENTS.md

@@ -15,7 +15,7 @@
 - 不要在 `runtime` 或 `tui` 里直接写工具执行逻辑；所有可被模型调用的能力必须进入 `internal/tools`。
 - 不要把会话状态、消息历史、工具调用记录散落到 UI；这些状态优先由 `runtime` 管理。
 - 不要把明文 API Key 写入 YAML、样例配置、测试快照或提交内容。
-- 修改 `config`、`provider`、`runtime`、`tools` 时，默认应同时评估并补充测试。
+- 修改 `config`、`provider`、`runtime`、`tools`、`context` 时，默认应同时评估并补充测试。
 
 ## 3. 代码结构与职责边界
 
@@ -24,16 +24,19 @@
 - `internal/app`：应用装配与 bootstrap，负责连接 config、provider、tools、runtime、tui。
 - `internal/config`：配置模型、YAML 加载、环境变量管理、配置校验和并发安全访问。
 - `internal/provider`：provider 抽象、领域模型和各厂商适配器。
-- `internal/runtime`：ReAct 主循环、事件流、Prompt 编排、Session 持久化。
+- `internal/runtime`：ReAct 主循环、事件流、Prompt 编排、token 累积与自动压缩触发。
+- `internal/session`：会话领域模型、存储抽象与 JSON 持久化实现。
 - `internal/tools`：工具契约、注册表、参数校验和具体工具实现。
 - `internal/tui`：Bubble Tea 状态机、渲染层、Slash Command 和事件桥接。
 - `docs`：架构、配置、事件流、会话持久化等说明文档。
 
 ### 3.2 模块职责
 - `app` 只负责装配和依赖注入，不承载业务规则。
-- `config` 负责 provider 列表、当前 provider、当前 model、workdir、shell 的管理和校验。
+- `config` 负责 provider 列表、当前 provider、当前 model、workdir、shell、context 压缩策略（含自动压缩阈值）的管理和校验。
 - `provider` 只处理模型协议差异、请求组装、响应解析、流式输出、超时与重试。
-- `runtime` 负责会话、消息上下文、tool schema 传递、tool call 识别、tool result 回灌和停止条件。
+- `context` 负责上下文构建（system prompt 组装、micro compact、消息裁剪）和自动压缩决策（基于 token 阈值判断是否需要压缩）。
+- `runtime` 负责会话编排、消息上下文流转、tool schema 传递、tool call 识别、tool result 回灌、token 累积、事件派发和停止条件。runtime 不替 context 做压缩决策。
+- `session` 负责会话领域模型与 JSON 持久化，包括 token 累计值的持久化。
 - `tools` 负责统一的 `schema + execute + result` 协议，以及参数校验、错误包装和输出格式收敛。
 - `tui` 只消费 runtime 事件并负责展示，不直接调用 provider，不直接执行 tools。
 
@@ -47,6 +50,7 @@
 
 ## 5. 测试规则
 - 测试文件命名为 `*_test.go`，测试函数命名为 `TestXxx`。
+- 所有改动必须以整体测试覆盖率 100% 为硬性目标；新增、修改或修复的逻辑必须同步补齐测试，覆盖正常路径、边界条件、异常分支、回归场景以及必要的跨模块交互，确保测试场景完整、结果可验证。
 - 优先覆盖以下边界：
   - 配置校验
   - provider 请求/响应转换
@@ -58,7 +62,16 @@
   - tool result 回灌
   - 最终响应输出
   - 错误事件派发
-- 修改 `tools` 时，重点覆盖：
+  - token 累积记录与事件发射
+  - 自动压缩触发与重置逻辑
+- 修改 `context` 时，重点覆盖：
+  - Build 输入输出契约（含 Metadata 新字段、ShouldAutoCompact 决策）
+  - micro compact 策略
+  - 消息裁剪边界
+  - AGENTS.md 加载与截断
+- 修改 `config` 时，重点覆盖：
+  - 新增配置项的校验、默认值和序列化/反序列化
+  - 配置加载向后兼容（新字段 omitempty）
   - schema 校验
   - 超时控制
   - 错误包装
@@ -101,6 +114,7 @@
 - 确认改动没有破坏 `TUI / Runtime / Provider / Tools / Config` 的职责分工。
 - 确认新增能力已经接到正确层级，而不是临时跨层实现。
 - 运行必要的格式化和测试。
+- 确认本次改动对应的测试已补齐，并满足整体测试覆盖率 100% 目标，不得遗漏关键路径、边界分支和回归场景。
 - 检查 `git status`，确保没有无关文件、密钥、本地配置或临时数据混入。
 
 ## 10. 常用命令

README.md

@@ -192,3 +192,19 @@ MIT
 ## Manual Compact
 
 NeoCode 支持通过 `/compact` 手动压缩当前会话上下文。配置项见 `docs/guides/configuration.md`，流程和摘要约定见 `docs/context-compact.md`。
+
+## CLI Workdir
+
+NeoCode 现在支持通过 CLI 启动参数覆盖本次运行工作区：
+
+```bash
+go run ./cmd/neocode --workdir /path/to/workspace
+```
+
+说明：
+
+- `--workdir` 只影响当前进程，不会写回 `config.yaml`
+- 当前工作区会同时用于工具执行根目录与 session 存储分桶
+- session 历史现在按工作区隔离存储，不同工作区默认互不可见
+
+[![Contributors](https://hub-io-mcells-projects.vercel.app/r/1024XEngineer/neo-code)](https://github.com/1024XEngineer/neo-code/graphs/contributors)

cmd/neocode/main.go

@@ -5,17 +5,11 @@ import (
 	"fmt"
 	"os"
 
-	"neo-code/internal/app"
+	"neo-code/internal/cli"
 )
 
 func main() {
-	program, err := app.NewProgram(context.Background())
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "neocode: %v\n", err)
-		os.Exit(1)
-	}
-
-	if _, err := program.Run(); err != nil {
+	if err := cli.Execute(context.Background()); err != nil {
 		fmt.Fprintf(os.Stderr, "neocode: %v\n", err)
 		os.Exit(1)
 	}

docs/context-compact.md

@@ -4,8 +4,8 @@
 
 ## 概览
 
-- runtime 当前仅接入手动触发的 compact，不包含自动 compact。
-- `internal/context/compact` 已支持 `manual` 与 `reactive` 两种 mode，供 runtime 后续在 provider 上下文过长错误场景接入调用。
+- runtime 已接入手动 compact、基于 token 阈值的自动 compact，以及 provider 上下文过长后的 `reactive` compact 自动恢复。
+- `internal/context/compact` 支持 `manual` 与 `reactive` 两种 mode。
 - 用户通过 `/compact` 对当前会话执行一次上下文压缩。
 - compact 前会先写入完整 transcript，随后生成并校验 compact summary，再回写会话消息。
 
@@ -20,6 +20,9 @@ context:
     manual_keep_recent_messages: 10
     max_summary_chars: 1200
     micro_compact_disabled: false
+  auto_compact:
+    enabled: false
+    input_token_threshold: 100000
 ```
 
 - `manual_strategy`
@@ -30,6 +33,19 @@ context:
   控制 compact summary 的最大字符数。
 - `micro_compact_disabled`
   控制是否关闭默认启用的读时 micro compact；设为 `true` 时会回退为仅 trim、不清理旧 tool result。
+- `auto_compact.enabled`
+  控制是否启用基于 token 阈值的自动压缩；默认关闭。
+- `auto_compact.input_token_threshold`
+  当会话累计输入 token 数达到此阈值时触发自动压缩；默认 100000。
+
+## 自动压缩
+
+当 `auto_compact.enabled` 为 `true` 时，runtime 在每次调用 `context.Builder.Build()` 时将当前 token 累计值传入 Metadata，context 模块通过比较累计值与阈值在 `BuildResult.ShouldAutoCompact` 中返回压缩建议。runtime 读取建议后调用现有 compact 管线执行压缩，并在成功后重置 token 计数器。
+
+设计原则：
+- **context 拥有压缩决策权**，runtime 只做编排执行。
+- 每次 `Run()` 调用最多触发一次自动压缩，避免无限循环。
+- 压缩成功后 token 计数器重置为零，下一轮不会立即重复触发。
 
 新增工具时，micro compact 策略不再由 `context` 层静态白名单维护，而是由 `internal/tools` 中的工具实现声明。
 默认情况下，已注册工具都会参与 micro compact；只有显式声明保留历史结果的工具才会跳过旧结果清理。
@@ -53,7 +69,12 @@ context:
 3. 生成并校验 `[compact_summary]`。
 4. 返回压缩后的消息与 transcript 元信息。
 
-当前 runtime 主链尚未自动调用 `reactive` mode；后续接入时可继续复用现有 compact 事件，并通过 `trigger_mode=reactive` 区分。
+当 provider 返回“上下文过长”错误时，runtime 会：
+
+1. 识别 provider 归一化后的 typed error，必要时回退到错误文本匹配。
+2. 触发一次 `compact.Run(mode=reactive)`。
+3. 继续复用 `compact_start`、`compact_done`、`compact_error` 事件，并通过 `trigger_mode=reactive` 区分来源。
+4. 每次 `Run()` 最多只执行一次 reactive 重试，避免无限循环。
 
 ## 摘要协议
 
@@ -90,7 +111,7 @@ constraints:
 
 ## 事件
 
-manual compact 相关 runtime 事件包括：
+compact 相关 runtime 事件包括：
 
 - `compact_start`
 - `compact_done`

docs/guides/configuration.md

@@ -330,3 +330,17 @@ context:
 新增工具默认会参与 micro compact；如果某个工具的历史结果必须保留，需要在 `internal/tools` 的工具实现中显式声明保留策略。
 
 更多行为说明见 [context-compact.md](../context-compact.md)。
+
+## CLI 工作区覆盖
+
+NeoCode 支持在启动时通过 CLI 参数覆盖当前运行工作区：
+
+```bash
+go run ./cmd/neocode --workdir /path/to/workspace
+```
+
+补充说明：
+
+- `--workdir` 只影响本次启动，不会持久化到 `config.yaml`
+- 运行时工具根目录与 session 存储分桶都会使用该工作区
+- session 现按工作区隔离存储，不同工作区的历史会话默认互不可见

docs/runtime-provider-event-flow.md

@@ -9,6 +9,10 @@
 - `tool_start`
 - `tool_result`
 - `error`
+- `token_usage`
+- `compact_start`
+- `compact_done`
+- `compact_error`
 
 ## ReAct 主循环
 
@@ -17,10 +21,12 @@
 3. 读取最新配置快照。
 4. 解析当前 provider 配置并构建 provider 实例。
 5. 调用 `context.Builder` 生成本轮请求使用的 `system prompt` 和消息上下文。
-6. 调用 `Provider.Chat`，并把流式事件桥接给 TUI。
-7. 保存 assistant 完整回复。
-8. 执行返回的工具调用，并保存每一个工具结果。
-9. 如果仍需继续推理，则进入下一轮；否则结束。
+6. 如命中 token 阈值自动压缩建议，则先执行一次 compact，再继续构造请求。
+7. 调用 `Provider.Chat`，并把流式事件桥接给 TUI。
+8. 如 provider 返回“上下文过长”错误，则触发一次 `reactive` compact，并仅重试一次当前请求。
+9. 保存 assistant 完整回复。
+10. 执行返回的工具调用，并保存每一个工具结果。
+11. 如果仍需继续推理，则进入下一轮；否则结束。
 
 ### Context Builder 输入与职责
 
@@ -30,11 +36,15 @@
   - `shell`
   - 当前 `provider`
   - 当前 `model`
+  - 会话累计输入 token 数（`SessionInputTokens`）
+  - 会话累计输出 token 数（`SessionOutputTokens`）
+  - 自动压缩阈值（`AutoCompactThreshold`）
 - `context.Builder` 负责统一组装：
   - 固定核心 system prompt sections
   - 从 `workdir` 向上发现的 `AGENTS.md`
   - 系统状态摘要（`workdir` / `shell` / `provider` / `model` / git branch / git dirty）
   - 裁剪后的历史消息
+  - 自动压缩决策（`BuildResult.ShouldAutoCompact`）
 - `runtime` 不直接读取规则文件，也不直接查询 git 状态。
 - `provider` 只消费最终生成的 `SystemPrompt`、消息列表和工具 schema，不感知上下文来源。
 
@@ -59,6 +69,17 @@
 - runtime 将其转换成 `RuntimeEvent`
 - TUI 使用 Bubble Tea `Cmd` 监听事件，并在处理完成后继续订阅
 
+## Token 计量
+
+runtime 在转发 provider 流式事件时，从 `MessageDone` 事件中提取 `Usage`（`InputTokens`、`OutputTokens`），累积到会话级计数器，并发出 `token_usage` 事件供 TUI 消费。
+
+`token_usage` payload 包含：
+
+- `input_tokens`：本次调用输入 token
+- `output_tokens`：本次调用输出 token
+- `session_input_tokens`：会话累计输入 token
+- `session_output_tokens`：会话累计输出 token
+
 ## 持久化时机
 
 - 用户消息提交后保存

docs/session-persistence-design.md

@@ -9,9 +9,16 @@
 NeoCode 在 MVP 阶段使用 JSON 文件持久化 Session，以保持本地优先、易于调试和跨平台可移植。
 
 ## 数据模型
-- `Session`：完整消息历史以及 `id`、`title`、`updated_at` 等元信息
+- `Session`：完整消息历史以及 `id`、`title`、`updated_at`、`token_input_total`、`token_output_total` 等元信息
 - `Summary`：用于侧边栏的轻量摘要结构（原 `SessionSummary` 命名已统一收口为 `Summary`）
 
+### Token 持久化
+- `token_input_total` 和 `token_output_total` 分别记录会话累计输入和输出 token。
+- 使用 `omitempty` 标签，确保旧版 JSON 文件正常加载（零值不序列化）。
+- runtime 在每次 provider 调用后更新 session 的 token 字段，随 session save 一起持久化。
+- 会话加载时，runtime 从 session 恢复 token 计数器；新建会话时计数器清零。
+- 自动压缩成功后 token 计数器重置为零，并持久化到 session。
+
 ## 加载策略
 - `ListSummaries` 只读取渲染侧边栏所需的基础信息
 - `Load` 仅在用户真正进入某个会话时读取完整消息历史
@@ -28,3 +35,10 @@ NeoCode 在 MVP 阶段使用 JSON 文件持久化 Session，以保持本地优
 ## 兼容性与演进说明
 - 会话持久化能力已从 runtime 侧实现中彻底收口到 `internal/session`
 - 新增会话存储实现时，应优先在 `internal/session` 内扩展并通过接口注入 runtime，避免跨层实现
+
+## 工作区隔离
+
+- session 现按工作区隔离存储，目录规则为 `~/.neocode/projects/<workspace-hash>/sessions/`
+- 工作区哈希基于启动时确定的工作区根目录生成，而不是基于 `session.Workdir`
+- `session.Workdir` 仍表示该会话当前实际执行命令时使用的目录，可被 `/cwd` 修改
+- 旧的全局 `~/.neocode/sessions/` 开发期数据不迁移、不回读

go.mod

@@ -3,33 +3,37 @@ module neo-code
 go 1.25.0
 
 require (
+	github.com/atotto/clipboard v0.1.4
 	github.com/charmbracelet/bubbles v1.0.0
 	github.com/charmbracelet/bubbletea v1.3.10
+	github.com/charmbracelet/glamour v1.0.0
 	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834
-	github.com/joho/godotenv v1.5.1
+	github.com/spf13/cobra v1.10.2
+	github.com/spf13/viper v1.21.0
 	golang.org/x/net v0.52.0
+	golang.org/x/sys v0.42.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
 require (
 	github.com/alecthomas/chroma/v2 v2.20.0 // indirect
-	github.com/atotto/clipboard v0.1.4 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/aymerick/douceur v0.2.0 // indirect
 	github.com/charmbracelet/colorprofile v0.4.3 // indirect
-	github.com/charmbracelet/glamour v1.0.0 // indirect
 	github.com/charmbracelet/harmonica v0.2.0 // indirect
 	github.com/charmbracelet/x/ansi v0.11.6 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
 	github.com/charmbracelet/x/exp/slice v0.0.0-20250327172914-2fdc97757edf // indirect
 	github.com/charmbracelet/x/term v0.2.2 // indirect
 	github.com/clipperhouse/displaywidth v0.11.0 // indirect
-	github.com/clipperhouse/stringish v0.1.1 // indirect
 	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
 	github.com/dlclark/regexp2 v1.11.5 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
+	github.com/fsnotify/fsnotify v1.9.0 // indirect
+	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
 	github.com/gorilla/css v1.0.1 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
@@ -39,12 +43,19 @@ require (
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/reflow v0.3.0 // indirect
 	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/sagikazarmark/locafero v0.11.0 // indirect
 	github.com/sahilm/fuzzy v0.1.1 // indirect
+	github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect
+	github.com/spf13/afero v1.15.0 // indirect
+	github.com/spf13/cast v1.10.0 // indirect
+	github.com/spf13/pflag v1.0.10 // indirect
+	github.com/subosito/gotenv v1.6.0 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/yuin/goldmark v1.7.13 // indirect
 	github.com/yuin/goldmark-emoji v1.0.6 // indirect
-	golang.org/x/sys v0.42.0 // indirect
+	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	golang.org/x/term v0.41.0 // indirect
 	golang.org/x/text v0.35.0 // indirect
 )