feat(context/runtime): 落地 manual compact（拆分自 #127）并补齐配置、TUI、事件与测试

.gitignore

@@ -31,6 +31,7 @@ config.local.yaml
 # Local data
 data/
 .cache/
+.neocode/projects/**/.transcripts/
 
 # Editor/IDE
 .idea/

AGENTS.md

@@ -75,6 +75,7 @@
 - 导出标识符使用 `PascalCase`，未导出使用 `camelCase`。
 - 使用制表符缩进，尽量将单行控制在约 120 字符内。
 - 核心抽象上的导出类型、函数、接口应补充清晰注释，尤其是 `provider`、`runtime`、`tools`。
+- 在非测试文件中新增函数时，必须紧邻函数定义补充便于解读的注释，注释内容使用中文并以 UTF-8 编码保存；注释应说明函数职责、关键行为或上下文，避免空泛的模板化表述。
 - 避免硬编码路径、URL、模型名、超时、输出长度限制和环境差异项，优先通过配置、参数或具名常量注入。
 - 避免硬编码业务语义字符串或状态值（例如消息角色、事件类型、协议字段值）；如需复用，优先收敛到共享常量、类型或统一定义处。
 - 优先写清晰、可替换的实现，不要为了“未来可能需要”提前引入复杂泛化。

README.md

@@ -186,3 +186,7 @@ NeoCode 已经集成了 GoReleaser 与 GitHub Actions 的全自动化 CI/CD 流
 ## License
 
 MIT
+
+## Manual Compact
+
+NeoCode 支持通过 `/compact` 手动压缩当前会话上下文。配置项见 `docs/guides/configuration.md`，流程和摘要约定见 `docs/context-compact.md`。

docs/context-compact.md

@@ -0,0 +1,91 @@
+# Context Compact
+
+本文档说明 NeoCode 中 manual compact 的配置、执行链路和摘要约定。
+
+## 概览
+
+- 当前仅支持手动触发的 compact，不包含自动 compact。
+- 用户通过 `/compact` 对当前会话执行一次上下文压缩。
+- compact 前会先写入完整 transcript，随后生成并校验 compact summary，再回写会话消息。
+
+## 配置
+
+compact 相关配置位于：
+
+```yaml
+context:
+  compact:
+    manual_strategy: keep_recent
+    manual_keep_recent_messages: 10
+    max_summary_chars: 1200
+```
+
+- `manual_strategy`
+  控制手动 compact 的策略，支持 `keep_recent` 和 `full_replace`。
+- `manual_keep_recent_messages`
+  在 `keep_recent` 模式下保留最近消息数量，并按 tool call 与 tool result 的原子块整体保留。
+- `max_summary_chars`
+  控制 compact summary 的最大字符数。
+
+## 执行链路
+
+1. TUI 识别 `/compact` 并调用 `runtime.Compact(...)`。
+2. runtime 发出 `compact_start` 事件。
+3. compact runner 将原始消息写入 transcript（JSONL）。
+4. compact runner 根据策略构造归档消息与保留消息。
+5. runtime 选择用于生成 summary 的 provider 和 model：
+   优先复用会话记录的 `provider` / `model`，缺失时回退到当前配置。
+6. summary generator 调用模型生成语义摘要。
+7. runner 校验摘要结构与长度，必要时截断。
+8. compact 成功时回写会话消息并发出 `compact_done`；失败时发出 `compact_error`。
+
+## 摘要协议
+
+compact summary 必须以如下结构返回：
+
+```text
+[compact_summary]
+
+done:
+- ...
+
+in_progress:
+- ...
+
+decisions:
+- ...
+
+code_changes:
+- ...
+
+constraints:
+- ...
+```
+
+- 必须包含固定起始标记 `[compact_summary]`。
+- 必须包含 `done`、`in_progress`、`decisions`、`code_changes`、`constraints` 五个 section。
+- 每个 section 至少包含一条非空 bullet。
+
+## 保留原则
+
+- 优先保留已完成事项及结果。
+- 保留仍在进行中的状态、关键决策及原因、关键代码改动、用户约束。
+- 默认忽略工具详细输出、重复背景、已解决错误的排查细节。
+
+## 事件
+
+manual compact 相关 runtime 事件包括：
+
+- `compact_start`
+- `compact_done`
+- `compact_error`
+
+`compact_done` payload 包含：
+
+- `applied`
+- `before_chars`
+- `after_chars`
+- `saved_ratio`
+- `trigger_mode`
+- `transcript_id`
+- `transcript_path`

docs/guides/configuration.md

@@ -302,3 +302,27 @@ echo $OPENAI_API_KEY
 ## 相关文档
 
 - [添加新 Provider](./adding-providers.md)
+
+## Context Compact
+
+以下配置用于控制手动上下文压缩行为。
+
+### 配置示例
+
+```yaml
+context:
+  compact:
+    manual_strategy: keep_recent
+    manual_keep_recent_messages: 10
+    max_summary_chars: 1200
+```
+
+### 字段说明
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `context.compact.manual_strategy` | string | `keep_recent` | 手动 `/compact` 策略，可选 `keep_recent` / `full_replace` |
+| `context.compact.manual_keep_recent_messages` | int | `10` | `keep_recent` 模式下保留最近 N 条消息；会按 tool call 与 tool result 的原子块整体保留 |
+| `context.compact.max_summary_chars` | int | `1200` | compact summary 最大字符数 |
+
+更多行为说明见 [context-compact.md](../context-compact.md)。

docs/neocode-coding-agent-mvp-architecture.md

@@ -1,3 +1,6 @@
+# ⚠️ 已过时：旧版 API 文档（DEPRECATED）
+
+
 # NeoCode Coding Agent MVP 架构设计
 
 ## 1. 目标

internal/app/bootstrap_test.go

@@ -49,7 +49,7 @@ func TestNewProgramNormalizesInvalidCurrentModelOnStartup(t *testing.T) {
 	}
 
 	configPath := filepath.Join(configDir, "config.yaml")
-	raw := []byte("selected_provider: openai\ncurrent_model: unsupported-current\nworkdir: .\nshell: powershell\n")
+	raw := []byte("selected_provider: openai\ncurrent_model: unsupported-current\nshell: powershell\n")
 	if err := os.WriteFile(configPath, raw, 0o644); err != nil {
 		t.Fatalf("write config: %v", err)
 	}